/* * Copyright 2002-2018 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.springframework.jdbc.object; import java.sql.ResultSet; import java.sql.Types; import java.util.Arrays; import java.util.Collections; import java.util.LinkedList; import java.util.List; import java.util.Map; import javax.sql.DataSource; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; import org.springframework.beans.factory.InitializingBean; import org.springframework.dao.InvalidDataAccessApiUsageException; import org.springframework.jdbc.core.JdbcTemplate; import org.springframework.jdbc.core.SqlParameter; import org.springframework.lang.Nullable; import org.springframework.util.Assert; /** * An "RDBMS operation" is a multi-threaded, reusable object representing a query, * update, or stored procedure call. An RDBMS operation is not a command, * as a command is not reusable. However, execute methods may take commands as * arguments. Subclasses should be JavaBeans, allowing easy configuration. * *
This class and subclasses throw runtime exceptions, defined in the * {@code org.springframework.dao} package (and as thrown by the * {@code org.springframework.jdbc.core} package, which the classes * in this package use under the hood to perform raw JDBC operations). * *
Subclasses should set SQL and add parameters before invoking the
* {@link #compile()} method. The order in which parameters are added is
* significant. The appropriate {@code execute} or {@code update}
* method can then be invoked.
*
* @author Rod Johnson
* @author Juergen Hoeller
* @see SqlQuery
* @see SqlUpdate
* @see StoredProcedure
* @see org.springframework.jdbc.core.JdbcTemplate
*/
public abstract class RdbmsOperation implements InitializingBean {
/** Logger available to subclasses. */
protected final Log logger = LogFactory.getLog(getClass());
/** Lower-level class used to execute SQL. */
private JdbcTemplate jdbcTemplate = new JdbcTemplate();
private int resultSetType = ResultSet.TYPE_FORWARD_ONLY;
private boolean updatableResults = false;
private boolean returnGeneratedKeys = false;
@Nullable
private String[] generatedKeysColumnNames;
@Nullable
private String sql;
private final List Default is -1, indicating to use the driver's default.
* @see org.springframework.jdbc.core.JdbcTemplate#setFetchSize
*/
public void setFetchSize(int fetchSize) {
this.jdbcTemplate.setFetchSize(fetchSize);
}
/**
* Set the maximum number of rows for this RDBMS operation. This is important
* for processing subsets of large result sets, avoiding to read and hold
* the entire result set in the database or in the JDBC driver.
* Default is -1, indicating to use the driver's default.
* @see org.springframework.jdbc.core.JdbcTemplate#setMaxRows
*/
public void setMaxRows(int maxRows) {
this.jdbcTemplate.setMaxRows(maxRows);
}
/**
* Set the query timeout for statements that this RDBMS operation executes.
* Default is -1, indicating to use the JDBC driver's default.
* Note: Any timeout specified here will be overridden by the remaining
* transaction timeout when executing within a transaction that has a
* timeout specified at the transaction level.
*/
public void setQueryTimeout(int queryTimeout) {
this.jdbcTemplate.setQueryTimeout(queryTimeout);
}
/**
* Set whether to use statements that return a specific type of ResultSet.
* @param resultSetType the ResultSet type
* @see java.sql.ResultSet#TYPE_FORWARD_ONLY
* @see java.sql.ResultSet#TYPE_SCROLL_INSENSITIVE
* @see java.sql.ResultSet#TYPE_SCROLL_SENSITIVE
* @see java.sql.Connection#prepareStatement(String, int, int)
*/
public void setResultSetType(int resultSetType) {
this.resultSetType = resultSetType;
}
/**
* Return whether statements will return a specific type of ResultSet.
*/
public int getResultSetType() {
return this.resultSetType;
}
/**
* Set whether to use statements that are capable of returning
* updatable ResultSets.
* @see java.sql.Connection#prepareStatement(String, int, int)
*/
public void setUpdatableResults(boolean updatableResults) {
if (isCompiled()) {
throw new InvalidDataAccessApiUsageException(
"The updateableResults flag must be set before the operation is compiled");
}
this.updatableResults = updatableResults;
}
/**
* Return whether statements will return updatable ResultSets.
*/
public boolean isUpdatableResults() {
return this.updatableResults;
}
/**
* Set whether prepared statements should be capable of returning
* auto-generated keys.
* @see java.sql.Connection#prepareStatement(String, int)
*/
public void setReturnGeneratedKeys(boolean returnGeneratedKeys) {
if (isCompiled()) {
throw new InvalidDataAccessApiUsageException(
"The returnGeneratedKeys flag must be set before the operation is compiled");
}
this.returnGeneratedKeys = returnGeneratedKeys;
}
/**
* Return whether statements should be capable of returning
* auto-generated keys.
*/
public boolean isReturnGeneratedKeys() {
return this.returnGeneratedKeys;
}
/**
* Set the column names of the auto-generated keys.
* @see java.sql.Connection#prepareStatement(String, String[])
*/
public void setGeneratedKeysColumnNames(@Nullable String... names) {
if (isCompiled()) {
throw new InvalidDataAccessApiUsageException(
"The column names for the generated keys must be set before the operation is compiled");
}
this.generatedKeysColumnNames = names;
}
/**
* Return the column names of the auto generated keys.
*/
@Nullable
public String[] getGeneratedKeysColumnNames() {
return this.generatedKeysColumnNames;
}
/**
* Set the SQL executed by this operation.
*/
public void setSql(@Nullable String sql) {
this.sql = sql;
}
/**
* Subclasses can override this to supply dynamic SQL if they wish, but SQL is
* normally set by calling the {@link #setSql} method or in a subclass constructor.
*/
@Nullable
public String getSql() {
return this.sql;
}
/**
* Resolve the configured SQL for actual use.
* @return the SQL (never {@code null})
* @since 5.0
*/
protected String resolveSql() {
String sql = getSql();
Assert.state(sql != null, "No SQL set");
return sql;
}
/**
* Add anonymous parameters, specifying only their SQL types
* as defined in the {@code java.sql.Types} class.
* Parameter ordering is significant. This method is an alternative
* to the {@link #declareParameter} method, which should normally be preferred.
* @param types array of SQL types as defined in the
* {@code java.sql.Types} class
* @throws InvalidDataAccessApiUsageException if the operation is already compiled
*/
public void setTypes(@Nullable int[] types) throws InvalidDataAccessApiUsageException {
if (isCompiled()) {
throw new InvalidDataAccessApiUsageException("Cannot add parameters once query is compiled");
}
if (types != null) {
for (int type : types) {
declareParameter(new SqlParameter(type));
}
}
}
/**
* Declare a parameter for this operation.
* The order in which this method is called is significant when using
* positional parameters. It is not significant when using named parameters
* with named SqlParameter objects here; it remains significant when using
* named parameters in combination with unnamed SqlParameter objects here.
* @param param the SqlParameter to add. This will specify SQL type and (optionally)
* the parameter's name. Note that you typically use the {@link SqlParameter} class
* itself here, not any of its subclasses.
* @throws InvalidDataAccessApiUsageException if the operation is already compiled,
* and hence cannot be configured further
*/
public void declareParameter(SqlParameter param) throws InvalidDataAccessApiUsageException {
if (isCompiled()) {
throw new InvalidDataAccessApiUsageException("Cannot add parameters once the query is compiled");
}
this.declaredParameters.add(param);
}
/**
* Add one or more declared parameters. Used for configuring this operation
* when used in a bean factory. Each parameter will specify SQL type and (optionally)
* the parameter's name.
* @param parameters an array containing the declared {@link SqlParameter} objects
* @see #declaredParameters
*/
public void setParameters(SqlParameter... parameters) {
if (isCompiled()) {
throw new InvalidDataAccessApiUsageException("Cannot add parameters once the query is compiled");
}
for (int i = 0; i < parameters.length; i++) {
if (parameters[i] != null) {
this.declaredParameters.add(parameters[i]);
}
else {
throw new InvalidDataAccessApiUsageException("Cannot add parameter at index " + i + " from " +
Arrays.asList(parameters) + " since it is 'null'");
}
}
}
/**
* Return a list of the declared {@link SqlParameter} objects.
*/
protected List Automatically called by {@code validateParameters}.
* @see #validateParameters
*/
protected void checkCompiled() {
if (!isCompiled()) {
logger.debug("SQL operation not compiled before execution - invoking compile");
compile();
}
}
/**
* Validate the parameters passed to an execute method based on declared parameters.
* Subclasses should invoke this method before every {@code executeQuery()}
* or {@code update()} method.
* @param parameters parameters supplied (may be {@code null})
* @throws InvalidDataAccessApiUsageException if the parameters are invalid
*/
protected void validateParameters(@Nullable Object[] parameters) throws InvalidDataAccessApiUsageException {
checkCompiled();
int declaredInParameters = 0;
for (SqlParameter param : this.declaredParameters) {
if (param.isInputValueProvided()) {
if (!supportsLobParameters() &&
(param.getSqlType() == Types.BLOB || param.getSqlType() == Types.CLOB)) {
throw new InvalidDataAccessApiUsageException(
"BLOB or CLOB parameters are not allowed for this kind of operation");
}
declaredInParameters++;
}
}
validateParameterCount((parameters != null ? parameters.length : 0), declaredInParameters);
}
/**
* Validate the named parameters passed to an execute method based on declared parameters.
* Subclasses should invoke this method before every {@code executeQuery()} or
* {@code update()} method.
* @param parameters parameter Map supplied (may be {@code null})
* @throws InvalidDataAccessApiUsageException if the parameters are invalid
*/
protected void validateNamedParameters(@Nullable Map Subclasses can assume that SQL and a DataSource have been supplied.
* @throws InvalidDataAccessApiUsageException if the subclass hasn't been
* properly configured
*/
protected abstract void compileInternal() throws InvalidDataAccessApiUsageException;
/**
* Return whether BLOB/CLOB parameters are supported for this kind of operation.
* The default is {@code true}.
*/
protected boolean supportsLobParameters() {
return true;
}
/**
* Return whether this operation accepts additional parameters that are
* given but not actually used. Applies in particular to parameter Maps.
* The default is {@code false}.
* @see StoredProcedure
*/
protected boolean allowsUnusedParameters() {
return false;
}
}