History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/java/sql/Clob.java (1 of 18352 files). Show all

Unified · Split

java/pkg/java/sql/Clob.java+348−0
@@ -0,0 +1,348 @@
1+/*
2+ * Copyright (c) 1998, 2006, 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<sup><font size=-2>TM</font></sup> 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 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) 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 accomodate 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 accomodate 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+}