001: /*
002: * Copyright 2002-2005 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.springframework.jdbc.support.lob;
018:
019: import java.io.InputStream;
020: import java.io.Reader;
021: import java.sql.PreparedStatement;
022: import java.sql.SQLException;
023:
024: /**
025: * Interface that abstracts potentially database-specific creation of large binary
026: * fields and large text fields. Does not work with java.sql.Blob and java.sql.Clob
027: * instances in the API, as some JDBC drivers do not support these types as such.
028: *
029: * <p>A LobCreator represents a session for creating BLOBs: It is <i>not</i>
030: * thread-safe and needs to be instantiated for each statement execution or for
031: * each transaction. Each LobCreator needs to be closed after completion.
032: *
033: * <p>For convenient working with a PreparedStatement and a LobCreator, consider
034: * JdbcTemplate with a AbstractLobCreatingPreparedStatementCallback implementation.
035: * See the latter's javadoc for details.
036: *
037: * @author Juergen Hoeller
038: * @since 04.12.2003
039: * @see #close
040: * @see LobHandler#getLobCreator
041: * @see org.springframework.jdbc.core.support.AbstractLobCreatingPreparedStatementCallback
042: * @see DefaultLobHandler.DefaultLobCreator
043: * @see OracleLobHandler.OracleLobCreator
044: * @see java.sql.PreparedStatement#setBlob
045: * @see java.sql.PreparedStatement#setClob
046: * @see java.sql.PreparedStatement#setBytes
047: * @see java.sql.PreparedStatement#setBinaryStream
048: * @see java.sql.PreparedStatement#setString
049: * @see java.sql.PreparedStatement#setAsciiStream
050: * @see java.sql.PreparedStatement#setCharacterStream
051: */
052: public interface LobCreator {
053:
054: /**
055: * Set the given content as bytes on the given statement, using the given
056: * parameter index. Might simply invoke <code>PreparedStatement.setBytes</code>
057: * or create a Blob instance for it, depending on the database and driver.
058: * @param ps the PreparedStatement to the set the content on
059: * @param paramIndex the parameter index to use
060: * @param content the content as byte array, or <code>null</code> for SQL NULL
061: * @throws SQLException if thrown by JDBC methods
062: * @see java.sql.PreparedStatement#setBytes
063: */
064: void setBlobAsBytes(PreparedStatement ps, int paramIndex,
065: byte[] content) throws SQLException;
066:
067: /**
068: * Set the given content as binary stream on the given statement, using the given
069: * parameter index. Might simply invoke <code>PreparedStatement.setBinaryStream</code>
070: * or create a Blob instance for it, depending on the database and driver.
071: * @param ps the PreparedStatement to the set the content on
072: * @param paramIndex the parameter index to use
073: * @param contentStream the content as binary stream, or <code>null</code> for SQL NULL
074: * @throws SQLException if thrown by JDBC methods
075: * @see java.sql.PreparedStatement#setBinaryStream
076: */
077: void setBlobAsBinaryStream(PreparedStatement ps, int paramIndex,
078: InputStream contentStream, int contentLength)
079: throws SQLException;
080:
081: /**
082: * Set the given content as String on the given statement, using the given
083: * parameter index. Might simply invoke <code>PreparedStatement.setString</code>
084: * or create a Clob instance for it, depending on the database and driver.
085: * @param ps the PreparedStatement to the set the content on
086: * @param paramIndex the parameter index to use
087: * @param content the content as String, or <code>null</code> for SQL NULL
088: * @throws SQLException if thrown by JDBC methods
089: * @see java.sql.PreparedStatement#setBytes
090: */
091: void setClobAsString(PreparedStatement ps, int paramIndex,
092: String content) throws SQLException;
093:
094: /**
095: * Set the given content as ASCII stream on the given statement, using the given
096: * parameter index. Might simply invoke <code>PreparedStatement.setAsciiStream</code>
097: * or create a Clob instance for it, depending on the database and driver.
098: * @param ps the PreparedStatement to the set the content on
099: * @param paramIndex the parameter index to use
100: * @param asciiStream the content as ASCII stream, or <code>null</code> for SQL NULL
101: * @throws SQLException if thrown by JDBC methods
102: * @see java.sql.PreparedStatement#setAsciiStream
103: */
104: void setClobAsAsciiStream(PreparedStatement ps, int paramIndex,
105: InputStream asciiStream, int contentLength)
106: throws SQLException;
107:
108: /**
109: * Set the given content as character stream on the given statement, using the given
110: * parameter index. Might simply invoke <code>PreparedStatement.setCharacterStream</code>
111: * or create a Clob instance for it, depending on the database and driver.
112: * @param ps the PreparedStatement to the set the content on
113: * @param paramIndex the parameter index to use
114: * @param characterStream the content as character stream, or <code>null</code> for SQL NULL
115: * @throws SQLException if thrown by JDBC methods
116: * @see java.sql.PreparedStatement#setCharacterStream
117: */
118: void setClobAsCharacterStream(PreparedStatement ps, int paramIndex,
119: Reader characterStream, int contentLength)
120: throws SQLException;
121:
122: /**
123: * Close this LobCreator session and free its temporarily created BLOBs and CLOBs.
124: * Will not need to do anything if using PreparedStatement's standard methods,
125: * but might be necessary to free database resources if using proprietary means.
126: * <p><b>NOTE</b>: Needs to be invoked after the involved PreparedStatements have
127: * been executed or the affected O/R mapping sessions have been flushed.
128: * Else, the database resources for the temporary BLOBs might stay allocated.
129: */
130: void close();
131:
132: }
|