Spring JDBC 6.1.4 · org.springframework.jdbc.support.lob.LobHandler

Abstraction for handling large binary fields and large text fields in specific databases, no matter if represented as simple types or Large OBjects.

Provides accessor methods for BLOBs and CLOBs, and acts as factory for LobCreator instances, to be used as sessions for creating BLOBs or CLOBs. LobCreators are typically instantiated for each statement execution or for each transaction; they are not thread-safe because they might track allocated database resources in order to free them after execution.

Most databases/drivers should be able to work with DefaultLobHandler, which by default delegates to JDBC's direct accessor methods, avoiding the java.sql.Blob and java.sql.Clob API completely. DefaultLobHandler can also be configured to access LOBs using PreparedStatement.setBlob/setClob (e.g. for PostgreSQL), through setting the "wrapAsLob" property.

Of course, you need to declare different field types for each database. In Oracle, any binary content needs to go into a BLOB, and all character content beyond 4000 bytes needs to go into a CLOB. In MySQL, there is no notion of a CLOB type but rather a LONGTEXT type that behaves like a VARCHAR. For complete portability, use a LobHandler for fields that might typically require LOBs on some database because of the field size (take Oracle's numbers as a guideline).

Summarizing the recommended options (for actual LOB fields):

JDBC 4.0 driver (including Oracle 11g driver): Use DefaultLobHandler, potentially with streamAsLob=true if your database driver requires that hint when populating a LOB field. Fall back to createTemporaryLob=true if you happen to run into LOB size limitations with your (Oracle) database setup.
Oracle 10g driver: Use DefaultLobHandler with standard setup. On Oracle 10.1, set the "SetBigStringTryClob" connection property; as of Oracle 10.2, DefaultLobHandler should work with standard setup out of the box.
PostgreSQL: Configure DefaultLobHandler with wrapAsLob=true, and use that LobHandler to access OID columns (but not BYTEA) in your database tables.
For all other database drivers (and for non-LOB fields that might potentially turn into LOBs on some databases): Simply use a plain DefaultLobHandler.

Method Summary

Modifier and Type	Method and Description
public InputStream	Returns: the content as binary stream, or `null` in case of SQL NULL getBlobAsBinaryStream(ResultSet the ResultSet to retrieve the content from rs, String the column name to use columnName) Retrieve the given column as binary stream from the given ResultSet.
public InputStream	Returns: the content as binary stream, or `null` in case of SQL NULL getBlobAsBinaryStream(ResultSet the ResultSet to retrieve the content from rs, int the column index to use columnIndex) Retrieve the given column as binary stream from the given ResultSet.
public byte[]	Returns: the content as byte array, or `null` in case of SQL NULL getBlobAsBytes(ResultSet the ResultSet to retrieve the content from rs, String the column name to use columnName) Retrieve the given column as bytes from the given ResultSet.
public byte[]	Returns: the content as byte array, or `null` in case of SQL NULL getBlobAsBytes(ResultSet the ResultSet to retrieve the content from rs, int the column index to use columnIndex) Retrieve the given column as bytes from the given ResultSet.
public InputStream	Returns: the content as ASCII stream, or `null` in case of SQL NULL getClobAsAsciiStream(ResultSet the ResultSet to retrieve the content from rs, String the column name to use columnName) Retrieve the given column as ASCII stream from the given ResultSet.
public InputStream	Returns: the content as ASCII stream, or `null` in case of SQL NULL getClobAsAsciiStream(ResultSet the ResultSet to retrieve the content from rs, int the column index to use columnIndex) Retrieve the given column as ASCII stream from the given ResultSet.
public Reader	Returns: the content as character stream getClobAsCharacterStream(ResultSet the ResultSet to retrieve the content from rs, String the column name to use columnName) Retrieve the given column as character stream from the given ResultSet.
public Reader	Returns: the content as character stream getClobAsCharacterStream(ResultSet the ResultSet to retrieve the content from rs, int the column index to use columnIndex) Retrieve the given column as character stream from the given ResultSet.
public String	Returns: the content as String, or `null` in case of SQL NULL getClobAsString(ResultSet the ResultSet to retrieve the content from rs, String the column name to use columnName) Retrieve the given column as String from the given ResultSet.
public String	Returns: the content as String, or `null` in case of SQL NULL getClobAsString(ResultSet the ResultSet to retrieve the content from rs, int the column index to use columnIndex) Retrieve the given column as String from the given ResultSet.
public LobCreator	Returns: the new LobCreator instance getLobCreator() Create a new `LobCreator` instance, i.e. a session for creating BLOBs and CLOBs.

Method Detail

getBlobAsBinaryStream back to summary

getBlobAsBinaryStream	back to summary
public InputStream getBlobAsBinaryStream(ResultSet rs, String columnName) throws SQLException Retrieve the given column as binary stream from the given ResultSet. Might simply invoke `ResultSet.getBinaryStream` or work with `ResultSet.getBlob`, depending on the database and driver. Parameters rs:ResultSet the ResultSet to retrieve the content from columnName:String the column name to use Returns:InputStream the content as binary stream, or `null` in case of SQL NULL Annotations @Nullable Exceptions SQLException: if thrown by JDBC methods See Also `java.sql.ResultSet#getBinaryStream`

public InputStream getBlobAsBinaryStream(ResultSet rs, String columnName) throws SQLException

Retrieve the given column as binary stream from the given ResultSet. Might simply invoke ResultSet.getBinaryStream or work with ResultSet.getBlob, depending on the database and driver.

Parameters

rs:ResultSet: the ResultSet to retrieve the content from
columnName:String: the column name to use

Returns:InputStream

the content as binary stream, or null in case of SQL NULL

Annotations

@Nullable

Exceptions

SQLException:: if thrown by JDBC methods

See Also

java.sql.ResultSet#getBinaryStream

getBlobAsBinaryStream back to summary

getBlobAsBinaryStream	back to summary
public InputStream getBlobAsBinaryStream(ResultSet rs, int columnIndex) throws SQLException Retrieve the given column as binary stream from the given ResultSet. Might simply invoke `ResultSet.getBinaryStream` or work with `ResultSet.getBlob`, depending on the database and driver. Parameters rs:ResultSet the ResultSet to retrieve the content from columnIndex:int the column index to use Returns:InputStream the content as binary stream, or `null` in case of SQL NULL Annotations @Nullable Exceptions SQLException: if thrown by JDBC methods See Also `java.sql.ResultSet#getBinaryStream`

public InputStream getBlobAsBinaryStream(ResultSet rs, int columnIndex) throws SQLException

Retrieve the given column as binary stream from the given ResultSet. Might simply invoke ResultSet.getBinaryStream or work with ResultSet.getBlob, depending on the database and driver.

Parameters

rs:ResultSet: the ResultSet to retrieve the content from
columnIndex:int: the column index to use

Returns:InputStream

the content as binary stream, or null in case of SQL NULL

Annotations

@Nullable

Exceptions

SQLException:: if thrown by JDBC methods

See Also

java.sql.ResultSet#getBinaryStream

getBlobAsBytes back to summary

getBlobAsBytes	back to summary
public byte[] getBlobAsBytes(ResultSet rs, String columnName) throws SQLException Retrieve the given column as bytes from the given ResultSet. Might simply invoke `ResultSet.getBytes` or work with `ResultSet.getBlob`, depending on the database and driver. Parameters rs:ResultSet the ResultSet to retrieve the content from columnName:String the column name to use Returns:byte[] the content as byte array, or `null` in case of SQL NULL Annotations @Nullable Exceptions SQLException: if thrown by JDBC methods See Also `java.sql.ResultSet#getBytes`

public byte[] getBlobAsBytes(ResultSet rs, String columnName) throws SQLException

Retrieve the given column as bytes from the given ResultSet. Might simply invoke ResultSet.getBytes or work with ResultSet.getBlob, depending on the database and driver.

Parameters

rs:ResultSet: the ResultSet to retrieve the content from
columnName:String: the column name to use

Returns:byte[]

the content as byte array, or null in case of SQL NULL

Annotations

@Nullable

Exceptions

SQLException:: if thrown by JDBC methods

See Also

java.sql.ResultSet#getBytes

getBlobAsBytes back to summary

getBlobAsBytes	back to summary
public byte[] getBlobAsBytes(ResultSet rs, int columnIndex) throws SQLException Retrieve the given column as bytes from the given ResultSet. Might simply invoke `ResultSet.getBytes` or work with `ResultSet.getBlob`, depending on the database and driver. Parameters rs:ResultSet the ResultSet to retrieve the content from columnIndex:int the column index to use Returns:byte[] the content as byte array, or `null` in case of SQL NULL Annotations @Nullable Exceptions SQLException: if thrown by JDBC methods See Also `java.sql.ResultSet#getBytes`

public byte[] getBlobAsBytes(ResultSet rs, int columnIndex) throws SQLException

Retrieve the given column as bytes from the given ResultSet. Might simply invoke ResultSet.getBytes or work with ResultSet.getBlob, depending on the database and driver.

Parameters

rs:ResultSet: the ResultSet to retrieve the content from
columnIndex:int: the column index to use

Returns:byte[]

the content as byte array, or null in case of SQL NULL

Annotations

@Nullable

Exceptions

SQLException:: if thrown by JDBC methods

See Also

java.sql.ResultSet#getBytes

getClobAsAsciiStream back to summary

getClobAsAsciiStream	back to summary
public InputStream getClobAsAsciiStream(ResultSet rs, String columnName) throws SQLException Retrieve the given column as ASCII stream from the given ResultSet. Might simply invoke `ResultSet.getAsciiStream` or work with `ResultSet.getClob`, depending on the database and driver. Parameters rs:ResultSet the ResultSet to retrieve the content from columnName:String the column name to use Returns:InputStream the content as ASCII stream, or `null` in case of SQL NULL Annotations @Nullable Exceptions SQLException: if thrown by JDBC methods See Also `java.sql.ResultSet#getAsciiStream`

public InputStream getClobAsAsciiStream(ResultSet rs, String columnName) throws SQLException

Retrieve the given column as ASCII stream from the given ResultSet. Might simply invoke ResultSet.getAsciiStream or work with ResultSet.getClob, depending on the database and driver.

Parameters

rs:ResultSet: the ResultSet to retrieve the content from
columnName:String: the column name to use

Returns:InputStream

the content as ASCII stream, or null in case of SQL NULL

Annotations

@Nullable

Exceptions

SQLException:: if thrown by JDBC methods

See Also

java.sql.ResultSet#getAsciiStream

getClobAsAsciiStream back to summary

getClobAsAsciiStream	back to summary
public InputStream getClobAsAsciiStream(ResultSet rs, int columnIndex) throws SQLException Retrieve the given column as ASCII stream from the given ResultSet. Might simply invoke `ResultSet.getAsciiStream` or work with `ResultSet.getClob`, depending on the database and driver. Parameters rs:ResultSet the ResultSet to retrieve the content from columnIndex:int the column index to use Returns:InputStream the content as ASCII stream, or `null` in case of SQL NULL Annotations @Nullable Exceptions SQLException: if thrown by JDBC methods See Also `java.sql.ResultSet#getAsciiStream`

public InputStream getClobAsAsciiStream(ResultSet rs, int columnIndex) throws SQLException

Retrieve the given column as ASCII stream from the given ResultSet. Might simply invoke ResultSet.getAsciiStream or work with ResultSet.getClob, depending on the database and driver.

Parameters

rs:ResultSet: the ResultSet to retrieve the content from
columnIndex:int: the column index to use

Returns:InputStream

the content as ASCII stream, or null in case of SQL NULL

Annotations

@Nullable

Exceptions

SQLException:: if thrown by JDBC methods

See Also

java.sql.ResultSet#getAsciiStream

getClobAsCharacterStream back to summary

getClobAsCharacterStream	back to summary
public Reader getClobAsCharacterStream(ResultSet rs, String columnName) throws SQLException Retrieve the given column as character stream from the given ResultSet. Might simply invoke `ResultSet.getCharacterStream` or work with `ResultSet.getClob`, depending on the database and driver. Parameters rs:ResultSet the ResultSet to retrieve the content from columnName:String the column name to use Returns:Reader the content as character stream Exceptions SQLException: if thrown by JDBC methods See Also `java.sql.ResultSet#getCharacterStream`

public Reader getClobAsCharacterStream(ResultSet rs, String columnName) throws SQLException

Retrieve the given column as character stream from the given ResultSet. Might simply invoke ResultSet.getCharacterStream or work with ResultSet.getClob, depending on the database and driver.

Parameters

rs:ResultSet: the ResultSet to retrieve the content from
columnName:String: the column name to use

Returns:Reader

the content as character stream

Exceptions

SQLException:: if thrown by JDBC methods

See Also

java.sql.ResultSet#getCharacterStream

getClobAsCharacterStream back to summary

getClobAsCharacterStream	back to summary
public Reader getClobAsCharacterStream(ResultSet rs, int columnIndex) throws SQLException Retrieve the given column as character stream from the given ResultSet. Might simply invoke `ResultSet.getCharacterStream` or work with `ResultSet.getClob`, depending on the database and driver. Parameters rs:ResultSet the ResultSet to retrieve the content from columnIndex:int the column index to use Returns:Reader the content as character stream Exceptions SQLException: if thrown by JDBC methods See Also `java.sql.ResultSet#getCharacterStream`

public Reader getClobAsCharacterStream(ResultSet rs, int columnIndex) throws SQLException

Retrieve the given column as character stream from the given ResultSet. Might simply invoke ResultSet.getCharacterStream or work with ResultSet.getClob, depending on the database and driver.

Parameters

rs:ResultSet: the ResultSet to retrieve the content from
columnIndex:int: the column index to use

Returns:Reader

the content as character stream

Exceptions

SQLException:: if thrown by JDBC methods

See Also

java.sql.ResultSet#getCharacterStream

getClobAsString back to summary

getClobAsString	back to summary
public String getClobAsString(ResultSet rs, String columnName) throws SQLException Retrieve the given column as String from the given ResultSet. Might simply invoke `ResultSet.getString` or work with `ResultSet.getClob`, depending on the database and driver. Parameters rs:ResultSet the ResultSet to retrieve the content from columnName:String the column name to use Returns:String the content as String, or `null` in case of SQL NULL Annotations @Nullable Exceptions SQLException: if thrown by JDBC methods See Also `java.sql.ResultSet#getString`

public String getClobAsString(ResultSet rs, String columnName) throws SQLException

Retrieve the given column as String from the given ResultSet. Might simply invoke ResultSet.getString or work with ResultSet.getClob, depending on the database and driver.

Parameters

rs:ResultSet: the ResultSet to retrieve the content from
columnName:String: the column name to use

Returns:String

the content as String, or null in case of SQL NULL

Annotations

@Nullable

Exceptions

SQLException:: if thrown by JDBC methods

See Also

java.sql.ResultSet#getString

getClobAsString back to summary

getClobAsString	back to summary
public String getClobAsString(ResultSet rs, int columnIndex) throws SQLException Retrieve the given column as String from the given ResultSet. Might simply invoke `ResultSet.getString` or work with `ResultSet.getClob`, depending on the database and driver. Parameters rs:ResultSet the ResultSet to retrieve the content from columnIndex:int the column index to use Returns:String the content as String, or `null` in case of SQL NULL Annotations @Nullable Exceptions SQLException: if thrown by JDBC methods See Also `java.sql.ResultSet#getString`

public String getClobAsString(ResultSet rs, int columnIndex) throws SQLException

Retrieve the given column as String from the given ResultSet. Might simply invoke ResultSet.getString or work with ResultSet.getClob, depending on the database and driver.

Parameters

rs:ResultSet: the ResultSet to retrieve the content from
columnIndex:int: the column index to use

Returns:String

the content as String, or null in case of SQL NULL

Annotations

@Nullable

Exceptions

SQLException:: if thrown by JDBC methods

See Also

java.sql.ResultSet#getString

getLobCreator back to summary

getLobCreator	back to summary
public LobCreator getLobCreator() Create a new `LobCreator` instance, i.e. a session for creating BLOBs and CLOBs. Needs to be closed after the created LOBs are not needed anymore - typically after statement execution or transaction completion. Returns:LobCreator the new LobCreator instance See Also `LobCreator#close()`

public LobCreator getLobCreator()

Create a new LobCreator instance, i.e. a session for creating BLOBs and CLOBs. Needs to be closed after the created LOBs are not needed anymore - typically after statement execution or transaction completion.

Returns:LobCreator: the new LobCreator instance
See Also: LobCreator#close()

public Interface LobHandler

Method Summary

Method Detail