KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > sql > Clob


1 /*
2  * @(#)Clob.java 1.29 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package java.sql;
9  
10 /**
11  * The mapping in the Java<sup><font size=-2>TM</font></sup> programming language
12  * for the SQL <code>CLOB</code> type.
13  * An SQL <code>CLOB</code> is a built-in type
14  * that stores a Character Large Object as a column value in a row of
15  * a database table.
16  * By default drivers implement a <code>Clob</code> object using an SQL
17  * <code>locator(CLOB)</code>, which means that a <code>Clob</code> object
18  * contains a logical pointer to the SQL <code>CLOB</code> data rather than
19  * the data itself. A <code>Clob</code> object is valid for the duration
20  * of the transaction in which it was created.
21  * <P>The <code>Clob</code> interface provides methods for getting the
22  * length of an SQL <code>CLOB</code> (Character Large Object) value,
23  * for materializing a <code>CLOB</code> value on the client, and for
24  * searching for a substring or <code>CLOB</code> object within a
25  * <code>CLOB</code> value.
26  * Methods in the interfaces {@link ResultSet},
27  * {@link CallableStatement}, and {@link PreparedStatement}, such as
28  * <code>getClob</code> and <code>setClob</code> allow a programmer to
29  * access an SQL <code>CLOB</code> value. In addition, this interface
30  * has methods for updating a <code>CLOB</code> value.
31  *
32  * @since 1.2
33  */

