001: /*
002: * Copyright 1998-2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package java.sql;
027:
028: import java.io.Reader;
029:
030: /**
031: * The mapping in the Java<sup><font size=-2>TM</font></sup> programming language
032: * for the SQL <code>CLOB</code> type.
033: * An SQL <code>CLOB</code> is a built-in type
034: * that stores a Character Large Object as a column value in a row of
035: * a database table.
036: * By default drivers implement a <code>Clob</code> object using an SQL
037: * <code>locator(CLOB)</code>, which means that a <code>Clob</code> object
038: * contains a logical pointer to the SQL <code>CLOB</code> data rather than
039: * the data itself. A <code>Clob</code> object is valid for the duration
040: * of the transaction in which it was created.
041: * <P>The <code>Clob</code> interface provides methods for getting the
042: * length of an SQL <code>CLOB</code> (Character Large Object) value,
043: * for materializing a <code>CLOB</code> value on the client, and for
044: * searching for a substring or <code>CLOB</code> object within a
045: * <code>CLOB</code> value.
046: * Methods in the interfaces {@link ResultSet},
047: * {@link CallableStatement}, and {@link PreparedStatement}, such as
048: * <code>getClob</code> and <code>setClob</code> allow a programmer to
049: * access an SQL <code>CLOB</code> value. In addition, this interface
050: * has methods for updating a <code>CLOB</code> value.
051: * <p>
052: * All methods on the <code>Clob</code> interface must be fully implemented if the
053: * JDBC driver supports the data type.
054: *
055: * @since 1.2
056: */
057:
058: public interface Clob {
059:
060: /**
061: * Retrieves the number of characters
062: * in the <code>CLOB</code> value
063: * designated by this <code>Clob</code> object.
064: *
065: * @return length of the <code>CLOB</code> in characters
066: * @exception SQLException if there is an error accessing the
067: * length of the <code>CLOB</code> value
068: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
069: * this method
070: * @since 1.2
071: */
072: long length() throws SQLException;
073:
074: /**
075: * Retrieves a copy of the specified substring
076: * in the <code>CLOB</code> value
077: * designated by this <code>Clob</code> object.
078: * The substring begins at position
079: * <code>pos</code> and has up to <code>length</code> consecutive
080: * characters.
081: *
082: * @param pos the first character of the substring to be extracted.
083: * The first character is at position 1.
084: * @param length the number of consecutive characters to be copied;
085: * the value for length must be 0 or greater
086: * @return a <code>String</code> that is the specified substring in
087: * the <code>CLOB</code> value designated by this <code>Clob</code> object
088: * @exception SQLException if there is an error accessing the
089: * <code>CLOB</code> value; if pos is less than 1 or length is
090: * less than 0
091: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
092: * this method
093: * @since 1.2
094: */
095: String getSubString(long pos, int length) throws SQLException;
096:
097: /**
098: * Retrieves the <code>CLOB</code> value designated by this <code>Clob</code>
099: * 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 accomodate 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 accomodate 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)
229: throws SQLException;
230:
231: /**
232: * Retrieves a stream to be used to write Ascii characters to the
233: * <code>CLOB</code> value that this <code>Clob</code> object represents,
234: * starting at position <code>pos</code>. Characters written to the stream
235: * will overwrite the existing characters
236: * in the <code>Clob</code> object starting at the position
237: * <code>pos</code>. If the end of the <code>Clob</code> value is reached
238: * while writing characters to the stream, then the length of the <code>Clob</code>
239: * value will be increased to accomodate the extra characters.
240: * <p>
241: * <b>Note:</b> If the value specified for <code>pos</code>
242: * is greater then the length+1 of the <code>CLOB</code> value then the
243: * behavior is undefined. Some JDBC drivers may throw a
244: * <code>SQLException</code> while other drivers may support this
245: * operation.
246: *
247: * @param pos the position at which to start writing to this
248: * <code>CLOB</code> object; The first position is 1
249: * @return the stream to which ASCII encoded characters can be written
250: * @exception SQLException if there is an error accessing the
251: * <code>CLOB</code> value or if pos is less than 1
252: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
253: * this method
254: * @see #getAsciiStream
255: *
256: * @since 1.4
257: */
258: java.io.OutputStream setAsciiStream(long pos) throws SQLException;
259:
260: /**
261: * Retrieves a stream to be used to write a stream of Unicode characters
262: * to the <code>CLOB</code> value that this <code>Clob</code> object
263: * represents, at position <code>pos</code>. Characters written to the stream
264: * will overwrite the existing characters
265: * in the <code>Clob</code> object starting at the position
266: * <code>pos</code>. If the end of the <code>Clob</code> value is reached
267: * while writing characters to the stream, then the length of the <code>Clob</code>
268: * value will be increased to accomodate the extra characters.
269: * <p>
270: * <b>Note:</b> If the value specified for <code>pos</code>
271: * is greater then the length+1 of the <code>CLOB</code> value then the
272: * behavior is undefined. Some JDBC drivers may throw a
273: * <code>SQLException</code> while other drivers may support this
274: * operation.
275: *
276: * @param pos the position at which to start writing to the
277: * <code>CLOB</code> value; The first position is 1
278: *
279: * @return a stream to which Unicode encoded characters can be written
280: * @exception SQLException if there is an error accessing the
281: * <code>CLOB</code> value or if pos is less than 1
282: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
283: * this method
284: * @see #getCharacterStream
285: *
286: * @since 1.4
287: */
288: java.io.Writer setCharacterStream(long pos) throws SQLException;
289:
290: /**
291: * Truncates the <code>CLOB</code> value that this <code>Clob</code>
292: * designates to have a length of <code>len</code>
293: * characters.
294: * <p>
295: * <b>Note:</b> If the value specified for <code>pos</code>
296: * is greater then the length+1 of the <code>CLOB</code> value then the
297: * behavior is undefined. Some JDBC drivers may throw a
298: * <code>SQLException</code> while other drivers may support this
299: * operation.
300: *
301: * @param len the length, in characters, to which the <code>CLOB</code> value
302: * should be truncated
303: * @exception SQLException if there is an error accessing the
304: * <code>CLOB</code> value or if len is less than 0
305: *
306: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
307: * this method
308: * @since 1.4
309: */
310: void truncate(long len) throws SQLException;
311:
312: /**
313: * This method frees the <code>Clob</code> object and releases the resources the resources
314: * that it holds. The object is invalid once the <code>free</code> method
315: * is called.
316: * <p>
317: * After <code>free</code> has been called, any attempt to invoke a
318: * method other than <code>free</code> will result in a <code>SQLException</code>
319: * being thrown. If <code>free</code> is called multiple times, the subsequent
320: * calls to <code>free</code> are treated as a no-op.
321: * <p>
322: * @throws SQLException if an error occurs releasing
323: * the Clob's resources
324: *
325: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
326: * this method
327: * @since 1.6
328: */
329: void free() throws SQLException;
330:
331: /**
332: * Returns a <code>Reader</code> object that contains a partial <code>Clob</code> value, starting
333: * with the character specified by pos, which is length characters in length.
334: *
335: * @param pos the offset to the first character of the partial value to
336: * be retrieved. The first character in the Clob is at position 1.
337: * @param length the length in characters of the partial value to be retrieved.
338: * @return <code>Reader</code> through which the partial <code>Clob</code> value can be read.
339: * @throws SQLException if pos is less than 1 or if pos is greater than the number of
340: * characters in the <code>Clob</code> or if pos + length is greater than the number of
341: * characters in the <code>Clob</code>
342: *
343: * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
344: * this method
345: * @since 1.6
346: */
347: Reader getCharacterStream(long pos, long length)
348: throws SQLException;
349:
350: }
| 