001 /*
002 * Copyright 2003-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 javax.sql.rowset.serial;
027
028 import java.sql.*;
029 import java.io.*;
030
031 /**
032 * A serialized mapping in the Java programming language of an SQL
033 * <code>CLOB</code> value.
034 * <P>
035 * The <code>SerialClob</code> class provides a constructor for creating
036 * an instance from a <code>Clob</code> object. Note that the <code>Clob</code>
037 * object should have brought the SQL <code>CLOB</code> value's data over
038 * to the client before a <code>SerialClob</code> object
039 * is constructed from it. The data of an SQL <code>CLOB</code> value can
040 * be materialized on the client as a stream of Unicode characters.
041 * <P>
042 * <code>SerialClob</code> methods make it possible to get a substring
043 * from a <code>SerialClob</code> object or to locate the start of
044 * a pattern of characters.
045 *
046 * @author Jonathan Bruce
047 */
048 public class SerialClob implements Clob, Serializable, Cloneable {
049
050 /**
051 * A serialized array of characters containing the data of the SQL
052 * <code>CLOB</code> value that this <code>SerialClob</code> object
053 * represents.
054 *
055 * @serial
056 */
057 private char buf[];
058
059 /**
060 * Internal Clob representation if SerialClob is intialized with a
061 * Clob
062 */
063 private Clob clob;
064
065 /**
066 * The length in characters of this <code>SerialClob</code> object's
067 * internal array of characters.
068 *
069 * @serial
070 */
071 private long len;
072
073 /**
074 * The original length in characters of tgus <code>SerialClob</code>
075 * objects internal array of characters.
076 *
077 * @serial
078 */
079 private long origLen;
080
081 /**
082 * Constructs a <code>SerialClob</code> object that is a serialized version of
083 * the given <code>char</code> array.
084 * <p>
085 * The new <code>SerialClob</code> object is initialized with the data from the
086 * <code>char</code> array, thus allowing disconnected <code>RowSet</code>
087 * objects to establish a serialized <code>Clob</code> object without touching
088 * the data source.
089 *
090 * @param ch the char array representing the <code>Clob</code> object to be
091 * serialized
092 * @throws SerialException if an error occurs during serialization
093 * @throws SQLException if a SQL error occurs
094 */
095 public SerialClob(char ch[]) throws SerialException, SQLException {
096
097 // %%% JMB. Agreed. Add code here to throw a SQLException if no
098 // support is available for locatorsUpdateCopy=false
099 // Serializing locators is not supported.
100
101 len = ch.length;
102 buf = new char[(int) len];
103 for (int i = 0; i < len; i++) {
104 buf[i] = ch[i];
105 }
106 origLen = len;
107 }
108
109 /**
110 * Constructs a <code>SerialClob</code> object that is a serialized
111 * version of the given <code>Clob</code> object.
112 * <P>
113 * The new <code>SerialClob</code> object is initialized with the
114 * data from the <code>Clob</code> object; therefore, the
115 * <code>Clob</code> object should have previously brought the
116 * SQL <code>CLOB</code> value's data over to the client from
117 * the database. Otherwise, the new <code>SerialClob</code> object
118 * object will contain no data.
119 * <p>
120 * Note: The <code>Clob</code> object supplied to this constructor cannot
121 * return <code>null</code> for the <code>Clob.getCharacterStream()</code>
122 * and <code>Clob.getAsciiStream</code> methods. This <code>SerialClob</code>
123 * constructor cannot serialize a <code>Clob</code> object in this instance
124 * and will throw an <code>SQLException</code> object.
125 *
126 * @param clob the <code>Clob</code> object from which this
127 * <code>SerialClob</code> object is to be constructed; cannot be null
128 * @throws SerialException if an error occurs during serialization
129 * @throws SQLException if a SQL error occurs in capturing the CLOB;
130 * if the <code>Clob</code> object is a null; or if both the
131 * <code>Clob.getCharacterStream()</code> and <code>Clob.getAsciiStream()</code>
132 * methods on the <code>Clob</code> return a null
133 * @see java.sql.Clob
134 */
135 public SerialClob(Clob clob) throws SerialException, SQLException {
136
137 if (clob == null) {
138 throw new SQLException("Cannot instantiate a SerialClob "
139 + "object with a null Clob object");
140 }
141 len = clob.length();
142 this .clob = clob;
143 buf = new char[(int) len];
144 int read = 0;
145 int offset = 0;
146
147 BufferedReader reader;
148 if ((((reader = new BufferedReader(clob.getCharacterStream())) == null))
149 && (clob.getAsciiStream() == null)) {
150 throw new SQLException(
151 "Invalid Clob object. Calls to getCharacterStream "
152 + "and getAsciiStream return null which cannot be serialized.");
153 }
154
155 try {
156 do {
157 read = reader.read(buf, offset, (int) (len - offset));
158 offset += read;
159 } while (read > 0);
160
161 } catch (java.io.IOException ex) {
162 throw new SerialException("SerialClob: " + ex.getMessage());
163 }
164
165 origLen = len;
166 }
167
168 /**
169 * Retrieves the number of characters in this <code>SerialClob</code>
170 * object's array of characters.
171 *
172 * @return a <code>long</code> indicating the length in characters of this
173 * <code>SerialClob</code> object's array of character
174 * @throws SerialException if an error occurs
175 */
176 public long length() throws SerialException {
177 return len;
178 }
179
180 /**
181 * Returns this <code>SerialClob</code> object's data as a stream
182 * of Unicode characters. Unlike the related method, <code>getAsciiStream</code>,
183 * a stream is produced regardless of whether the <code>SerialClob</code> object
184 * was created with a <code>Clob</code> object or a <code>char</code> array.
185 *
186 * @return a <code>java.io.Reader</code> object containing this
187 * <code>SerialClob</code> object's data
188 * @throws SerialException if an error occurs
189 */
190 public java.io.Reader getCharacterStream() throws SerialException {
191 return (java.io.Reader) new CharArrayReader(buf);
192 }
193
194 /**
195 * Retrieves the <code>CLOB</code> value designated by this <code>SerialClob</code>
196 * object as an ascii stream. This method forwards the <code>getAsciiStream</code>
197 * call to the underlying <code>Clob</code> object in the event that this
198 * <code>SerialClob</code> object is instantiated with a <code>Clob</code>
199 * object. If this <code>SerialClob</code> object is instantiated with
200 * a <code>char</code> array, a <code>SerialException</code> object is thrown.
201 *
202 * @return a <code>java.io.InputStream</code> object containing
203 * this <code>SerialClob</code> object's data
204 * @throws SerialException if this <code>SerialClob</code> object was not instantiated
205 * with a <code>Clob</code> object
206 * @throws SQLException if there is an error accessing the
207 * <code>CLOB</code> value represented by the <code>Clob</code> object that was
208 * used to create this <code>SerialClob</code> object
209 */
210 public java.io.InputStream getAsciiStream() throws SerialException,
211 SQLException {
212 if (this .clob != null) {
213 return this .clob.getAsciiStream();
214 } else {
215 throw new SerialException(
216 "Unsupported operation. SerialClob cannot "
217 + "return a the CLOB value as an ascii stream, unless instantiated "
218 + "with a fully implemented Clob object.");
219 }
220 }
221
222 /**
223 * Returns a copy of the substring contained in this
224 * <code>SerialClob</code> object, starting at the given position
225 * and continuing for the specified number or characters.
226 *
227 * @param pos the position of the first character in the substring
228 * to be copied; the first character of the
229 * <code>SerialClob</code> object is at position
230 * <code>1</code>; must not be less than <code>1</code>,
231 * and the sum of the starting position and the length
232 * of the substring must be less than the length of this
233 * <code>SerialClob</code> object
234 * @param length the number of characters in the substring to be
235 * returned; must not be greater than the length of
236 * this <code>SerialClob</code> object, and the
237 * sum of the starting position and the length
238 * of the substring must be less than the length of this
239 * <code>SerialClob</code> object
240 * @return a <code>String</code> object containing a substring of
241 * this <code>SerialClob</code> object beginning at the
242 * given position and containing the specified number of
243 * consecutive characters
244 * @throws SerialException if either of the arguments is out of bounds
245 */
246 public String getSubString(long pos, int length)
247 throws SerialException {
248
249 if (pos < 1 || pos > this .length()) {
250 throw new SerialException(
251 "Invalid position in BLOB object set");
252 }
253
254 if ((pos - 1) + length > this .length()) {
255 throw new SerialException(
256 "Invalid position and substring length");
257 }
258
259 try {
260 return new String(buf, (int) pos - 1, length);
261
262 } catch (StringIndexOutOfBoundsException e) {
263 throw new SerialException(
264 "StringIndexOutOfBoundsException: "
265 + e.getMessage());
266 }
267
268 }
269
270 /**
271 * Returns the position in this <code>SerialClob</code> object
272 * where the given <code>String</code> object begins, starting
273 * the search at the specified position. This method returns
274 * <code>-1</code> if the pattern is not found.
275 *
276 * @param searchStr the <code>String</code> object for which to
277 * search
278 * @param start the position in this <code>SerialClob</code> object
279 * at which to start the search; the first position is
280 * <code>1</code>; must not be less than <code>1</code> nor
281 * greater than the length of this <code>SerialClob</code> object
282 * @return the position at which the given <code>String</code> object
283 * begins, starting the search at the specified position;
284 * <code>-1</code> if the given <code>String</code> object is
285 * not found or the starting position is out of bounds; position
286 * numbering for the return value starts at <code>1</code>
287 * @throws SerialException if an error occurs locating the String signature
288 * @throws SQLException if there is an error accessing the Blob value
289 * from the database.
290 */
291 public long position(String searchStr, long start)
292 throws SerialException, SQLException {
293
294 if (start < 1 || start > len) {
295 return -1;
296 }
297
298 char pattern[] = searchStr.toCharArray();
299
300 int pos = (int) start - 1;
301 int i = 0;
302 long patlen = pattern.length;
303
304 while (pos < len) {
305 if (pattern[i] == buf[pos]) {
306 if (i + 1 == patlen) {
307 return (pos + 1) - (patlen - 1);
308 }
309 i++;
310 pos++; // increment pos, and i
311
312 } else if (pattern[i] != buf[pos]) {
313 pos++; // increment pos only
314 }
315 }
316 return -1; // not found
317 }
318
319 /**
320 * Returns the position in this <code>SerialClob</code> object
321 * where the given <code>Clob</code> signature begins, starting
322 * the search at the specified position. This method returns
323 * <code>-1</code> if the pattern is not found.
324 *
325 * @param searchStr the <code>Clob</code> object for which to search
326 * @param start the position in this <code>SerialClob</code> object
327 * at which to begin the search; the first position is
328 * <code>1</code>; must not be less than <code>1</code> nor
329 * greater than the length of this <code>SerialClob</code> object
330 * @return the position at which the given <code>Clob</code>
331 * object begins in this <code>SerialClob</code> object,
332 * at or after the specified starting position
333 * @throws SerialException if an error occurs locating the Clob signature
334 * @throws SQLException if there is an error accessing the Blob value
335 * from the database
336 */
337 public long position(Clob searchStr, long start)
338 throws SerialException, SQLException {
339
340 return position(searchStr.getSubString(1, (int) searchStr
341 .length()), start);
342 }
343
344 /**
345 * Writes the given Java <code>String</code> to the <code>CLOB</code>
346 * value that this <code>SerialClob</code> object represents, at the position
347 * <code>pos</code>.
348 *
349 * @param pos the position at which to start writing to the <code>CLOB</code>
350 * value that this <code>SerialClob</code> object represents; the first
351 * position is <code>1</code>; must not be less than <code>1</code> nor
352 * greater than the length of this <code>SerialClob</code> object
353 * @param str the string to be written to the <code>CLOB</code>
354 * value that this <code>SerialClob</code> object represents
355 * @return the number of characters written
356 * @throws SerialException if there is an error accessing the
357 * <code>CLOB</code> value; if an invalid position is set; if an
358 * invalid offset value is set; if number of bytes to be written
359 * is greater than the <code>SerialClob</code> length; or the combined
360 * values of the length and offset is greater than the Clob buffer
361 */
362 public int setString(long pos, String str) throws SerialException {
363 return (setString(pos, str, 0, str.length()));
364 }
365
366 /**
367 * Writes <code>len</code> characters of <code>str</code>, starting
368 * at character <code>offset</code>, to the <code>CLOB</code> value
369 * that this <code>Clob</code> represents.
370 *
371 * @param pos the position at which to start writing to the <code>CLOB</code>
372 * value that this <code>SerialClob</code> object represents; the first
373 * position is <code>1</code>; must not be less than <code>1</code> nor
374 * greater than the length of this <code>SerialClob</code> object
375 * @param str the string to be written to the <code>CLOB</code>
376 * value that this <code>Clob</code> object represents
377 * @param offset the offset into <code>str</code> to start reading
378 * the characters to be written
379 * @param length the number of characters to be written
380 * @return the number of characters written
381 * @throws SerialException if there is an error accessing the
382 * <code>CLOB</code> value; if an invalid position is set; if an
383 * invalid offset value is set; if number of bytes to be written
384 * is greater than the <code>SerialClob</code> length; or the combined
385 * values of the length and offset is greater than the Clob buffer
386 */
387 public int setString(long pos, String str, int offset, int length)
388 throws SerialException {
389 String temp = str.substring(offset);
390 char cPattern[] = temp.toCharArray();
391
392 if (offset < 0 || offset > str.length()) {
393 throw new SerialException(
394 "Invalid offset in byte array set");
395 }
396
397 if (pos < 1 || pos > this .length()) {
398 throw new SerialException(
399 "Invalid position in BLOB object set");
400 }
401
402 if ((long) (length) > origLen) {
403 throw new SerialException(
404 "Buffer is not sufficient to hold the value");
405 }
406
407 if ((length + offset) > str.length()) {
408 // need check to ensure length + offset !> bytes.length
409 throw new SerialException(
410 "Invalid OffSet. Cannot have combined offset "
411 + " and length that is greater that the Blob buffer");
412 }
413
414 int i = 0;
415 pos--; //values in the array are at position one less
416 while (i < length || (offset + i + 1) < (str.length() - offset)) {
417 this .buf[(int) pos + i] = cPattern[offset + i];
418 i++;
419 }
420 return i;
421 }
422
423 /**
424 * Retrieves a stream to be used to write Ascii characters to the
425 * <code>CLOB</code> value that this <code>SerialClob</code> object represents,
426 * starting at position <code>pos</code>. This method forwards the
427 * <code>setAsciiStream()</code> call to the underlying <code>Clob</code> object in
428 * the event that this <code>SerialClob</code> object is instantiated with a
429 * <code>Clob</code> object. If this <code>SerialClob</code> object is instantiated
430 * with a <code>char</code> array, a <code>SerialException</code> object is thrown.
431 *
432 * @param pos the position at which to start writing to the
433 * <code>CLOB</code> object
434 * @return the stream to which ASCII encoded characters can be written
435 * @throws SerialException if SerialClob is not instantiated with a
436 * Clob object that supports <code>setAsciiStream</code>
437 * @throws SQLException if there is an error accessing the
438 * <code>CLOB</code> value
439 * @see #getAsciiStream
440 */
441 public java.io.OutputStream setAsciiStream(long pos)
442 throws SerialException, SQLException {
443 if (this .clob.setAsciiStream(pos) != null) {
444 return this .clob.setAsciiStream(pos);
445 } else {
446 throw new SerialException(
447 "Unsupported operation. SerialClob cannot "
448 + "return a writable ascii stream\n unless instantiated with a Clob object "
449 + "that has a setAsciiStream() implementation");
450 }
451 }
452
453 /**
454 * Retrieves a stream to be used to write a stream of Unicode characters
455 * to the <code>CLOB</code> value that this <code>SerialClob</code> object
456 * represents, at position <code>pos</code>. This method forwards the
457 * <code>setCharacterStream()</code> call to the underlying <code>Clob</code>
458 * object in the event that this <code>SerialClob</code> object is instantiated with a
459 * <code>Clob</code> object. If this <code>SerialClob</code> object is instantiated with
460 * a <code>char</code> array, a <code>SerialException</code> is thrown.
461 *
462 * @param pos the position at which to start writing to the
463 * <code>CLOB</code> value
464 *
465 * @return a stream to which Unicode encoded characters can be written
466 * @throws SerialException if the SerialClob is not instantiated with
467 * a Clob object that supports <code>setCharacterStream</code>
468 * @throws SQLException if there is an error accessing the
469 * <code>CLOB</code> value
470 * @see #getCharacterStream
471 */
472 public java.io.Writer setCharacterStream(long pos)
473 throws SerialException, SQLException {
474 if (this .clob.setCharacterStream(pos) != null) {
475 return this .clob.setCharacterStream(pos);
476 } else {
477 throw new SerialException(
478 "Unsupported operation. SerialClob cannot "
479 + "return a writable character stream\n unless instantiated with a Clob object "
480 + "that has a setCharacterStream implementation");
481 }
482 }
483
484 /**
485 * Truncates the <code>CLOB</code> value that this <code>SerialClob</code>
486 * object represents so that it has a length of <code>len</code>
487 * characters.
488 * <p>
489 * Truncating a <code>SerialClob</code> object to length 0 has the effect of
490 * clearing its contents.
491 *
492 * @param length the length, in bytes, to which the <code>CLOB</code>
493 * value should be truncated
494 * @throws SQLException if there is an error accessing the
495 * <code>CLOB</code> value
496 */
497 public void truncate(long length) throws SerialException {
498 if (length > len) {
499 throw new SerialException(
500 "Length more than what can be truncated");
501 } else {
502 len = length;
503 // re-size the buffer
504
505 if (len == 0) {
506 buf = new char[] {};
507 } else {
508 buf = (this .getSubString(1, (int) len)).toCharArray();
509 }
510
511 }
512 }
513
514 public Reader getCharacterStream(long pos, long length)
515 throws SQLException {
516 throw new java.lang.UnsupportedOperationException(
517 "Not supported");
518 }
519
520 public void free() throws SQLException {
521 throw new java.lang.UnsupportedOperationException(
522 "Not supported");
523 }
524
525 /**
526 * The identifier that assists in the serialization of this <code>SerialClob</code>
527 * object.
528 */
529 static final long serialVersionUID = -1662519690087375313L;
530 }
|