SimpleJdbcInsert (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

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 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 JBDC driver can provide the names of the columns for a specified table than we can rely on this auto-detection feature. If that is not the case then the column names must be specified explicitly.

  The actual insert is being handled using Spring's `JdbcTemplate`.

  Many of the configuration methods return the current instance of the SimpleJdbcInsert to provide the ability to string multiple ones together in a "fluid" interface style.

  Since:
    2.5
  Author:
    Thomas Risberg
  See Also:
    `DatabaseMetaData`, `JdbcTemplate`

- - ### Field Summary

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

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SimpleJdbcInsert(DataSource dataSource)` Constructor that takes one parameter with the JDBC DataSource to use when creating the JdbcTemplate.
    `SimpleJdbcInsert(JdbcTemplate jdbcTemplate)` Alternative Constructor that takes one parameter with the JdbcTemplate to be used.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `execute(Map<String,Object> 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,Object> 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,Object> 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,Object>[] 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.
    `SimpleJdbcInsertOperations` | `includeSynonymsForTableColumnMetaData()` Include synonyms for the column meta data lookups via JDBC.
    `SimpleJdbcInsertOperations` | `useNativeJdbcExtractorForMetaData(NativeJdbcExtractor nativeJdbcExtractor)` Use a the provided NativeJdbcExtractor during 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 name sof any columns that have auto generated keys.
    `SimpleJdbcInsert` | `withCatalogName(String catalogName)` Specify the catalog name, if any, to be used for the insert.
    `SimpleJdbcInsertOperations` | `withoutTableColumnMetaDataAccess()` Turn off any processing of column meta data information obtained via JDBC.
    `SimpleJdbcInsert` | `withSchemaName(String schemaName)` Specify the shema 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, matchInParameterValuesWithInsertColumns, matchInParameterValuesWithInsertColumns, onCompileInternal, setAccessTableColumnMetaData, setCatalogName, setColumnNames, setGeneratedKeyName, setGeneratedKeyNames, setNativeJdbcExtractor, setOverrideIncludeSynonymsDefault, setSchemaName, setTableName`

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

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

- - ### Constructor Detail

    - #### SimpleJdbcInsert

          public SimpleJdbcInsert(DataSource dataSource)

      Constructor that takes one parameter with 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 takes one parameter with the JdbcTemplate to be used.
      Parameters:
        `jdbcTemplate` - the `JdbcTemplate` to use
      See Also:
        `JdbcAccessor.setDataSource(javax.sql.DataSource)`

  - ### Method Detail

    - #### 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:
        the instance of this SimpleJdbcInsert

    - #### withSchemaName

          public SimpleJdbcInsert withSchemaName(String schemaName)

      Description copied from interface: `SimpleJdbcInsertOperations`
      Specify the shema name, if any, to be used for the insert.
      Specified by:
        `withSchemaName` in interface `SimpleJdbcInsertOperations`
      Parameters:
        `schemaName` - the name of the schema
      Returns:
        the instance of this SimpleJdbcInsert

    - #### 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:
        the instance of this SimpleJdbcInsert

    - #### 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:
        the instance of this SimpleJdbcInsert

    - #### usingGeneratedKeyColumns

          public SimpleJdbcInsert usingGeneratedKeyColumns(String... columnNames)

      Description copied from interface: `SimpleJdbcInsertOperations`
      Specify the name sof any columns that have auto generated keys.
      Specified by:
        `usingGeneratedKeyColumns` in interface `SimpleJdbcInsertOperations`
      Parameters:
        `columnNames` - one or more column names
      Returns:
        the instance of this SimpleJdbcInsert

    - #### withoutTableColumnMetaDataAccess

          public SimpleJdbcInsertOperations 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:
        the instance of this SimpleJdbcInsert

    - #### includeSynonymsForTableColumnMetaData

          public SimpleJdbcInsertOperations 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 seems to include the synonyms automatically.
      Specified by:
        `includeSynonymsForTableColumnMetaData` in interface `SimpleJdbcInsertOperations`
      Returns:
        the instance of this SimpleJdbcInsert

    - #### useNativeJdbcExtractorForMetaData

          public SimpleJdbcInsertOperations useNativeJdbcExtractorForMetaData(NativeJdbcExtractor nativeJdbcExtractor)

      Description copied from interface: `SimpleJdbcInsertOperations`
      Use a the provided NativeJdbcExtractor during the column meta data lookups via JDBC. Note: this is only necessary to include when running with a connection pool that wraps the meta data connection and when using a database like Oracle where it is necessary to access the native connection to include synonyms.
      Specified by:
        `useNativeJdbcExtractorForMetaData` in interface `SimpleJdbcInsertOperations`
      Returns:
        the instance of this SimpleJdbcInsert

    - #### execute

          public int execute(Map<String,Object> args)

      Description copied from interface: `SimpleJdbcInsertOperations`
      Execute the insert using the values passed in.
      Specified by:
        `execute` in interface `SimpleJdbcInsertOperations`
      Parameters:
        `args` - 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` - 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,Object> 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 key or throw an exception if a key was not returned.
      Specified by:
        `executeAndReturnKey` in interface `SimpleJdbcInsertOperations`
      Parameters:
        `args` - 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 key or throw an exception if a key was not returned.
      Specified by:
        `executeAndReturnKey` in interface `SimpleJdbcInsertOperations`
      Parameters:
        `parameterSource` - SqlParameterSource containing values to use for insert
      Returns:
        the generated key value.

    - #### executeAndReturnKeyHolder

          public KeyHolder executeAndReturnKeyHolder(Map<String,Object> 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` - 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` - SqlParameterSource containing values to use for insert
      Returns:
        the KeyHolder containing all generated keys

    - #### executeBatch

          public int[] executeBatch(Map<String,Object>[] 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