34
35 public interface Clob {
36
37   /**
38    * Retrieves the number of characters
39    * in the <code>CLOB</code> value
40    * designated by this <code>Clob</code> object.
41    *
42    * @return length of the <code>CLOB</code> in characters
43    * @exception SQLException if there is an error accessing the
44    * length of the <code>CLOB</code> value
45    * @since 1.2
46    */

47   long length() throws SQLException JavaDoc;
48
49   /**
50    * Retrieves a copy of the specified substring
51    * in the <code>CLOB</code> value
52    * designated by this <code>Clob</code> object.
53    * The substring begins at position
54    * <code>pos</code> and has up to <code>length</code> consecutive
55    * characters.
56    *
57    * @param pos the first character of the substring to be extracted.
58    * The first character is at position 1.
59    * @param length the number of consecutive characters to be copied
60    * @return a <code>String</code> that is the specified substring in
61    * the <code>CLOB</code> value designated by this <code>Clob</code> object
62    * @exception SQLException if there is an error accessing the
63    * <code>CLOB</code> value
64    * @since 1.2
65    */

66   String JavaDoc getSubString(long pos, int length) throws SQLException JavaDoc;
67
68   /**
69    * Retrieves the <code>CLOB</code> value designated by this <code>Clob</code>
70    * object as a <code>java.io.Reader</code> object (or as a stream of
71    * characters).
72    *
73    * @return a <code>java.io.Reader</code> object containing the
74    * <code>CLOB</code> data
75    * @exception SQLException if there is an error accessing the
76    * <code>CLOB</code> value
77    * @see #setCharacterStream
78    * @since 1.2
79    */

80   java.io.Reader JavaDoc getCharacterStream() throws SQLException JavaDoc;
81
82   /**
83    * Retrieves the <code>CLOB</code> value designated by this <code>Clob</code>
84    * object as an ascii stream.
85    *
86    * @return a <code>java.io.InputStream</code> object containing the
87    * <code>CLOB</code> data
88    * @exception SQLException if there is an error accessing the
89    * <code>CLOB</code> value
90    * @see #setAsciiStream
91    * @since 1.2
92    */

93   java.io.InputStream JavaDoc getAsciiStream() throws SQLException JavaDoc;
94
95   /**
96    * Retrieves the character position at which the specified substring
97    * <code>searchstr</code> appears in the SQL <code>CLOB</code> value
98    * represented by this <code>Clob</code> object. The search
99    * begins at position <code>start</code>.
100    *
101    * @param searchstr the substring for which to search
102    * @param start the position at which to begin searching; the first position
103    * is 1
104    * @return the position at which the substring appears or -1 if it is not
105    * present; the first position is 1
106    * @exception SQLException if there is an error accessing the
107    * <code>CLOB</code> value
108    * @since 1.2
109    */

110   long position(String JavaDoc searchstr, long start) throws SQLException JavaDoc;
111
112   /**
113    * Retrieves the character position at which the specified
114    * <code>Clob</code> object <code>searchstr</code> appears in this
115    * <code>Clob</code> object. The search begins at position
116    * <code>start</code>.
117    *
118    * @param searchstr the <code>Clob</code> object for which to search
119    * @param start the position at which to begin searching; the first
120    * position is 1
121    * @return the position at which the <code>Clob</code> object appears
122    * or -1 if it is not present; the first position is 1
123    * @exception SQLException if there is an error accessing the
124    * <code>CLOB</code> value
125    * @since 1.2
126    */

127   long position(Clob JavaDoc searchstr, long start) throws SQLException JavaDoc;
128
129     //---------------------------- jdbc 3.0 -----------------------------------
130

131     /**
132      * Writes the given Java <code>String</code> to the <code>CLOB</code>
133      * value that this <code>Clob</code> object designates at the position
134      * <code>pos</code>.
135      *
136      * @param pos the position at which to start writing to the <code>CLOB</code>
137      * value that this <code>Clob</code> object represents
138      * @param str the string to be written to the <code>CLOB</code>
139      * value that this <code>Clob</code> designates
140      * @return the number of characters written
141      * @exception SQLException if there is an error accessing the
142      * <code>CLOB</code> value
143      *
144      * @since 1.4
145      */

146     int setString(long pos, String JavaDoc str) throws SQLException JavaDoc;
147
148     /**
149      * Writes <code>len</code> characters of <code>str</code>, starting
150      * at character <code>offset</code>, to the <code>CLOB</code> value
151      * that this <code>Clob</code> represents.
152      *
153      * @param pos the position at which to start writing to this
154      * <code>CLOB</code> object
155      * @param str the string to be written to the <code>CLOB</code>
156      * value that this <code>Clob</code> object represents
157      * @param offset the offset into <code>str</code> to start reading
158      * the characters to be written
159      * @param len the number of characters to be written
160      * @return the number of characters written
161      * @exception SQLException if there is an error accessing the
162      * <code>CLOB</code> value
163      *
164      * @since 1.4
165      */

166     int setString(long pos, String JavaDoc str, int offset, int len) throws SQLException JavaDoc;
167
168     /**
169      * Retrieves a stream to be used to write Ascii characters to the
170      * <code>CLOB</code> value that this <code>Clob</code> object represents,
171      * starting at position <code>pos</code>.
172      *
173      * @param pos the position at which to start writing to this
174      * <code>CLOB</code> object
175      * @return the stream to which ASCII encoded characters can be written
176      * @exception SQLException if there is an error accessing the
177      * <code>CLOB</code> value
178      * @see #getAsciiStream
179      *
180      * @since 1.4
181      */

182     java.io.OutputStream JavaDoc setAsciiStream(long pos) throws SQLException JavaDoc;
183
184     /**
185      * Retrieves a stream to be used to write a stream of Unicode characters
186      * to the <code>CLOB</code> value that this <code>Clob</code> object
187      * represents, at position <code>pos</code>.
188      *
189      * @param pos the position at which to start writing to the
190      * <code>CLOB</code> value
191      *
192      * @return a stream to which Unicode encoded characters can be written
193      * @exception SQLException if there is an error accessing the
194      * <code>CLOB</code> value
195      * @see #getCharacterStream
196      *
197      * @since 1.4
198      */

199     java.io.Writer JavaDoc setCharacterStream(long pos) throws SQLException JavaDoc;
200
201     /**
202      * Truncates the <code>CLOB</code> value that this <code>Clob</code>
203      * designates to have a length of <code>len</code>
204      * characters.
205      * @param len the length, in bytes, to which the <code>CLOB</code> value
206      * should be truncated
207      * @exception SQLException if there is an error accessing the
208      * <code>CLOB</code> value
209      *
210      * @since 1.4
211      */

212     void truncate(long len) throws SQLException JavaDoc;
213
214 }
215
216
Popular Tags