1 /*
2 * Copyright 2003-2006 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package javax.sql.rowset.serial;
27
28 import java.sql;
29 import java.io;
30
31 /**
32 * A serialized mapping in the Java programming language of an SQL
33 * <code>CLOB</code> value.
34 * <P>
35 * The <code>SerialClob</code> class provides a constructor for creating
36 * an instance from a <code>Clob</code> object. Note that the <code>Clob</code>
37 * object should have brought the SQL <code>CLOB</code> value's data over
38 * to the client before a <code>SerialClob</code> object
39 * is constructed from it. The data of an SQL <code>CLOB</code> value can
40 * be materialized on the client as a stream of Unicode characters.
41 * <P>
42 * <code>SerialClob</code> methods make it possible to get a substring
43 * from a <code>SerialClob</code> object or to locate the start of
44 * a pattern of characters.
45 *
46 * @author Jonathan Bruce
47 */
48 public class SerialClob implements Clob, Serializable, Cloneable {
49
50 /**
51 * A serialized array of characters containing the data of the SQL
52 * <code>CLOB</code> value that this <code>SerialClob</code> object
53 * represents.
54 *
55 * @serial
56 */
57 private char buf[];
58
59 /**
60 * Internal Clob representation if SerialClob is intialized with a
61 * Clob
62 */
63 private Clob clob;
64
65 /**
66 * The length in characters of this <code>SerialClob</code> object's
67 * internal array of characters.
68 *
69 * @serial
70 */
71 private long len;
72
73 /**
74 * The original length in characters of tgus <code>SerialClob</code>
75 * objects internal array of characters.
76 *
77 * @serial
78 */
79 private long origLen;
80
81 /**
82 * Constructs a <code>SerialClob</code> object that is a serialized version of
83 * the given <code>char</code> array.
84 * <p>
85 * The new <code>SerialClob</code> object is initialized with the data from the
86 * <code>char</code> array, thus allowing disconnected <code>RowSet</code>
87 * objects to establish a serialized <code>Clob</code> object without touching
88 * the data source.
89 *
90 * @param ch the char array representing the <code>Clob</code> object to be
91 * serialized
92 * @throws SerialException if an error occurs during serialization
93 * @throws SQLException if a SQL error occurs
94 */
95 public SerialClob(char ch[]) throws SerialException, SQLException {
96
97 // %%% JMB. Agreed. Add code here to throw a SQLException if no
98 // support is available for locatorsUpdateCopy=false
99 // 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("Invalid Clob object. Calls to getCharacterStream " +
151 "and getAsciiStream return null which cannot be serialized.");
152 }
153
154 try {
155 do {
156 read = reader.read(buf, offset, (int)(len - offset));
157 offset += read;
158 } while (read > 0);
159
160 } catch (java.io.IOException ex) {
161 throw new SerialException("SerialClob: " + ex.getMessage());
162 }
163
164 origLen = len;
165 }
166
167 /**
168 * Retrieves the number of characters in this <code>SerialClob</code>
169 * object's array of characters.
170 *
171 * @return a <code>long</code> indicating the length in characters of this
172 * <code>SerialClob</code> object's array of character
173 * @throws SerialException if an error occurs
174 */
175 public long length() throws SerialException {
176 return len;
177 }
178
179 /**
180 * Returns this <code>SerialClob</code> object's data as a stream
181 * of Unicode characters. Unlike the related method, <code>getAsciiStream</code>,
182 * a stream is produced regardless of whether the <code>SerialClob</code> object
183 * was created with a <code>Clob</code> object or a <code>char</code> array.
184 *
185 * @return a <code>java.io.Reader</code> object containing this
186 * <code>SerialClob</code> object's data
187 * @throws SerialException if an error occurs
188 */
189 public java.io.Reader getCharacterStream() throws SerialException {
190 return (java.io.Reader) new CharArrayReader(buf);
191 }
192
193 /**
194 * Retrieves the <code>CLOB</code> value designated by this <code>SerialClob</code>
195 * object as an ascii stream. This method forwards the <code>getAsciiStream</code>
196 * call to the underlying <code>Clob</code> object in the event that this
197 * <code>SerialClob</code> object is instantiated with a <code>Clob</code>
198 * object. If this <code>SerialClob</code> object is instantiated with
199 * a <code>char</code> array, a <code>SerialException</code> object is thrown.
200 *
201 * @return a <code>java.io.InputStream</code> object containing
202 * this <code>SerialClob</code> object's data
203 * @throws SerialException if this <code>SerialClob</code> object was not instantiated
204 * with a <code>Clob</code> object
205 * @throws SQLException if there is an error accessing the
206 * <code>CLOB</code> value represented by the <code>Clob</code> object that was
207 * used to create this <code>SerialClob</code> object
208 */
209 public java.io.InputStream getAsciiStream() throws SerialException, SQLException {
210 if (this.clob != null) {
211 return this.clob.getAsciiStream();
212 } else {
213 throw new SerialException("Unsupported operation. SerialClob cannot " +
214 "return a the CLOB value as an ascii stream, unless instantiated " +
215 "with a fully implemented Clob object.");
216 }
217 }
218
219 /**
220 * Returns a copy of the substring contained in this
221 * <code>SerialClob</code> object, starting at the given position
222 * and continuing for the specified number or characters.
223 *
224 * @param pos the position of the first character in the substring
225 * to be copied; the first character of the
226 * <code>SerialClob</code> object is at position
227 * <code>1</code>; must not be less than <code>1</code>,
228 * and the sum of the starting position and the length
229 * of the substring must be less than the length of this
230 * <code>SerialClob</code> object
231 * @param length the number of characters in the substring to be
232 * returned; must not be greater than the length of
233 * this <code>SerialClob</code> object, and the
234 * sum of the starting position and the length
235 * of the substring must be less than the length of this
236 * <code>SerialClob</code> object
237 * @return a <code>String</code> object containing a substring of
238 * this <code>SerialClob</code> object beginning at the
239 * given position and containing the specified number of
240 * consecutive characters
241 * @throws SerialException if either of the arguments is out of bounds
242 */
243 public String getSubString(long pos, int length) throws SerialException {
244
245 if (pos < 1 || pos > this.length()) {
246 throw new SerialException("Invalid position in BLOB object set");
247 }
248
249 if ((pos-1) + length > this.length()) {
250 throw new SerialException("Invalid position and substring length");
251 }
252
253 try {
254 return new String(buf, (int)pos - 1, length);
255
256 } catch (StringIndexOutOfBoundsException e) {
257 throw new SerialException("StringIndexOutOfBoundsException: " +
258 e.getMessage());
259 }
260
261 }
262
263 /**
264 * Returns the position in this <code>SerialClob</code> object
265 * where the given <code>String</code> object begins, starting
266 * the search at the specified position. This method returns
267 * <code>-1</code> if the pattern is not found.
268 *
269 * @param searchStr the <code>String</code> object for which to
270 * search
271 * @param start the position in this <code>SerialClob</code> object
272 * at which to start the search; the first position is
273 * <code>1</code>; must not be less than <code>1</code> nor
274 * greater than the length of this <code>SerialClob</code> object
275 * @return the position at which the given <code>String</code> object
276 * begins, starting the search at the specified position;
277 * <code>-1</code> if the given <code>String</code> object is
278 * not found or the starting position is out of bounds; position
279 * numbering for the return value starts at <code>1</code>
280 * @throws SerialException if an error occurs locating the String signature
281 * @throws SQLException if there is an error accessing the Blob value
282 * from the database.
283 */
284 public long position(String searchStr, long start)
285 throws SerialException, SQLException {
286
287 if (start < 1 || start > len) {
288 return -1;
289 }
290
291 char pattern[] = searchStr.toCharArray();
292
293 int pos = (int)start-1;
294 int i = 0;
295 long patlen = pattern.length;
296
297 while (pos < len) {
298 if (pattern[i] == buf[pos]) {
299 if (i + 1 == patlen) {
300 return (pos + 1) - (patlen - 1);
301 }
302 i++; pos++; // increment pos, and i
303
304 } else if (pattern[i] != buf[pos]) {
305 pos++; // increment pos only
306 }
307 }
308 return -1; // not found
309 }
310
311 /**
312 * Returns the position in this <code>SerialClob</code> object
313 * where the given <code>Clob</code> signature begins, starting
314 * the search at the specified position. This method returns
315 * <code>-1</code> if the pattern is not found.
316 *
317 * @param searchStr the <code>Clob</code> object for which to search
318 * @param start the position in this <code>SerialClob</code> object
319 * at which to begin the search; the first position is
320 * <code>1</code>; must not be less than <code>1</code> nor
321 * greater than the length of this <code>SerialClob</code> object
322 * @return the position at which the given <code>Clob</code>
323 * object begins in this <code>SerialClob</code> object,
324 * at or after the specified starting position
325 * @throws SerialException if an error occurs locating the Clob signature
326 * @throws SQLException if there is an error accessing the Blob value
327 * from the database
328 */
329 public long position(Clob searchStr, long start)
330 throws SerialException, SQLException {
331
332 return position(searchStr.getSubString(1,(int)searchStr.length()), start);
333 }
334
335 /**
336 * Writes the given Java <code>String</code> to the <code>CLOB</code>
337 * value that this <code>SerialClob</code> object represents, at the position
338 * <code>pos</code>.
339 *
340 * @param pos the position at which to start writing to the <code>CLOB</code>
341 * value that this <code>SerialClob</code> object represents; the first
342 * position is <code>1</code>; must not be less than <code>1</code> nor
343 * greater than the length of this <code>SerialClob</code> object
344 * @param str the string to be written to the <code>CLOB</code>
345 * value that this <code>SerialClob</code> object represents
346 * @return the number of characters written
347 * @throws SerialException if there is an error accessing the
348 * <code>CLOB</code> value; if an invalid position is set; if an
349 * invalid offset value is set; if number of bytes to be written
350 * is greater than the <code>SerialClob</code> length; or the combined
351 * values of the length and offset is greater than the Clob buffer
352 */
353 public int setString(long pos, String str) throws SerialException {
354 return (setString(pos, str, 0, str.length()));
355 }
356
357 /**
358 * Writes <code>len</code> characters of <code>str</code>, starting
359 * at character <code>offset</code>, to the <code>CLOB</code> value
360 * that this <code>Clob</code> represents.
361 *
362 * @param pos the position at which to start writing to the <code>CLOB</code>
363 * value that this <code>SerialClob</code> object represents; the first
364 * position is <code>1</code>; must not be less than <code>1</code> nor
365 * greater than the length of this <code>SerialClob</code> object
366 * @param str the string to be written to the <code>CLOB</code>
367 * value that this <code>Clob</code> object represents
368 * @param offset the offset into <code>str</code> to start reading
369 * the characters to be written
370 * @param length the number of characters to be written
371 * @return the number of characters written
372 * @throws SerialException if there is an error accessing the
373 * <code>CLOB</code> value; if an invalid position is set; if an
374 * invalid offset value is set; if number of bytes to be written
375 * is greater than the <code>SerialClob</code> length; or the combined
376 * values of the length and offset is greater than the Clob buffer
377 */
378 public int setString(long pos, String str, int offset, int length)
379 throws SerialException {
380 String temp = str.substring(offset);
381 char cPattern[] = temp.toCharArray();
382
383 if (offset < 0 || offset > str.length()) {
384 throw new SerialException("Invalid offset in byte array set");
385 }
386
387 if (pos < 1 || pos > this.length()) {
388 throw new SerialException("Invalid position in BLOB object set");
389 }
390
391 if ((long)(length) > origLen) {
392 throw new SerialException("Buffer is not sufficient to hold the value");
393 }
394
395 if ((length + offset) > str.length()) {
396 // need check to ensure length + offset !> bytes.length
397 throw new SerialException("Invalid OffSet. Cannot have combined offset " +
398 " and length that is greater that the Blob buffer");
399 }
400
401 int i = 0;
402 pos--; //values in the array are at position one less
403 while ( i < length || (offset + i +1) < (str.length() - offset ) ) {
404 this.buf[(int)pos + i ] = cPattern[offset + i ];
405 i++;
406 }
407 return i;
408 }
409
410 /**
411 * Retrieves a stream to be used to write Ascii characters to the
412 * <code>CLOB</code> value that this <code>SerialClob</code> object represents,
413 * starting at position <code>pos</code>. This method forwards the
414 * <code>setAsciiStream()</code> call to the underlying <code>Clob</code> object in
415 * the event that this <code>SerialClob</code> object is instantiated with a
416 * <code>Clob</code> object. If this <code>SerialClob</code> object is instantiated
417 * with a <code>char</code> array, a <code>SerialException</code> object is thrown.
418 *
419 * @param pos the position at which to start writing to the
420 * <code>CLOB</code> object
421 * @return the stream to which ASCII encoded characters can be written
422 * @throws SerialException if SerialClob is not instantiated with a
423 * Clob object that supports <code>setAsciiStream</code>
424 * @throws SQLException if there is an error accessing the
425 * <code>CLOB</code> value
426 * @see #getAsciiStream
427 */
428 public java.io.OutputStream setAsciiStream(long pos)
429 throws SerialException, SQLException {
430 if (this.clob.setAsciiStream(pos) != null) {
431 return this.clob.setAsciiStream(pos);
432 } else {
433 throw new SerialException("Unsupported operation. SerialClob cannot " +
434 "return a writable ascii stream\n unless instantiated with a Clob object " +
435 "that has a setAsciiStream() implementation");
436 }
437 }
438
439 /**
440 * Retrieves a stream to be used to write a stream of Unicode characters
441 * to the <code>CLOB</code> value that this <code>SerialClob</code> object
442 * represents, at position <code>pos</code>. This method forwards the
443 * <code>setCharacterStream()</code> call to the underlying <code>Clob</code>
444 * object in the event that this <code>SerialClob</code> object is instantiated with a
445 * <code>Clob</code> object. If this <code>SerialClob</code> object is instantiated with
446 * a <code>char</code> array, a <code>SerialException</code> is thrown.
447 *
448 * @param pos the position at which to start writing to the
449 * <code>CLOB</code> value
450 *
451 * @return a stream to which Unicode encoded characters can be written
452 * @throws SerialException if the SerialClob is not instantiated with
453 * a Clob object that supports <code>setCharacterStream</code>
454 * @throws SQLException if there is an error accessing the
455 * <code>CLOB</code> value
456 * @see #getCharacterStream
457 */
458 public java.io.Writer setCharacterStream(long pos)
459 throws SerialException, SQLException {
460 if (this.clob.setCharacterStream(pos) != null) {
461 return this.clob.setCharacterStream(pos);
462 } else {
463 throw new SerialException("Unsupported operation. SerialClob cannot " +
464 "return a writable character stream\n unless instantiated with a Clob object " +
465 "that has a setCharacterStream implementation");
466 }
467 }
468
469 /**
470 * Truncates the <code>CLOB</code> value that this <code>SerialClob</code>
471 * object represents so that it has a length of <code>len</code>
472 * characters.
473 * <p>
474 * Truncating a <code>SerialClob</code> object to length 0 has the effect of
475 * clearing its contents.
476 *
477 * @param length the length, in bytes, to which the <code>CLOB</code>
478 * value should be truncated
479 * @throws SQLException if there is an error accessing the
480 * <code>CLOB</code> value
481 */
482 public void truncate(long length) throws SerialException {
483 if (length > len) {
484 throw new SerialException
485 ("Length more than what can be truncated");
486 } else {
487 len = length;
488 // re-size the buffer
489
490 if (len == 0) {
491 buf = new char[] {};
492 } else {
493 buf = (this.getSubString(1, (int)len)).toCharArray();
494 }
495
496 }
497 }
498
499
500 public Reader getCharacterStream(long pos, long length) throws SQLException {
501 throw new java.lang.UnsupportedOperationException("Not supported");
502 }
503
504 public void free() throws SQLException {
505 throw new java.lang.UnsupportedOperationException("Not supported");
506 }
507
508 /**
509 * The identifier that assists in the serialization of this <code>SerialClob</code>
510 * object.
511 */
512 static final long serialVersionUID = -1662519690087375313L;
513 }
Save This Page