View Javadoc
1   /*
2    * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package java.sql;
27  
28  import java.io.Reader;
29  
30  /**
31   * The mapping in the Java™ programming language
32   * for the SQL <code>CLOB</code> type.
33   * An SQL <code>CLOB</code> is a built-in type
34   * that stores a Character Large Object as a column value in a row of
35   * a database table.
36   * By default drivers implement a <code>Clob</code> object using an SQL
37   * <code>locator(CLOB)</code>, which means that a <code>Clob</code> object
38   * contains a logical pointer to the SQL <code>CLOB</code> data rather than
39   * the data itself. A <code>Clob</code> object is valid for the duration
40   * of the transaction in which it was created.
41   * <P>The <code>Clob</code> interface provides methods for getting the
42   * length of an SQL <code>CLOB</code> (Character Large Object) value,
43   * for materializing a <code>CLOB</code> value on the client, and for
44   * searching for a substring or <code>CLOB</code> object within a
45   * <code>CLOB</code> value.
46   * Methods in the interfaces {@link ResultSet},
47   * {@link CallableStatement}, and {@link PreparedStatement}, such as
48   * <code>getClob</code> and <code>setClob</code> allow a programmer to
49   * access an SQL <code>CLOB</code> value.  In addition, this interface
50   * has methods for updating a <code>CLOB</code> value.
51   * <p>
52   * All methods on the <code>Clob</code> interface must be fully implemented if the
53   * JDBC driver supports the data type.
54   *
55   * @since 1.2
56   */
57  
58  public interface Clob {
59  
60    /**
61     * Retrieves the number of characters
62     * in the <code>CLOB</code> value
63     * designated by this <code>Clob</code> object.
64     *
65     * @return length of the <code>CLOB</code> in characters
66     * @exception SQLException if there is an error accessing the
67     *            length of the <code>CLOB</code> value
68     * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
69     * this method
70     * @since 1.2
71     */
72    long length() throws SQLException;
73  
74    /**
75     * Retrieves a copy of the specified substring
76     * in the <code>CLOB</code> value
77     * designated by this <code>Clob</code> object.
78     * The substring begins at position
79     * <code>pos</code> and has up to <code>length</code> consecutive
80     * characters.
81     *
82     * @param pos the first character of the substring to be extracted.
83     *            The first character is at position 1.
84     * @param length the number of consecutive characters to be copied;
85     * the value for length must be 0 or greater
86     * @return a <code>String</code> that is the specified substring in
87     *         the <code>CLOB</code> value designated by this <code>Clob</code> object
88     * @exception SQLException if there is an error accessing the
89     *            <code>CLOB</code> value; if pos is less than 1 or length is
90     * less than 0
91     * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
92     * this method
93     * @since 1.2
94     */
95    String getSubString(long pos, int length) throws SQLException;
96  
97    /**
98     * Retrieves the <code>CLOB</code> value designated by this <code>Clob</code>
99     * object as a <code>java.io.Reader</code> object (or as a stream of
100    * characters).
101    *
102    * @return a <code>java.io.Reader</code> object containing the
103    *         <code>CLOB</code> data
104    * @exception SQLException if there is an error accessing the
105    *            <code>CLOB</code> value
106    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
107    * this method
108    * @see #setCharacterStream
109    * @since 1.2
110    */
111   java.io.Reader getCharacterStream() throws SQLException;
112 
113   /**
114    * Retrieves the <code>CLOB</code> value designated by this <code>Clob</code>
115    * object as an ascii stream.
116    *
117    * @return a <code>java.io.InputStream</code> object containing the
118    *         <code>CLOB</code> data
119    * @exception SQLException if there is an error accessing the
120    *            <code>CLOB</code> value
121    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
122    * this method
123    * @see #setAsciiStream
124    * @since 1.2
125    */
126   java.io.InputStream getAsciiStream() throws SQLException;
127 
128   /**
129    * Retrieves the character position at which the specified substring
130    * <code>searchstr</code> appears in the SQL <code>CLOB</code> value
131    * represented by this <code>Clob</code> object.  The search
132    * begins at position <code>start</code>.
133    *
134    * @param searchstr the substring for which to search
135    * @param start the position at which to begin searching; the first position
136    *              is 1
137    * @return the position at which the substring appears or -1 if it is not
138    *         present; the first position is 1
139    * @exception SQLException if there is an error accessing the
140    *            <code>CLOB</code> value or if pos is less than 1
141    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
142    * this method
143    * @since 1.2
144    */
145   long position(String searchstr, long start) throws SQLException;
146 
147   /**
148    * Retrieves the character position at which the specified
149    * <code>Clob</code> object <code>searchstr</code> appears in this
150    * <code>Clob</code> object.  The search begins at position
151    * <code>start</code>.
152    *
153    * @param searchstr the <code>Clob</code> object for which to search
154    * @param start the position at which to begin searching; the first
155    *              position is 1
156    * @return the position at which the <code>Clob</code> object appears
157    *              or -1 if it is not present; the first position is 1
158    * @exception SQLException if there is an error accessing the
159    *            <code>CLOB</code> value or if start is less than 1
160    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
161    * this method
162    * @since 1.2
163    */
164   long position(Clob searchstr, long start) throws SQLException;
165 
166     //---------------------------- jdbc 3.0 -----------------------------------
167 
168     /**
169      * Writes the given Java <code>String</code> to the <code>CLOB</code>
170      * value that this <code>Clob</code> object designates at the position
171      * <code>pos</code>. The string will overwrite the existing characters
172      * in the <code>Clob</code> object starting at the position
173      * <code>pos</code>.  If the end of the <code>Clob</code> value is reached
174      * while writing the given string, then the length of the <code>Clob</code>
175      * value will be increased to accommodate the extra characters.
176      * <p>
177      * <b>Note:</b> If the value specified for <code>pos</code>
178      * is greater then the length+1 of the <code>CLOB</code> value then the
179      * behavior is undefined. Some JDBC drivers may throw a
180      * <code>SQLException</code> while other drivers may support this
181      * operation.
182      *
183      * @param pos the position at which to start writing to the <code>CLOB</code>
184      *         value that this <code>Clob</code> object represents;
185      * The first position is 1
186      * @param str the string to be written to the <code>CLOB</code>
187      *        value that this <code>Clob</code> designates
188      * @return the number of characters written
189      * @exception SQLException if there is an error accessing the
190      *            <code>CLOB</code> value or if pos is less than 1
191      *
192      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
193      * this method
194      * @since 1.4
195      */
196     int setString(long pos, String str) throws SQLException;
197 
198     /**
199      * Writes <code>len</code> characters of <code>str</code>, starting
200      * at character <code>offset</code>, to the <code>CLOB</code> value
201      * that this <code>Clob</code> represents.  The string will overwrite the existing characters
202      * in the <code>Clob</code> object starting at the position
203      * <code>pos</code>.  If the end of the <code>Clob</code> value is reached
204      * while writing the given string, then the length of the <code>Clob</code>
205      * value will be increased to accommodate the extra characters.
206      * <p>
207      * <b>Note:</b> If the value specified for <code>pos</code>
208      * is greater then the length+1 of the <code>CLOB</code> value then the
209      * behavior is undefined. Some JDBC drivers may throw a
210      * <code>SQLException</code> while other drivers may support this
211      * operation.
212      *
213      * @param pos the position at which to start writing to this
214      *        <code>CLOB</code> object; The first position  is 1
215      * @param str the string to be written to the <code>CLOB</code>
216      *        value that this <code>Clob</code> object represents
217      * @param offset the offset into <code>str</code> to start reading
218      *        the characters to be written
219      * @param len the number of characters to be written
220      * @return the number of characters written
221      * @exception SQLException if there is an error accessing the
222      *            <code>CLOB</code> value or if pos is less than 1
223      *
224      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
225      * this method
226      * @since 1.4
227      */
228     int setString(long pos, String str, int offset, int len) throws SQLException;
229 
230     /**
231      * Retrieves a stream to be used to write Ascii characters to the
232      * <code>CLOB</code> value that this <code>Clob</code> object represents,
233      * starting at position <code>pos</code>.  Characters written to the stream
234      * will overwrite the existing characters
235      * in the <code>Clob</code> object starting at the position
236      * <code>pos</code>.  If the end of the <code>Clob</code> value is reached
237      * while writing characters to the stream, then the length of the <code>Clob</code>
238      * value will be increased to accommodate the extra characters.
239      * <p>
240      * <b>Note:</b> If the value specified for <code>pos</code>
241      * is greater then the length+1 of the <code>CLOB</code> value then the
242      * behavior is undefined. Some JDBC drivers may throw a
243      * <code>SQLException</code> while other drivers may support this
244      * operation.
245      *
246      * @param pos the position at which to start writing to this
247      *        <code>CLOB</code> object; The first position is 1
248      * @return the stream to which ASCII encoded characters can be written
249      * @exception SQLException if there is an error accessing the
250      *            <code>CLOB</code> value or if pos is less than 1
251      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
252      * this method
253      * @see #getAsciiStream
254      *
255      * @since 1.4
256      */
257     java.io.OutputStream setAsciiStream(long pos) throws SQLException;
258 
259     /**
260      * Retrieves a stream to be used to write a stream of Unicode characters
261      * to the <code>CLOB</code> value that this <code>Clob</code> object
262      * represents, at position <code>pos</code>. Characters written to the stream
263      * will overwrite the existing characters
264      * in the <code>Clob</code> object starting at the position
265      * <code>pos</code>.  If the end of the <code>Clob</code> value is reached
266      * while writing characters to the stream, then the length of the <code>Clob</code>
267      * value will be increased to accommodate the extra characters.
268      * <p>
269      * <b>Note:</b> If the value specified for <code>pos</code>
270      * is greater then the length+1 of the <code>CLOB</code> value then the
271      * behavior is undefined. Some JDBC drivers may throw a
272      * <code>SQLException</code> while other drivers may support this
273      * operation.
274      *
275      * @param  pos the position at which to start writing to the
276      *        <code>CLOB</code> value; The first position is 1
277      *
278      * @return a stream to which Unicode encoded characters can be written
279      * @exception SQLException if there is an error accessing the
280      *            <code>CLOB</code> value or if pos is less than 1
281      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
282      * this method
283      * @see #getCharacterStream
284      *
285      * @since 1.4
286      */
287     java.io.Writer setCharacterStream(long pos) throws SQLException;
288 
289     /**
290      * Truncates the <code>CLOB</code> value that this <code>Clob</code>
291      * designates to have a length of <code>len</code>
292      * characters.
293      * <p>
294      * <b>Note:</b> If the value specified for <code>pos</code>
295      * is greater then the length+1 of the <code>CLOB</code> value then the
296      * behavior is undefined. Some JDBC drivers may throw a
297      * <code>SQLException</code> while other drivers may support this
298      * operation.
299      *
300      * @param len the length, in characters, to which the <code>CLOB</code> value
301      *        should be truncated
302      * @exception SQLException if there is an error accessing the
303      *            <code>CLOB</code> value or if len is less than 0
304      *
305      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
306      * this method
307      * @since 1.4
308      */
309     void truncate(long len) throws SQLException;
310 
311     /**
312      * This method frees the <code>Clob</code> object and releases the resources the resources
313      * that it holds.  The object is invalid once the <code>free</code> method
314      * is called.
315      * <p>
316      * After <code>free</code> has been called, any attempt to invoke a
317      * method other than <code>free</code> will result in a <code>SQLException</code>
318      * being thrown.  If <code>free</code> is called multiple times, the subsequent
319      * calls to <code>free</code> are treated as a no-op.
320      * <p>
321      * @throws SQLException if an error occurs releasing
322      * the Clob's resources
323      *
324      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
325      * this method
326      * @since 1.6
327      */
328     void free() throws SQLException;
329 
330     /**
331      * Returns a <code>Reader</code> object that contains a partial <code>Clob</code> value, starting
332      * with the character specified by pos, which is length characters in length.
333      *
334      * @param pos the offset to the first character of the partial value to
335      * be retrieved.  The first character in the Clob is at position 1.
336      * @param length the length in characters of the partial value to be retrieved.
337      * @return <code>Reader</code> through which the partial <code>Clob</code> value can be read.
338      * @throws SQLException if pos is less than 1 or if pos is greater than the number of
339      * characters in the <code>Clob</code> or if pos + length is greater than the number of
340      * characters in the <code>Clob</code>
341      *
342      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
343      * this method
344      * @since 1.6
345      */
346     Reader getCharacterStream(long pos, long length) throws SQLException;
347 
348 }