Package org.springframework.jdbc.core.simple

# Class SimpleJdbcInsert

java.lang.Object
org.springframework.jdbc.core.simple.AbstractJdbcInsert
org.springframework.jdbc.core.simple.SimpleJdbcInsert

All Implemented Interfaces:
  `SimpleJdbcInsertOperations`

public class SimpleJdbcInsert extends AbstractJdbcInsert implements SimpleJdbcInsertOperations
A `SimpleJdbcInsert` is a multi-threaded, reusable object providing easy (batch) insert capabilities for a table. It provides meta-data processing to simplify the code needed to construct a basic insert statement. All you need to provide is the name of the table and a `Map` containing the column names and the column values.

The meta-data processing is based on the `DatabaseMetaData` provided by the JDBC driver. As long as the JDBC driver can provide the names of the columns for a specified table then we can rely on this auto-detection feature. If that is not the case, then the column names must be specified explicitly.

The actual (batch) insert is handled using Spring's `JdbcTemplate`.

Many of the configuration methods return the current instance of the `SimpleJdbcInsert` to provide the ability to chain multiple ones together in a "fluent" API style.

Since:
  2.5
Author:
  Thomas Risberg, Juergen Hoeller, Sam Brannen
See Also:
  - `DatabaseMetaData`
  - `JdbcTemplate`

## Field Summary

### Fields inherited from class org.springframework.jdbc.core.simple.AbstractJdbcInsert

`logger`

## Constructor Summary

Constructors
Constructor
Description
`SimpleJdbcInsert(DataSource dataSource)`
Constructor that accepts the JDBC `DataSource` to use when creating the `JdbcTemplate`.
`SimpleJdbcInsert(JdbcTemplate jdbcTemplate)`
Alternative constructor that accepts the `JdbcTemplate` to be used.

## Method Summary

Modifier and Type
Method
Description
`int`
`execute(Map<String,?> args)`
Execute the insert using the values passed in.
`int`
`execute(SqlParameterSource parameterSource)`
Execute the insert using the values passed in.
`Number`
`executeAndReturnKey(Map<String,?> args)`
Execute the insert using the values passed in and return the generated key.
`Number`
`executeAndReturnKey(SqlParameterSource parameterSource)`
Execute the insert using the values passed in and return the generated key.
`KeyHolder`
`executeAndReturnKeyHolder(Map<String,?> args)`
Execute the insert using the values passed in and return the generated keys.
`KeyHolder`
`executeAndReturnKeyHolder(SqlParameterSource parameterSource)`
Execute the insert using the values passed in and return the generated keys.
`int[]`
`executeBatch(Map<String,?>... batch)`
Execute a batch insert using the batch of values passed in.
`int[]`
`executeBatch(SqlParameterSource... batch)`
Execute a batch insert using the batch of values passed in.
`SimpleJdbcInsert`
`includeSynonymsForTableColumnMetaData()`
Include synonyms for the column meta-data lookups via JDBC.
`SimpleJdbcInsert`
`usingColumns(String... columnNames)`
Specify the column names that the insert statement should be limited to use.
`SimpleJdbcInsert`
`usingGeneratedKeyColumns(String... columnNames)`
Specify the names of any columns that have auto-generated keys.
`SimpleJdbcInsert`
`usingQuotedIdentifiers()`
Specify that SQL identifiers should be quoted.
`SimpleJdbcInsert`
`withCatalogName(String catalogName)`
Specify the catalog name, if any, to be used for the insert.
`SimpleJdbcInsert`
`withoutTableColumnMetaDataAccess()`
Turn off any processing of column meta-data information obtained via JDBC.
`SimpleJdbcInsert`
`withSchemaName(String schemaName)`
Specify the schema name, if any, to be used for the insert.
`SimpleJdbcInsert`
`withTableName(String tableName)`
Specify the table name to be used for the insert.

### Methods inherited from class org.springframework.jdbc.core.simple.AbstractJdbcInsert

`checkCompiled, checkIfConfigurationModificationIsAllowed, compile, compileInternal, doExecute, doExecute, doExecuteAndReturnKey, doExecuteAndReturnKey, doExecuteAndReturnKeyHolder, doExecuteAndReturnKeyHolder, doExecuteBatch, doExecuteBatch, getCatalogName, getColumnNames, getGeneratedKeyNames, getInsertString, getInsertTypes, getJdbcTemplate, getSchemaName, getTableName, isCompiled, isQuoteIdentifiers, matchInParameterValuesWithInsertColumns, matchInParameterValuesWithInsertColumns, onCompileInternal, setAccessTableColumnMetaData, setCatalogName, setColumnNames, setGeneratedKeyName, setGeneratedKeyNames, setOverrideIncludeSynonymsDefault, setQuoteIdentifiers, setSchemaName, setTableName`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### SimpleJdbcInsert

public SimpleJdbcInsert(DataSource dataSource)
Constructor that accepts the JDBC `DataSource` to use when creating the `JdbcTemplate`.

Parameters:
  `dataSource` - the `DataSource` to use
See Also:
  - `JdbcAccessor.setDataSource(javax.sql.DataSource)`

### SimpleJdbcInsert

public SimpleJdbcInsert(JdbcTemplate jdbcTemplate)
Alternative constructor that accepts the `JdbcTemplate` to be used.

Parameters:
  `jdbcTemplate` - the `JdbcTemplate` to use
See Also:
  - `JdbcAccessor.setDataSource(javax.sql.DataSource)`

## Method Details

### withTableName

public SimpleJdbcInsert withTableName(String tableName)
Description copied from interface: `SimpleJdbcInsertOperations`
Specify the table name to be used for the insert.

Specified by:
  `withTableName` in interface `SimpleJdbcInsertOperations`
Parameters:
  `tableName` - the name of the stored table
Returns:
  this `SimpleJdbcInsert` (for method chaining)

### withSchemaName

public SimpleJdbcInsert withSchemaName(String schemaName)
Description copied from interface: `SimpleJdbcInsertOperations`
Specify the schema name, if any, to be used for the insert.

Specified by:
  `withSchemaName` in interface `SimpleJdbcInsertOperations`
Parameters:
  `schemaName` - the name of the schema
Returns:
  this `SimpleJdbcInsert` (for method chaining)

### withCatalogName

public SimpleJdbcInsert withCatalogName(String catalogName)
Description copied from interface: `SimpleJdbcInsertOperations`
Specify the catalog name, if any, to be used for the insert.

Specified by:
  `withCatalogName` in interface `SimpleJdbcInsertOperations`
Parameters:
  `catalogName` - the name of the catalog
Returns:
  this `SimpleJdbcInsert` (for method chaining)

### usingColumns

public SimpleJdbcInsert usingColumns(String... columnNames)
Description copied from interface: `SimpleJdbcInsertOperations`
Specify the column names that the insert statement should be limited to use.

Specified by:
  `usingColumns` in interface `SimpleJdbcInsertOperations`
Parameters:
  `columnNames` - one or more column names
Returns:
  this `SimpleJdbcInsert` (for method chaining)

### usingGeneratedKeyColumns

public SimpleJdbcInsert usingGeneratedKeyColumns(String... columnNames)
Description copied from interface: `SimpleJdbcInsertOperations`
Specify the names of any columns that have auto-generated keys.

Specified by:
  `usingGeneratedKeyColumns` in interface `SimpleJdbcInsertOperations`
Parameters:
  `columnNames` - one or more column names
Returns:
  this `SimpleJdbcInsert` (for method chaining)

### usingQuotedIdentifiers

public SimpleJdbcInsert usingQuotedIdentifiers()
Description copied from interface: `SimpleJdbcInsertOperations`
Specify that SQL identifiers should be quoted.

If this method is invoked, the identifier quote string for the underlying database will be used to quote SQL identifiers in generated SQL statements. In this context, SQL identifiers refer to schema, table, and column names.

When identifiers are quoted, explicit column names must be supplied via `SimpleJdbcInsertOperations.usingColumns(String...)`. Furthermore, all identifiers for the schema name, table name, and column names must match the corresponding identifiers in the database's metadata regarding casing (mixed case, uppercase, or lowercase).

Specified by:
  `usingQuotedIdentifiers` in interface `SimpleJdbcInsertOperations`
Returns:
  this `SimpleJdbcInsert` (for method chaining)
See Also:
  - `SimpleJdbcInsertOperations.withSchemaName(String)`
  - `SimpleJdbcInsertOperations.withTableName(String)`
  - `SimpleJdbcInsertOperations.usingColumns(String...)`
  - `DatabaseMetaData.getIdentifierQuoteString()`
  - `DatabaseMetaData.storesMixedCaseIdentifiers()`
  - `DatabaseMetaData.storesMixedCaseQuotedIdentifiers()`
  - `DatabaseMetaData.storesUpperCaseIdentifiers()`
  - `DatabaseMetaData.storesUpperCaseQuotedIdentifiers()`
  - `DatabaseMetaData.storesLowerCaseIdentifiers()`
  - `DatabaseMetaData.storesLowerCaseQuotedIdentifiers()`

### withoutTableColumnMetaDataAccess

public SimpleJdbcInsert withoutTableColumnMetaDataAccess()
Description copied from interface: `SimpleJdbcInsertOperations`
Turn off any processing of column meta-data information obtained via JDBC.

Specified by:
  `withoutTableColumnMetaDataAccess` in interface `SimpleJdbcInsertOperations`
Returns:
  this `SimpleJdbcInsert` (for method chaining)

### includeSynonymsForTableColumnMetaData

public SimpleJdbcInsert includeSynonymsForTableColumnMetaData()
Description copied from interface: `SimpleJdbcInsertOperations`
Include synonyms for the column meta-data lookups via JDBC.

Note: This is only necessary to include for Oracle since other databases supporting synonyms seem to include the synonyms automatically.

Specified by:
  `includeSynonymsForTableColumnMetaData` in interface `SimpleJdbcInsertOperations`
Returns:
  this `SimpleJdbcInsert` (for method chaining)

### execute

public int execute(Map<String,?> args)
Description copied from interface: `SimpleJdbcInsertOperations`
Execute the insert using the values passed in.

Specified by:
  `execute` in interface `SimpleJdbcInsertOperations`
Parameters:
  `args` - a Map containing column names and corresponding value
Returns:
  the number of rows affected as returned by the JDBC driver

### execute

public int execute(SqlParameterSource parameterSource)
Description copied from interface: `SimpleJdbcInsertOperations`
Execute the insert using the values passed in.

Specified by:
  `execute` in interface `SimpleJdbcInsertOperations`
Parameters:
  `parameterSource` - the SqlParameterSource containing values to use for insert
Returns:
  the number of rows affected as returned by the JDBC driver

### executeAndReturnKey

public Number executeAndReturnKey(Map<String,?> args)
Description copied from interface: `SimpleJdbcInsertOperations`
Execute the insert using the values passed in and return the generated key.

This requires that the name of the columns with auto generated keys have been specified. This method will always return a KeyHolder but the caller must verify that it actually contains the generated keys.

Specified by:
  `executeAndReturnKey` in interface `SimpleJdbcInsertOperations`
Parameters:
  `args` - a Map containing column names and corresponding value
Returns:
  the generated key value

### executeAndReturnKey

public Number executeAndReturnKey(SqlParameterSource parameterSource)
Description copied from interface: `SimpleJdbcInsertOperations`
Execute the insert using the values passed in and return the generated key.

This requires that the name of the columns with auto generated keys have been specified. This method will always return a KeyHolder but the caller must verify that it actually contains the generated keys.

Specified by:
  `executeAndReturnKey` in interface `SimpleJdbcInsertOperations`
Parameters:
  `parameterSource` - the SqlParameterSource containing values to use for insert
Returns:
  the generated key value.

### executeAndReturnKeyHolder

public KeyHolder executeAndReturnKeyHolder(Map<String,?> args)
Description copied from interface: `SimpleJdbcInsertOperations`
Execute the insert using the values passed in and return the generated keys.

This requires that the name of the columns with auto generated keys have been specified. This method will always return a KeyHolder but the caller must verify that it actually contains the generated keys.

Specified by:
  `executeAndReturnKeyHolder` in interface `SimpleJdbcInsertOperations`
Parameters:
  `args` - a Map containing column names and corresponding value
Returns:
  the KeyHolder containing all generated keys

### executeAndReturnKeyHolder

public KeyHolder executeAndReturnKeyHolder(SqlParameterSource parameterSource)
Description copied from interface: `SimpleJdbcInsertOperations`
Execute the insert using the values passed in and return the generated keys.

This requires that the name of the columns with auto generated keys have been specified. This method will always return a KeyHolder but the caller must verify that it actually contains the generated keys.

Specified by:
  `executeAndReturnKeyHolder` in interface `SimpleJdbcInsertOperations`
Parameters:
  `parameterSource` - the SqlParameterSource containing values to use for insert
Returns:
  the KeyHolder containing all generated keys

### executeBatch

public int[] executeBatch(Map<String,?>... batch)
Description copied from interface: `SimpleJdbcInsertOperations`
Execute a batch insert using the batch of values passed in.

Specified by:
  `executeBatch` in interface `SimpleJdbcInsertOperations`
Parameters:
  `batch` - an array of Maps containing a batch of column names and corresponding value
Returns:
  the array of number of rows affected as returned by the JDBC driver

### executeBatch

public int[] executeBatch(SqlParameterSource... batch)
Description copied from interface: `SimpleJdbcInsertOperations`
Execute a batch insert using the batch of values passed in.

Specified by:
  `executeBatch` in interface `SimpleJdbcInsertOperations`
Parameters:
  `batch` - an array of SqlParameterSource containing values for the batch
Returns:
  the array of number of rows affected as returned by the JDBC driver