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.ResultSet;
022: import java.sql.SQLException;
023:
024: /**
025: * Abstraction for handling large binary fields and large text fields in
026: * specific databases, no matter if represented as simple types or Large OBjects.
027: * Its main purpose is to isolate Oracle's peculiar handling of LOBs in
028: * OracleLobHandler; most other databases should work with DefaultLobHandler.
029: *
030: * <p>Provides accessor methods for BLOBs and CLOBs, and acts as factory for
031: * LobCreator instances, to be used as sessions for creating BLOBs or CLOBs.
032: * LobCreators are typically instantiated for each statement execution or for
033: * each transaction. They are not thread-safe because they might track
034: * allocated database resources to be able to free them after execution.
035: *
036: * <p>Most databases/drivers should be able to work with DefaultLobHandler,
037: * which simply delegates to JDBC's direct accessor methods, avoiding
038: * <code>java.sql.Blob</code> and <code>java.sql.Clob</code> completely.
039: *
040: * <p>Unfortunately, Oracle 9i just accepts Blob/Clob instances created via its own
041: * proprietary BLOB/CLOB API, and additionally doesn't accept large streams for
042: * PreparedStatement's corresponding setter methods. Therefore, you need to use
043: * OracleLobHandler there, which uses Oracle's BLOB/CLOB API for both all access.
044: * The Oracle 10g JDBC driver should work with DefaultLobHandler too.
045: *
046: * <p>Of course, you need to declare different field types for each database.
047: * In Oracle, any binary content needs to go into a BLOB, and all character content
048: * beyond 4000 bytes needs to go into a CLOB. In MySQL, there is no notion of a
049: * CLOB type but rather a LONGTEXT type that behaves like a VARCHAR. For complete
050: * portability, just use a LobHandler for fields that might typically require LOBs
051: * on some database because of their size (take Oracle's numbers as a guideline).
052: *
053: * @author Juergen Hoeller
054: * @since 23.12.2003
055: * @see DefaultLobHandler
056: * @see OracleLobHandler
057: * @see java.sql.ResultSet#getBlob
058: * @see java.sql.ResultSet#getClob
059: * @see java.sql.ResultSet#getBytes
060: * @see java.sql.ResultSet#getBinaryStream
061: * @see java.sql.ResultSet#getString
062: * @see java.sql.ResultSet#getAsciiStream
063: * @see java.sql.ResultSet#getCharacterStream
064: */
065: public interface LobHandler {
066:
067: /**
068: * Retrieve the given column as bytes from the given ResultSet.
069: * Might simply invoke <code>ResultSet.getBytes</code> or work with
070: * <code>ResultSet.getBlob</code>, depending on the database and driver.
071: * @param rs the ResultSet to retrieve the content from
072: * @param columnName the column name to use
073: * @return the content as byte array, or <code>null</code> in case of SQL NULL
074: * @throws SQLException if thrown by JDBC methods
075: * @see java.sql.ResultSet#getBytes
076: */
077: byte[] getBlobAsBytes(ResultSet rs, String columnName)
078: throws SQLException;
079:
080: /**
081: * Retrieve the given column as bytes from the given ResultSet.
082: * Might simply invoke <code>ResultSet.getBytes</code> or work with
083: * <code>ResultSet.getBlob</code>, depending on the database and driver.
084: * @param rs the ResultSet to retrieve the content from
085: * @param columnIndex the column index to use
086: * @return the content as byte array, or <code>null</code> in case of SQL NULL
087: * @throws SQLException if thrown by JDBC methods
088: * @see java.sql.ResultSet#getBytes
089: */
090: byte[] getBlobAsBytes(ResultSet rs, int columnIndex)
091: throws SQLException;
092:
093: /**
094: * Retrieve the given column as binary stream from the given ResultSet.
095: * Might simply invoke <code>ResultSet.getBinaryStream</code> or work with
096: * <code>ResultSet.getBlob</code>, depending on the database and driver.
097: * @param rs the ResultSet to retrieve the content from
098: * @param columnName the column name to use
099: * @return the content as binary stream, or <code>null</code> in case of SQL NULL
100: * @throws SQLException if thrown by JDBC methods
101: * @see java.sql.ResultSet#getBinaryStream
102: */
103: InputStream getBlobAsBinaryStream(ResultSet rs, String columnName)
104: throws SQLException;
105:
106: /**
107: * Retrieve the given column as binary stream from the given ResultSet.
108: * Might simply invoke <code>ResultSet.getBinaryStream</code> or work with
109: * <code>ResultSet.getBlob</code>, depending on the database and driver.
110: * @param rs the ResultSet to retrieve the content from
111: * @param columnIndex the column index to use
112: * @return the content as binary stream, or <code>null</code> in case of SQL NULL
113: * @throws SQLException if thrown by JDBC methods
114: * @see java.sql.ResultSet#getBinaryStream
115: */
116: InputStream getBlobAsBinaryStream(ResultSet rs, int columnIndex)
117: throws SQLException;
118:
119: /**
120: * Retrieve the given column as String from the given ResultSet.
121: * Might simply invoke <code>ResultSet.getString</code> or work with
122: * <code>ResultSet.getClob</code>, depending on the database and driver.
123: * @param rs the ResultSet to retrieve the content from
124: * @param columnName the column name to use
125: * @return the content as String, or <code>null</code> in case of SQL NULL
126: * @throws SQLException if thrown by JDBC methods
127: * @see java.sql.ResultSet#getString
128: */
129: String getClobAsString(ResultSet rs, String columnName)
130: throws SQLException;
131:
132: /**
133: * Retrieve the given column as String from the given ResultSet.
134: * Might simply invoke <code>ResultSet.getString</code> or work with
135: * <code>ResultSet.getClob</code>, depending on the database and driver.
136: * @param rs the ResultSet to retrieve the content from
137: * @param columnIndex the column index to use
138: * @return the content as String, or <code>null</code> in case of SQL NULL
139: * @throws SQLException if thrown by JDBC methods
140: * @see java.sql.ResultSet#getString
141: */
142: String getClobAsString(ResultSet rs, int columnIndex)
143: throws SQLException;
144:
145: /**
146: * Retrieve the given column as ASCII stream from the given ResultSet.
147: * Might simply invoke <code>ResultSet.getAsciiStream</code> or work with
148: * <code>ResultSet.getClob</code>, depending on the database and driver.
149: * @param rs the ResultSet to retrieve the content from
150: * @param columnName the column name to use
151: * @return the content as ASCII stream, or <code>null</code> in case of SQL NULL
152: * @throws SQLException if thrown by JDBC methods
153: * @see java.sql.ResultSet#getAsciiStream
154: */
155: InputStream getClobAsAsciiStream(ResultSet rs, String columnName)
156: throws SQLException;
157:
158: /**
159: * Retrieve the given column as ASCII stream from the given ResultSet.
160: * Might simply invoke <code>ResultSet.getAsciiStream</code> or work with
161: * <code>ResultSet.getClob</code>, depending on the database and driver.
162: * @param rs the ResultSet to retrieve the content from
163: * @param columnIndex the column index to use
164: * @return the content as ASCII stream, or <code>null</code> in case of SQL NULL
165: * @throws SQLException if thrown by JDBC methods
166: * @see java.sql.ResultSet#getAsciiStream
167: */
168: InputStream getClobAsAsciiStream(ResultSet rs, int columnIndex)
169: throws SQLException;
170:
171: /**
172: * Retrieve the given column as character stream from the given ResultSet.
173: * Might simply invoke <code>ResultSet.getCharacterStream</code> or work with
174: * <code>ResultSet.getClob</code>, depending on the database and driver.
175: * @param rs the ResultSet to retrieve the content from
176: * @param columnName the column name to use
177: * @return the content as character stream
178: * @throws SQLException if thrown by JDBC methods
179: * @see java.sql.ResultSet#getCharacterStream
180: */
181: Reader getClobAsCharacterStream(ResultSet rs, String columnName)
182: throws SQLException;
183:
184: /**
185: * Retrieve the given column as character stream from the given ResultSet.
186: * Might simply invoke <code>ResultSet.getCharacterStream</code> or work with
187: * <code>ResultSet.getClob</code>, depending on the database and driver.
188: * @param rs the ResultSet to retrieve the content from
189: * @param columnIndex the column index to use
190: * @return the content as character stream
191: * @throws SQLException if thrown by JDBC methods
192: * @see java.sql.ResultSet#getCharacterStream
193: */
194: Reader getClobAsCharacterStream(ResultSet rs, int columnIndex)
195: throws SQLException;
196:
197: /**
198: * Create a new LobCreator instance, i.e. a session for creating BLOBs
199: * and CLOBs. Needs to be closed after the created LOBs are not needed
200: * anymore, i.e. after statement execution or transaction completion.
201: * @return the new LobCreator instance
202: * @see LobCreator#close
203: */
204: LobCreator getLobCreator();
205:
206: }
|