LobHandler


1   /*
2    * Copyright 2002-2005 the original author or authors.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.springframework.jdbc.support.lob;
18  
19  import java.io.InputStream  ;
20  import java.io.Reader  ;
21  import java.sql.ResultSet  ;
22  import java.sql.SQLException  ;
23  
24  /**
25   * Abstraction for handling large binary fields and large text fields in
26   * specific databases, no matter if represented as simple types or Large OBjects.
27   * Its main purpose is to isolate Oracle's peculiar handling of LOBs in
28   * OracleLobHandler; most other databases should work with DefaultLobHandler.
29   *
30   * <p>Provides accessor methods for BLOBs and CLOBs, and acts as factory for
31   * LobCreator instances, to be used as sessions for creating BLOBs or CLOBs.
32   * LobCreators are typically instantiated for each statement execution or for
33   * each transaction. They are not thread-safe because they might track
34   * allocated database resources to be able to free them after execution.
35   *
36   * <p>Most databases/drivers should be able to work with DefaultLobHandler,
37   * which simply delegates to JDBC's direct accessor methods, avoiding
38   * <code>java.sql.Blob</code> and <code>java.sql.Clob</code> completely.
39   *
40   * <p>Unfortunately, Oracle 9i just accepts Blob/Clob instances created via its own
41   * proprietary BLOB/CLOB API, and additionally doesn't accept large streams for
42   * PreparedStatement's corresponding setter methods. Therefore, you need to use
43   * OracleLobHandler there, which uses Oracle's BLOB/CLOB API for both all access.
44   * The Oracle 10g JDBC driver should work with DefaultLobHandler too.
45   *
46   * <p>Of course, you need to declare different field types for each database.
47   * In Oracle, any binary content needs to go into a BLOB, and all character content
48   * beyond 4000 bytes needs to go into a CLOB. In MySQL, there is no notion of a
49   * CLOB type but rather a LONGTEXT type that behaves like a VARCHAR. For complete
50   * portability, just use a LobHandler for fields that might typically require LOBs
51   * on some database because of their size (take Oracle's numbers as a guideline).
52   *
53   * @author Juergen Hoeller
54   * @since 23.12.2003
55   * @see DefaultLobHandler
56   * @see OracleLobHandler
57   * @see java.sql.ResultSet#getBlob
58   * @see java.sql.ResultSet#getClob
59   * @see java.sql.ResultSet#getBytes
60   * @see java.sql.ResultSet#getBinaryStream
61   * @see java.sql.ResultSet#getString
62   * @see java.sql.ResultSet#getAsciiStream
63   * @see java.sql.ResultSet#getCharacterStream
64   */
65  public interface LobHandler {
66  
67      /**
68       * Retrieve the given column as bytes from the given ResultSet.
69       * Might simply invoke <code>ResultSet.getBytes</code> or work with
70       * <code>ResultSet.getBlob</code>, depending on the database and driver.
71       * @param rs the ResultSet to retrieve the content from
72       * @param columnName the column name to use
73       * @return the content as byte array, or <code>null</code> in case of SQL NULL
74       * @throws SQLException if thrown by JDBC methods
75       * @see java.sql.ResultSet#getBytes
76       */
77      byte[] getBlobAsBytes(ResultSet   rs, String   columnName) throws SQLException  ;
78  
79      /**
80       * Retrieve the given column as bytes from the given ResultSet.
81       * Might simply invoke <code>ResultSet.getBytes</code> or work with
82       * <code>ResultSet.getBlob</code>, depending on the database and driver.
83       * @param rs the ResultSet to retrieve the content from
84       * @param columnIndex the column index to use
85       * @return the content as byte array, or <code>null</code> in case of SQL NULL
86       * @throws SQLException if thrown by JDBC methods
87       * @see java.sql.ResultSet#getBytes
88       */
89      byte[] getBlobAsBytes(ResultSet   rs, int columnIndex) throws SQLException  ;
90  
91      /**
92       * Retrieve the given column as binary stream from the given ResultSet.
93       * Might simply invoke <code>ResultSet.getBinaryStream</code> or work with
94       * <code>ResultSet.getBlob</code>, depending on the database and driver.
95       * @param rs the ResultSet to retrieve the content from
96       * @param columnName the column name to use
97       * @return the content as binary stream, or <code>null</code> in case of SQL NULL
98       * @throws SQLException if thrown by JDBC methods
99       * @see java.sql.ResultSet#getBinaryStream
100      */
101     InputStream   getBlobAsBinaryStream(ResultSet   rs, String   columnName) throws SQLException  ;
102 
103     /**
104      * Retrieve the given column as binary stream from the given ResultSet.
105      * Might simply invoke <code>ResultSet.getBinaryStream</code> or work with
106      * <code>ResultSet.getBlob</code>, depending on the database and driver.
107      * @param rs the ResultSet to retrieve the content from
108      * @param columnIndex the column index to use
109      * @return the content as binary stream, or <code>null</code> in case of SQL NULL
110      * @throws SQLException if thrown by JDBC methods
111      * @see java.sql.ResultSet#getBinaryStream
112      */
113     InputStream   getBlobAsBinaryStream(ResultSet   rs, int columnIndex) throws SQLException  ;
114 
115     /**
116      * Retrieve the given column as String from the given ResultSet.
117      * Might simply invoke <code>ResultSet.getString</code> or work with
118      * <code>ResultSet.getClob</code>, depending on the database and driver.
119      * @param rs the ResultSet to retrieve the content from
120      * @param columnName the column name to use
121      * @return the content as String, or <code>null</code> in case of SQL NULL
122      * @throws SQLException if thrown by JDBC methods
123      * @see java.sql.ResultSet#getString
124      */
125     String   getClobAsString(ResultSet   rs, String   columnName) throws SQLException  ;
126 
127     /**
128      * Retrieve the given column as String from the given ResultSet.
129      * Might simply invoke <code>ResultSet.getString</code> or work with
130      * <code>ResultSet.getClob</code>, depending on the database and driver.
131      * @param rs the ResultSet to retrieve the content from
132      * @param columnIndex the column index to use
133      * @return the content as String, or <code>null</code> in case of SQL NULL
134      * @throws SQLException if thrown by JDBC methods
135      * @see java.sql.ResultSet#getString
136      */
137     String   getClobAsString(ResultSet   rs, int columnIndex) throws SQLException  ;
138 
139     /**
140      * Retrieve the given column as ASCII stream from the given ResultSet.
141      * Might simply invoke <code>ResultSet.getAsciiStream</code> or work with
142      * <code>ResultSet.getClob</code>, depending on the database and driver.
143      * @param rs the ResultSet to retrieve the content from
144      * @param columnName the column name to use
145      * @return the content as ASCII stream, or <code>null</code> in case of SQL NULL
146      * @throws SQLException if thrown by JDBC methods
147      * @see java.sql.ResultSet#getAsciiStream
148      */
149     InputStream   getClobAsAsciiStream(ResultSet   rs, String   columnName) throws SQLException  ;
150 
151     /**
152      * Retrieve the given column as ASCII stream from the given ResultSet.
153      * Might simply invoke <code>ResultSet.getAsciiStream</code> or work with
154      * <code>ResultSet.getClob</code>, depending on the database and driver.
155      * @param rs the ResultSet to retrieve the content from
156      * @param columnIndex the column index to use
157      * @return the content as ASCII stream, or <code>null</code> in case of SQL NULL
158      * @throws SQLException if thrown by JDBC methods
159      * @see java.sql.ResultSet#getAsciiStream
160      */
161     InputStream   getClobAsAsciiStream(ResultSet   rs, int columnIndex) throws SQLException  ;
162 
163     /**
164      * Retrieve the given column as character stream from the given ResultSet.
165      * Might simply invoke <code>ResultSet.getCharacterStream</code> or work with
166      * <code>ResultSet.getClob</code>, depending on the database and driver.
167      * @param rs the ResultSet to retrieve the content from
168      * @param columnName the column name to use
169      * @return the content as character stream
170      * @throws SQLException if thrown by JDBC methods
171      * @see java.sql.ResultSet#getCharacterStream
172      */
173     Reader   getClobAsCharacterStream(ResultSet   rs, String   columnName) throws SQLException  ;
174 
175     /**
176      * Retrieve the given column as character stream from the given ResultSet.
177      * Might simply invoke <code>ResultSet.getCharacterStream</code> or work with
178      * <code>ResultSet.getClob</code>, depending on the database and driver.
179      * @param rs the ResultSet to retrieve the content from
180      * @param columnIndex the column index to use
181      * @return the content as character stream
182      * @throws SQLException if thrown by JDBC methods
183      * @see java.sql.ResultSet#getCharacterStream
184      */
185     Reader   getClobAsCharacterStream(ResultSet   rs, int columnIndex) throws SQLException  ;
186 
187     /**
188      * Create a new LobCreator instance, i.e. a session for creating BLOBs
189      * and CLOBs. Needs to be closed after the created LOBs are not needed
190      * anymore, i.e. after statement execution or transaction completion.
191      * @return the new LobCreator instance
192      * @see LobCreator#close
193      */
194     LobCreator getLobCreator();
195 
196 }
197
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags