https://github.com/spring-projects/spring-framework: Spring JDBC (Spring IO)
  • Juergen Hoeller 
/*
 * Copyright 2002-2016 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
 *
 *      https://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.support.lob;

import java.io.Closeable;
import java.io.InputStream;
import java.io.Reader;
import java.sql.PreparedStatement;
import java.sql.SQLException;

import org.springframework.lang.Nullable;


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. 
Author:Juergen Hoeller
See Also:
Since:04.12.2003
/**
 * Interface that abstracts potentially database-specific creation of large binary
 * fields and large text fields. Does not work with {@code java.sql.Blob}
 * and {@code java.sql.Clob} instances in the API, as some JDBC drivers
 * do not support these types as such.
 *
 * <p>The LOB creation part is where {@link LobHandler} implementations usually
 * differ. Possible strategies include usage of
 * {@code PreparedStatement.setBinaryStream/setCharacterStream} but also
 * {@code PreparedStatement.setBlob/setClob} with either a stream argument
 * (requires JDBC 4.0) or {@code java.sql.Blob/Clob} wrapper objects.
 *
 * <p>A LobCreator represents a session for creating BLOBs: It is <i>not</i>
 * thread-safe and needs to be instantiated for each statement execution or for
 * each transaction. Each LobCreator needs to be closed after completion.
 *
 * <p>For convenient working with a PreparedStatement and a LobCreator,
 * consider using {@link org.springframework.jdbc.core.JdbcTemplate} with an
 *{@link org.springframework.jdbc.core.support.AbstractLobCreatingPreparedStatementCallback}
 * implementation. See the latter's javadoc for details.
 *
 * @author Juergen Hoeller
 * @since 04.12.2003
 * @see #close()
 * @see LobHandler#getLobCreator()
 * @see DefaultLobHandler.DefaultLobCreator
 * @see java.sql.PreparedStatement#setBlob
 * @see java.sql.PreparedStatement#setClob
 * @see java.sql.PreparedStatement#setBytes
 * @see java.sql.PreparedStatement#setBinaryStream
 * @see java.sql.PreparedStatement#setString
 * @see java.sql.PreparedStatement#setAsciiStream
 * @see java.sql.PreparedStatement#setCharacterStream
 */
public interface LobCreator extends Closeable {

	
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. 
Params:
  • 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:
See Also:
/**
	 * Set the given content as bytes on the given statement, using the given
	 * parameter index. Might simply invoke {@code PreparedStatement.setBytes}
	 * or create a Blob instance for it, depending on the database and driver.
	 * @param ps the PreparedStatement to the set the content on
	 * @param paramIndex the parameter index to use
	 * @param content the content as byte array, or {@code null} for SQL NULL
	 * @throws SQLException if thrown by JDBC methods
	 * @see java.sql.PreparedStatement#setBytes
	 */
	void setBlobAsBytes(PreparedStatement ps, int paramIndex, @Nullable byte[] content)
			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. 
Params:
  • 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:
See Also:
/**
	 * Set the given content as binary stream on the given statement, using the given
	 * parameter index. Might simply invoke {@code PreparedStatement.setBinaryStream}
	 * or create a Blob instance for it, depending on the database and driver.
	 * @param ps the PreparedStatement to the set the content on
	 * @param paramIndex the parameter index to use
	 * @param contentStream the content as binary stream, or {@code null} for SQL NULL
	 * @throws SQLException if thrown by JDBC methods
	 * @see java.sql.PreparedStatement#setBinaryStream
	 */
	void setBlobAsBinaryStream(
			PreparedStatement ps, int paramIndex, @Nullable InputStream contentStream, int contentLength)
			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. 
Params:
  • 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:
See Also:
/**
	 * Set the given content as String on the given statement, using the given
	 * parameter index. Might simply invoke {@code PreparedStatement.setString}
	 * or create a Clob instance for it, depending on the database and driver.
	 * @param ps the PreparedStatement to the set the content on
	 * @param paramIndex the parameter index to use
	 * @param content the content as String, or {@code null} for SQL NULL
	 * @throws SQLException if thrown by JDBC methods
	 * @see java.sql.PreparedStatement#setBytes
	 */
	void setClobAsString(PreparedStatement ps, int paramIndex, @Nullable String content)
			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. 
Params:
  • 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:
See Also:
/**
	 * Set the given content as ASCII stream on the given statement, using the given
	 * parameter index. Might simply invoke {@code PreparedStatement.setAsciiStream}
	 * or create a Clob instance for it, depending on the database and driver.
	 * @param ps the PreparedStatement to the set the content on
	 * @param paramIndex the parameter index to use
	 * @param asciiStream the content as ASCII stream, or {@code null} for SQL NULL
	 * @throws SQLException if thrown by JDBC methods
	 * @see java.sql.PreparedStatement#setAsciiStream
	 */
	void setClobAsAsciiStream(
			PreparedStatement ps, int paramIndex, @Nullable InputStream asciiStream, 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. 
Params:
  • 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:
See Also:
/**
	 * Set the given content as character stream on the given statement, using the given
	 * parameter index. Might simply invoke {@code PreparedStatement.setCharacterStream}
	 * or create a Clob instance for it, depending on the database and driver.
	 * @param ps the PreparedStatement to the set the content on
	 * @param paramIndex the parameter index to use
	 * @param characterStream the content as character stream, or {@code null} for SQL NULL
	 * @throws SQLException if thrown by JDBC methods
	 * @see java.sql.PreparedStatement#setCharacterStream
	 */
	void setClobAsCharacterStream(
			PreparedStatement ps, int paramIndex, @Nullable Reader characterStream, int contentLength)
			throws SQLException;

	
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.

/**
	 * 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.
	 * <p><b>NOTE</b>: 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.
	 */
	@Override
	void close();

}