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

org.springframework.jdbc.support.lob

## Interface LobCreator

- All Superinterfaces:
    AutoCloseable, Closeable
  All Known Implementing Classes:
    DefaultLobHandler.DefaultLobCreator, OracleLobHandler.OracleLobCreator

      public interface LobCreator
      extends Closeable

  Interface that abstracts potentially database-specific creation of large binary fields and large text fields. Does not work with `java.sql.Blob` and `java.sql.Clob` instances in the API, as some JDBC drivers do not support these types as such.

  The LOB creation part is where `LobHandler` implementations usually differ. Possible strategies include usage of `PreparedStatement.setBinaryStream/setCharacterStream` but also `PreparedStatement.setBlob/setClob` with either a stream argument (requires JDBC 4.0) or `java.sql.Blob/Clob` wrapper objects.

  A LobCreator represents a session for creating BLOBs: It is not thread-safe and needs to be instantiated for each statement execution or for each transaction. Each LobCreator needs to be closed after completion.

  For convenient working with a PreparedStatement and a LobCreator, consider using `JdbcTemplate` with an `AbstractLobCreatingPreparedStatementCallback` implementation. See the latter's javadoc for details.

  Since:
    04.12.2003
  Author:
    Juergen Hoeller
  See Also:
    `close()`, `LobHandler.getLobCreator()`, `DefaultLobHandler.DefaultLobCreator`, `OracleLobHandler.OracleLobCreator`, `PreparedStatement.setBlob(int, java.sql.Blob)`, `PreparedStatement.setClob(int, java.sql.Clob)`, `PreparedStatement.setBytes(int, byte[])`, `PreparedStatement.setBinaryStream(int, java.io.InputStream, int)`, `PreparedStatement.setString(int, java.lang.String)`, `PreparedStatement.setAsciiStream(int, java.io.InputStream, int)`, `PreparedStatement.setCharacterStream(int, java.io.Reader, int)`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Close this LobCreator session and free its temporarily created BLOBs and CLOBs.
    `void` | `setBlobAsBinaryStream(PreparedStatement ps, int paramIndex, InputStream contentStream, int contentLength)` Set the given content as binary stream on the given statement, using the given parameter index.
    `void` | `setBlobAsBytes(PreparedStatement ps, int paramIndex, byte[] content)` Set the given content as bytes on the given statement, using the given parameter index.
    `void` | `setClobAsAsciiStream(PreparedStatement ps, int paramIndex, InputStream asciiStream, int contentLength)` Set the given content as ASCII stream on the given statement, using the given parameter index.
    `void` | `setClobAsCharacterStream(PreparedStatement ps, int paramIndex, Reader characterStream, int contentLength)` Set the given content as character stream on the given statement, using the given parameter index.
    `void` | `setClobAsString(PreparedStatement ps, int paramIndex, String content)` Set the given content as String on the given statement, using the given parameter index.

- - ### Method Detail

    - #### setBlobAsBytes

          void setBlobAsBytes(PreparedStatement ps,
                            int paramIndex,
                            byte[] content)
                              throws SQLException

      Set the given content as bytes on the given statement, using the given parameter index. Might simply invoke `PreparedStatement.setBytes` or create a Blob instance for it, depending on the database and driver.
      Parameters:
        `ps` - the PreparedStatement to the set the content on
        `paramIndex` - the parameter index to use
        `content` - the content as byte array, or `null` for SQL NULL
      Throws:
        `SQLException` - if thrown by JDBC methods
      See Also:
        `PreparedStatement.setBytes(int, byte[])`

    - #### setBlobAsBinaryStream

          void setBlobAsBinaryStream(PreparedStatement ps,
                                   int paramIndex,
                                   InputStream contentStream,
                                   int contentLength)
                                     throws SQLException

      Set the given content as binary stream on the given statement, using the given parameter index. Might simply invoke `PreparedStatement.setBinaryStream` or create a Blob instance for it, depending on the database and driver.
      Parameters:
        `ps` - the PreparedStatement to the set the content on
        `paramIndex` - the parameter index to use
        `contentStream` - the content as binary stream, or `null` for SQL NULL
      Throws:
        `SQLException` - if thrown by JDBC methods
      See Also:
        `PreparedStatement.setBinaryStream(int, java.io.InputStream, int)`

    - #### setClobAsString

          void setClobAsString(PreparedStatement ps,
                             int paramIndex,
                             String content)
                               throws SQLException

      Set the given content as String on the given statement, using the given parameter index. Might simply invoke `PreparedStatement.setString` or create a Clob instance for it, depending on the database and driver.
      Parameters:
        `ps` - the PreparedStatement to the set the content on
        `paramIndex` - the parameter index to use
        `content` - the content as String, or `null` for SQL NULL
      Throws:
        `SQLException` - if thrown by JDBC methods
      See Also:
        `PreparedStatement.setBytes(int, byte[])`

    - #### setClobAsAsciiStream

          void setClobAsAsciiStream(PreparedStatement ps,
                                  int paramIndex,
                                  InputStream asciiStream,
                                  int contentLength)
                                    throws SQLException

      Set the given content as ASCII stream on the given statement, using the given parameter index. Might simply invoke `PreparedStatement.setAsciiStream` or create a Clob instance for it, depending on the database and driver.
      Parameters:
        `ps` - the PreparedStatement to the set the content on
        `paramIndex` - the parameter index to use
        `asciiStream` - the content as ASCII stream, or `null` for SQL NULL
      Throws:
        `SQLException` - if thrown by JDBC methods
      See Also:
        `PreparedStatement.setAsciiStream(int, java.io.InputStream, int)`

    - #### setClobAsCharacterStream

          void setClobAsCharacterStream(PreparedStatement ps,
                                      int paramIndex,
                                      Reader characterStream,
                                      int contentLength)
                                        throws SQLException

      Set the given content as character stream on the given statement, using the given parameter index. Might simply invoke `PreparedStatement.setCharacterStream` or create a Clob instance for it, depending on the database and driver.
      Parameters:
        `ps` - the PreparedStatement to the set the content on
        `paramIndex` - the parameter index to use
        `characterStream` - the content as character stream, or `null` for SQL NULL
      Throws:
        `SQLException` - if thrown by JDBC methods
      See Also:
        `PreparedStatement.setCharacterStream(int, java.io.Reader, int)`

    - #### close

          void close()

      Close this LobCreator session and free its temporarily created BLOBs and CLOBs. Will not need to do anything if using PreparedStatement's standard methods, but might be necessary to free database resources if using proprietary means.

      NOTE: Needs to be invoked after the involved PreparedStatements have been executed or the affected O/R mapping sessions have been flushed. Otherwise, the database resources for the temporary BLOBs might stay allocated.

      Specified by:
        `close` in interface `AutoCloseable`
      Specified by:
        `close` in interface `Closeable`