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 javax.sql.*;
030 import java.io.*;
031 import java.math.*;
032 import java.util.Map;
033
034 /**
035 * An input stream used for custom mapping user-defined types (UDTs).
036 * An <code>SQLInputImpl</code> object is an input stream that contains a
037 * stream of values that are the attributes of a UDT.
038 * <p>
039 * This class is used by the driver behind the scenes when the method
040 * <code>getObject</code> is called on an SQL structured or distinct type
041 * that has a custom mapping; a programmer never invokes
042 * <code>SQLInputImpl</code> methods directly. They are provided here as a
043 * convenience for those who write <code>RowSet</code> implementations.
044 * <P>
045 * The <code>SQLInputImpl</code> class provides a set of
046 * reader methods analogous to the <code>ResultSet</code> getter
047 * methods. These methods make it possible to read the values in an
048 * <code>SQLInputImpl</code> object.
049 * <P>
050 * The method <code>wasNull</code> is used to determine whether the
051 * the last value read was SQL <code>NULL</code>.
052 * <P>When the method <code>getObject</code> is called with an
053 * object of a class implementing the interface <code>SQLData</code>,
054 * the JDBC driver calls the method <code>SQLData.getSQLType</code>
055 * to determine the SQL type of the UDT being custom mapped. The driver
056 * creates an instance of <code>SQLInputImpl</code>, populating it with the
057 * attributes of the UDT. The driver then passes the input
058 * stream to the method <code>SQLData.readSQL</code>, which in turn
059 * calls the <code>SQLInputImpl</code> reader methods
060 * to read the attributes from the input stream.
061 * @see java.sql.SQLData
062 */
063 public class SQLInputImpl implements SQLInput {
064
065 /**
066 * <code>true</code> if the last value returned was <code>SQL NULL</code>;
067 * <code>false</code> otherwise.
068 */
069 private boolean lastValueWasNull;
070
071 /**
072 * The current index into the array of SQL structured type attributes
073 * that will be read from this <code>SQLInputImpl</code> object and
074 * mapped to the fields of a class in the Java programming language.
075 */
076 private int idx;
077
078 /**
079 * The array of attributes to be read from this stream. The order
080 * of the attributes is the same as the order in which they were
081 * listed in the SQL definition of the UDT.
082 */
083 private Object attrib[];
084
085 /**
086 * The type map to use when the method <code>readObject</code>
087 * is invoked. This is a <code>java.util.Map</code> object in which
088 * there may be zero or more entries. Each entry consists of the
089 * fully qualified name of a UDT (the value to be mapped) and the
090 * <code>Class</code> object for a class that implements
091 * <code>SQLData</code> (the Java class that defines how the UDT
092 * will be mapped).
093 */
094 private Map map;
095
096 /**
097 * Creates an <code>SQLInputImpl</code> object initialized with the
098 * given array of attributes and the given type map. If any of the
099 * attributes is a UDT whose name is in an entry in the type map,
100 * the attribute will be mapped according to the corresponding
101 * <code>SQLData</code> implementation.
102 *
103 * @param attributes an array of <code>Object</code> instances in which
104 * each element is an attribute of a UDT. The order of the
105 * attributes in the array is the same order in which
106 * the attributes were defined in the UDT definition.
107 * @param map a <code>java.util.Map</code> object containing zero or more
108 * entries, with each entry consisting of 1) a <code>String</code>
109 * giving the fully
110 * qualified name of the UDT and 2) the <code>Class</code> object
111 * for the <code>SQLData</code> implementation that defines how
112 * the UDT is to be mapped
113 * @throws SQLException if the <code>attributes</code> or the <code>map</code>
114 * is a <code>null</code> value
115 */
116
117 public SQLInputImpl(Object[] attributes, Map<String, Class<?>> map)
118 throws SQLException {
119 if ((attributes == null) || (map == null)) {
120 throw new SQLException("Cannot instantiate a SQLInputImpl "
121 + "object with null parameters");
122 }
123 // assign our local reference to the attribute stream
124 attrib = attributes;
125 // init the index point before the head of the stream
126 idx = -1;
127 // set the map
128 this .map = map;
129 }
130
131 /**
132 * Retrieves the next attribute in this <code>SQLInputImpl</code> object
133 * as an <code>Object</code> in the Java programming language.
134 *
135 * @return the next value in the input stream
136 * as an <code>Object</code> in the Java programming language
137 * @throws SQLException if the read position is located at an invalid
138 * position or if there are no further values in the stream
139 */
140 private Object getNextAttribute() throws SQLException {
141 if (++idx >= attrib.length) {
142 throw new SQLException(
143 "SQLInputImpl exception: Invalid read "
144 + "position");
145 } else {
146 return attrib[idx];
147 }
148 }
149
150 //================================================================
151 // Methods for reading attributes from the stream of SQL data.
152 // These methods correspond to the column-accessor methods of
153 // java.sql.ResultSet.
154 //================================================================
155
156 /**
157 * Retrieves the next attribute in this <code>SQLInputImpl</code> object as
158 * a <code>String</code> in the Java programming language.
159 * <p>
160 * This method does not perform type-safe checking to determine if the
161 * returned type is the expected type; this responsibility is delegated
162 * to the UDT mapping as defined by a <code>SQLData</code>
163 * implementation.
164 * <p>
165 * @return the next attribute in this <code>SQLInputImpl</code> object;
166 * if the value is <code>SQL NULL</code>, return <code>null</code>
167 * @throws SQLException if the read position is located at an invalid
168 * position or if there are no further values in the stream.
169 */
170 public String readString() throws SQLException {
171
172 String attrib = (String) getNextAttribute();
173
174 if (attrib == null) {
175 lastValueWasNull = true;
176 return null;
177 } else {
178 lastValueWasNull = false;
179 return attrib;
180 }
181 }
182
183 /**
184 * Retrieves the next attribute in this <code>SQLInputImpl</code> object as
185 * a <code>boolean</code> in the Java programming language.
186 * <p>
187 * This method does not perform type-safe checking to determine if the
188 * returned type is the expected type; this responsibility is delegated
189 * to the UDT mapping as defined by a <code>SQLData</code>
190 * implementation.
191 * <p>
192 * @return the next attribute in this <code>SQLInputImpl</code> object;
193 * if the value is <code>SQL NULL</code>, return <code>null</code>
194 * @throws SQLException if the read position is located at an invalid
195 * position or if there are no further values in the stream.
196 */
197 public boolean readBoolean() throws SQLException {
198
199 Boolean attrib = (Boolean) getNextAttribute();
200
201 if (attrib == null) {
202 lastValueWasNull = true;
203 return false;
204 } else {
205 lastValueWasNull = false;
206 return attrib.booleanValue();
207 }
208 }
209
210 /**
211 * Retrieves the next attribute in this <code>SQLInputImpl</code> object as
212 * a <code>byte</code> in the Java programming language.
213 * <p>
214 * This method does not perform type-safe checking to determine if the
215 * returned type is the expected type; this responsibility is delegated
216 * to the UDT mapping as defined by a <code>SQLData</code>
217 * implementation.
218 * <p>
219 * @return the next attribute in this <code>SQLInputImpl</code> object;
220 * if the value is <code>SQL NULL</code>, return <code>null</code>
221 * @throws SQLException if the read position is located at an invalid
222 * position or if there are no further values in the stream
223 */
224 public byte readByte() throws SQLException {
225 Byte attrib = (Byte) getNextAttribute();
226
227 if (attrib == null) {
228 lastValueWasNull = true;
229 return (byte) 0;
230 } else {
231 lastValueWasNull = false;
232 return attrib.byteValue();
233 }
234 }
235
236 /**
237 * Retrieves the next attribute in this <code>SQLInputImpl</code> object
238 * as a <code>short</code> in the Java programming language.
239 * <P>
240 * This method does not perform type-safe checking to determine if the
241 * returned type is the expected type; this responsibility is delegated
242 * to the UDT mapping as defined by a <code>SQLData</code> implementation.
243 * <P>
244 * @return the next attribute in this <code>SQLInputImpl</code> object;
245 * if the value is <code>SQL NULL</code>, return <code>null</code>
246 * @throws SQLException if the read position is located at an invalid
247 * position or if there are no more values in the stream
248 */
249 public short readShort() throws SQLException {
250 Short attrib = (Short) getNextAttribute();
251
252 if (attrib == null) {
253 lastValueWasNull = true;
254 return (short) 0;
255 } else {
256 lastValueWasNull = false;
257 return attrib.shortValue();
258 }
259 }
260
261 /**
262 * Retrieves the next attribute in this <code>SQLInputImpl</code> object
263 * as an <code>int</code> in the Java programming language.
264 * <P>
265 * This method does not perform type-safe checking to determine if the
266 * returned type is the expected type; this responsibility is delegated
267 * to the UDT mapping as defined by a <code>SQLData</code> implementation.
268 * <P>
269 * @return the next attribute in this <code>SQLInputImpl</code> object;
270 * if the value is <code>SQL NULL</code>, return <code>null</code>
271 * @throws SQLException if the read position is located at an invalid
272 * position or if there are no more values in the stream
273 */
274 public int readInt() throws SQLException {
275 Integer attrib = (Integer) getNextAttribute();
276
277 if (attrib == null) {
278 lastValueWasNull = true;
279 return (int) 0;
280 } else {
281 lastValueWasNull = false;
282 return attrib.intValue();
283 }
284 }
285
286 /**
287 * Retrieves the next attribute in this <code>SQLInputImpl</code> object
288 * as a <code>long</code> in the Java programming language.
289 * <P>
290 * This method does not perform type-safe checking to determine if the
291 * returned type is the expected type; this responsibility is delegated
292 * to the UDT mapping as defined by a <code>SQLData</code> implementation.
293 * <P>
294 * @return the next attribute in this <code>SQLInputImpl</code> object;
295 * if the value is <code>SQL NULL</code>, return <code>null</code>
296 * @throws SQLException if the read position is located at an invalid
297 * position or if there are no more values in the stream
298 */
299 public long readLong() throws SQLException {
300 Long attrib = (Long) getNextAttribute();
301
302 if (attrib == null) {
303 lastValueWasNull = true;
304 return (long) 0;
305 } else {
306 lastValueWasNull = false;
307 return attrib.longValue();
308 }
309 }
310
311 /**
312 * Retrieves the next attribute in this <code>SQLInputImpl</code> object
313 * as a <code>float</code> in the Java programming language.
314 * <P>
315 * This method does not perform type-safe checking to determine if the
316 * returned type is the expected type; this responsibility is delegated
317 * to the UDT mapping as defined by a <code>SQLData</code> implementation.
318 * <P>
319 * @return the next attribute in this <code>SQLInputImpl</code> object;
320 * if the value is <code>SQL NULL</code>, return <code>null</code>
321 * @throws SQLException if the read position is located at an invalid
322 * position or if there are no more values in the stream
323 */
324 public float readFloat() throws SQLException {
325 Float attrib = (Float) getNextAttribute();
326
327 if (attrib == null) {
328 lastValueWasNull = true;
329 return (float) 0;
330 } else {
331 lastValueWasNull = false;
332 return attrib.floatValue();
333 }
334 }
335
336 /**
337 * Retrieves the next attribute in this <code>SQLInputImpl</code> object
338 * as a <code>double</code> in the Java programming language.
339 * <P>
340 * This method does not perform type-safe checking to determine if the
341 * returned type is the expected type; this responsibility is delegated
342 * to the UDT mapping as defined by a <code>SQLData</code> implementation.
343 * <P>
344 * @return the next attribute in this <code>SQLInputImpl</code> object;
345 * if the value is <code>SQL NULL</code>, return <code>null</code>
346 * @throws SQLException if the read position is located at an invalid
347 * position or if there are no more values in the stream
348 */
349 public double readDouble() throws SQLException {
350 Double attrib = (Double) getNextAttribute();
351
352 if (attrib == null) {
353 lastValueWasNull = true;
354 return (double) 0;
355 } else {
356 lastValueWasNull = false;
357 return attrib.doubleValue();
358 }
359 }
360
361 /**
362 * Retrieves the next attribute in this <code>SQLInputImpl</code> object
363 * as a <code>java.math.BigDecimal</code>.
364 * <P>
365 * This method does not perform type-safe checking to determine if the
366 * returned type is the expected type; this responsibility is delegated
367 * to the UDT mapping as defined by a <code>SQLData</code> implementation.
368 * <P>
369 * @return the next attribute in this <code>SQLInputImpl</code> object;
370 * if the value is <code>SQL NULL</code>, return <code>null</code>
371 * @throws SQLException if the read position is located at an invalid
372 * position or if there are no more values in the stream
373 */
374 public java.math.BigDecimal readBigDecimal() throws SQLException {
375 java.math.BigDecimal attrib = (java.math.BigDecimal) getNextAttribute();
376
377 if (attrib == null) {
378 lastValueWasNull = true;
379 return null;
380 } else {
381 lastValueWasNull = false;
382 return attrib;
383 }
384 }
385
386 /**
387 * Retrieves the next attribute in this <code>SQLInputImpl</code> object
388 * as an array of bytes.
389 * <p>
390 * This method does not perform type-safe checking to determine if the
391 * returned type is the expected type; this responsibility is delegated
392 * to the UDT mapping as defined by a <code>SQLData</code> implementation.
393 * <P>
394 * @return the next attribute in this <code>SQLInputImpl</code> object;
395 * if the value is <code>SQL NULL</code>, return <code>null</code>
396 * @throws SQLException if the read position is located at an invalid
397 * position or if there are no more values in the stream
398 */
399 public byte[] readBytes() throws SQLException {
400 byte[] attrib = (byte[]) getNextAttribute();
401
402 if (attrib == null) {
403 lastValueWasNull = true;
404 return null;
405 } else {
406 lastValueWasNull = false;
407 return attrib;
408 }
409 }
410
411 /**
412 * Retrieves the next attribute in this <code>SQLInputImpl</code> as
413 * a <code>java.sql.Date</code> object.
414 * <P>
415 * This method does not perform type-safe checking to determine if the
416 * returned type is the expected type; this responsibility is delegated
417 * to the UDT mapping as defined by a <code>SQLData</code> implementation.
418 * <P>
419 * @return the next attribute in this <code>SQLInputImpl</code> object;
420 * if the value is <code>SQL NULL</code>, return <code>null</code>
421 * @throws SQLException if the read position is located at an invalid
422 * position or if there are no more values in the stream
423 */
424 public java.sql.Date readDate() throws SQLException {
425 java.sql.Date attrib = (java.sql.Date) getNextAttribute();
426
427 if (attrib == null) {
428 lastValueWasNull = true;
429 return null;
430 } else {
431 lastValueWasNull = false;
432 return attrib;
433 }
434 }
435
436 /**
437 * Retrieves the next attribute in this <code>SQLInputImpl</code> object as
438 * a <code>java.sql.Time</code> object.
439 * <P>
440 * This method does not perform type-safe checking to determine if the
441 * returned type is the expected type as this responsibility is delegated
442 * to the UDT mapping as implemented by a <code>SQLData</code>
443 * implementation.
444 *
445 * @return the attribute; if the value is <code>SQL NULL</code>, return
446 * <code>null</code>
447 * @throws SQLException if the read position is located at an invalid
448 * position; or if there are no further values in the stream.
449 */
450 public java.sql.Time readTime() throws SQLException {
451 java.sql.Time attrib = (java.sql.Time) getNextAttribute();
452
453 if (attrib == null) {
454 lastValueWasNull = true;
455 return null;
456 } else {
457 lastValueWasNull = false;
458 return attrib;
459 }
460 }
461
462 /**
463 * Retrieves the next attribute in this <code>SQLInputImpl</code> object as
464 * a <code>java.sql.Timestamp</code> object.
465 *
466 * @return the attribute; if the value is <code>SQL NULL</code>, return
467 * <code>null</code>
468 * @throws SQLException if the read position is located at an invalid
469 * position; or if there are no further values in the stream.
470 */
471 public java.sql.Timestamp readTimestamp() throws SQLException {
472 java.sql.Timestamp attrib = (java.sql.Timestamp) getNextAttribute();
473
474 if (attrib == null) {
475 lastValueWasNull = true;
476 return null;
477 } else {
478 lastValueWasNull = false;
479 return attrib;
480 }
481 }
482
483 /**
484 * Retrieves the next attribute in this <code>SQLInputImpl</code> object
485 * as a stream of Unicode characters.
486 * <P>
487 * This method does not perform type-safe checking to determine if the
488 * returned type is the expected type as this responsibility is delegated
489 * to the UDT mapping as implemented by a <code>SQLData</code>
490 * implementation.
491 *
492 * @return the attribute; if the value is <code>SQL NULL</code>, return <code>null</code>
493 * @throws SQLException if the read position is located at an invalid
494 * position; or if there are no further values in the stream.
495 */
496 public java.io.Reader readCharacterStream() throws SQLException {
497 java.io.Reader attrib = (java.io.Reader) getNextAttribute();
498
499 if (attrib == null) {
500 lastValueWasNull = true;
501 return null;
502 } else {
503 lastValueWasNull = false;
504 return attrib;
505 }
506 }
507
508 /**
509 * Returns the next attribute in this <code>SQLInputImpl</code> object
510 * as a stream of ASCII characters.
511 * <P>
512 * This method does not perform type-safe checking to determine if the
513 * returned type is the expected type as this responsibility is delegated
514 * to the UDT mapping as implemented by a <code>SQLData</code>
515 * implementation.
516 *
517 * @return the attribute; if the value is <code>SQL NULL</code>,
518 * return <code>null</code>
519 * @throws SQLException if the read position is located at an invalid
520 * position; or if there are no further values in the stream.
521 */
522 public java.io.InputStream readAsciiStream() throws SQLException {
523 java.io.InputStream attrib = (java.io.InputStream) getNextAttribute();
524
525 if (attrib == null) {
526 lastValueWasNull = true;
527 return null;
528 } else {
529 lastValueWasNull = false;
530 return attrib;
531 }
532 }
533
534 /**
535 * Returns the next attribute in this <code>SQLInputImpl</code> object
536 * as a stream of uninterpreted bytes.
537 * <P>
538 * This method does not perform type-safe checking to determine if the
539 * returned type is the expected type as this responsibility is delegated
540 * to the UDT mapping as implemented by a <code>SQLData</code>
541 * implementation.
542 *
543 * @return the attribute; if the value is <code>SQL NULL</code>, return
544 * <code>null</code>
545 * @throws SQLException if the read position is located at an invalid
546 * position; or if there are no further values in the stream.
547 */
548 public java.io.InputStream readBinaryStream() throws SQLException {
549 java.io.InputStream attrib = (java.io.InputStream) getNextAttribute();
550
551 if (attrib == null) {
552 lastValueWasNull = true;
553 return null;
554 } else {
555 lastValueWasNull = false;
556 return attrib;
557 }
558 }
559
560 //================================================================
561 // Methods for reading items of SQL user-defined types from the stream.
562 //================================================================
563
564 /**
565 * Retrieves the value at the head of this <code>SQLInputImpl</code>
566 * object as an <code>Object</code> in the Java programming language. The
567 * actual type of the object returned is determined by the default
568 * mapping of SQL types to types in the Java programming language unless
569 * there is a custom mapping, in which case the type of the object
570 * returned is determined by this stream's type map.
571 * <P>
572 * The JDBC technology-enabled driver registers a type map with the stream
573 * before passing the stream to the application.
574 * <P>
575 * When the datum at the head of the stream is an SQL <code>NULL</code>,
576 * this method returns <code>null</code>. If the datum is an SQL
577 * structured or distinct type with a custom mapping, this method
578 * determines the SQL type of the datum at the head of the stream,
579 * constructs an object of the appropriate class, and calls the method
580 * <code>SQLData.readSQL</code> on that object. The <code>readSQL</code>
581 * method then calls the appropriate <code>SQLInputImpl.readXXX</code>
582 * methods to retrieve the attribute values from the stream.
583 *
584 * @return the value at the head of the stream as an <code>Object</code>
585 * in the Java programming language; <code>null</code> if
586 * the value is SQL <code>NULL</code>
587 * @throws SQLException if the read position is located at an invalid
588 * position; or if there are no further values in the stream.
589 */
590 public Object readObject() throws SQLException {
591 Object attrib = (Object) getNextAttribute();
592
593 if (attrib == null) {
594 lastValueWasNull = true;
595 return null;
596 } else {
597 lastValueWasNull = false;
598 if (attrib instanceof Struct) {
599 Struct s = (Struct) attrib;
600 // look up the class in the map
601 Class c = (Class) map.get(s.getSQLTypeName());
602 if (c != null) {
603 // create new instance of the class
604 SQLData obj = null;
605 try {
606 obj = (SQLData) c.newInstance();
607 } catch (java.lang.InstantiationException ex) {
608 throw new SQLException(
609 "Unable to instantiate: "
610 + ex.getMessage());
611 } catch (java.lang.IllegalAccessException ex) {
612 throw new SQLException(
613 "Unable to instantiate: "
614 + ex.getMessage());
615 }
616 // get the attributes from the struct
617 Object attribs[] = s.getAttributes(map);
618 // create the SQLInput "stream"
619 SQLInputImpl sqlInput = new SQLInputImpl(attribs,
620 map);
621 // read the values...
622 obj.readSQL(sqlInput, s.getSQLTypeName());
623 return (Object) obj;
624 }
625 }
626 return (Object) attrib;
627 }
628 }
629
630 /**
631 * Retrieves the value at the head of this <code>SQLInputImpl</code> object
632 * as a <code>Ref</code> object in the Java programming language.
633 *
634 * @return a <code>Ref</code> object representing the SQL
635 * <code>REF</code> value at the head of the stream; if the value
636 * is <code>SQL NULL</code> return <code>null</code>
637 * @throws SQLException if the read position is located at an invalid
638 * position; or if there are no further values in the stream.
639 */
640 public Ref readRef() throws SQLException {
641 Ref attrib = (Ref) getNextAttribute();
642
643 if (attrib == null) {
644 lastValueWasNull = true;
645 return null;
646 } else {
647 lastValueWasNull = false;
648 return attrib;
649 }
650 }
651
652 /**
653 * Retrieves the <code>BLOB</code> value at the head of this
654 * <code>SQLInputImpl</code> object as a <code>Blob</code> object
655 * in the Java programming language.
656 * <P>
657 * This method does not perform type-safe checking to determine if the
658 * returned type is the expected type as this responsibility is delegated
659 * to the UDT mapping as implemented by a <code>SQLData</code>
660 * implementation.
661 *
662 * @return a <code>Blob</code> object representing the SQL
663 * <code>BLOB</code> value at the head of this stream;
664 * if the value is <code>SQL NULL</code>, return
665 * <code>null</code>
666 * @throws SQLException if the read position is located at an invalid
667 * position; or if there are no further values in the stream.
668 */
669 public Blob readBlob() throws SQLException {
670 Blob attrib = (Blob) getNextAttribute();
671
672 if (attrib == null) {
673 lastValueWasNull = true;
674 return null;
675 } else {
676 lastValueWasNull = false;
677 return attrib;
678 }
679 }
680
681 /**
682 * Retrieves the <code>CLOB</code> value at the head of this
683 * <code>SQLInputImpl</code> object as a <code>Clob</code> object
684 * in the Java programming language.
685 * <P>
686 * This method does not perform type-safe checking to determine if the
687 * returned type is the expected type as this responsibility is delegated
688 * to the UDT mapping as implemented by a <code>SQLData</code>
689 * implementation.
690 *
691 * @return a <code>Clob</code> object representing the SQL
692 * <code>CLOB</code> value at the head of the stream;
693 * if the value is <code>SQL NULL</code>, return
694 * <code>null</code>
695 * @throws SQLException if the read position is located at an invalid
696 * position; or if there are no further values in the stream.
697 */
698 public Clob readClob() throws SQLException {
699
700 Clob attrib = (Clob) getNextAttribute();
701 if (attrib == null) {
702 lastValueWasNull = true;
703 return null;
704 } else {
705 lastValueWasNull = false;
706 return attrib;
707 }
708 }
709
710 /**
711 * Reads an SQL <code>ARRAY</code> value from the stream and
712 * returns it as an <code>Array</code> object in the Java programming
713 * language.
714 * <P>
715 * This method does not perform type-safe checking to determine if the
716 * returned type is the expected type as this responsibility is delegated
717 * to the UDT mapping as implemented by a <code>SQLData</code>
718 * implementation.
719 *
720 * @return an <code>Array</code> object representing the SQL
721 * <code>ARRAY</code> value at the head of the stream; *
722 * if the value is <code>SQL NULL</code>, return
723 * <code>null</code>
724 * @throws SQLException if the read position is located at an invalid
725 * position; or if there are no further values in the stream.
726
727 */
728 public Array readArray() throws SQLException {
729 Array attrib = (Array) getNextAttribute();
730
731 if (attrib == null) {
732 lastValueWasNull = true;
733 return null;
734 } else {
735 lastValueWasNull = false;
736 return attrib;
737 }
738 }
739
740 /**
741 * Ascertains whether the last value read from this
742 * <code>SQLInputImpl</code> object was <code>null</code>.
743 *
744 * @return <code>true</code> if the SQL value read most recently was
745 * <code>null</code>; otherwise, <code>false</code>; by default it
746 * will return false
747 * @throws SQLException if an error occurs determining the last value
748 * read was a <code>null</code> value or not;
749 */
750 public boolean wasNull() throws SQLException {
751 return lastValueWasNull;
752 }
753
754 /**
755 * Reads an SQL <code>DATALINK</code> value from the stream and
756 * returns it as an <code>URL</code> object in the Java programming
757 * language.
758 * <P>
759 * This method does not perform type-safe checking to determine if the
760 * returned type is the expected type as this responsibility is delegated
761 * to the UDT mapping as implemented by a <code>SQLData</code>
762 * implementation.
763 *
764 * @return an <code>URL</code> object representing the SQL
765 * <code>DATALINK</code> value at the head of the stream; *
766 * if the value is <code>SQL NULL</code>, return
767 * <code>null</code>
768 * @throws SQLException if the read position is located at an invalid
769 * position; or if there are no further values in the stream.
770 */
771 public java.net.URL readURL() throws SQLException {
772 throw new SQLException("Operation not supported");
773 }
774
775 //---------------------------- JDBC 4.0 -------------------------
776
777 /**
778 * Reads an SQL <code>NCLOB</code> value from the stream and returns it as a
779 * <code>Clob</code> object in the Java programming language.
780 *
781 * @return a <code>NClob</code> object representing data of the SQL <code>NCLOB</code> value
782 * at the head of the stream; <code>null</code> if the value read is
783 * SQL <code>NULL</code>
784 * @exception SQLException if a database access error occurs
785 */
786 public NClob readNClob() throws SQLException {
787 throw new UnsupportedOperationException(
788 "Operation not supported");
789 }
790
791 /**
792 * Reads the next attribute in the stream and returns it as a <code>String</code>
793 * in the Java programming language. It is intended for use when
794 * accessing <code>NCHAR</code>,<code>NVARCHAR</code>
795 * and <code>LONGNVARCHAR</code> columns.
796 *
797 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
798 * @exception SQLException if a database access error occurs
799 */
800 public String readNString() throws SQLException {
801 throw new UnsupportedOperationException(
802 "Operation not supported");
803 }
804
805 /**
806 * Reads an SQL <code>XML</code> value from the stream and returns it as a
807 * <code>SQLXML</code> object in the Java programming language.
808 *
809 * @return a <code>SQLXML</code> object representing data of the SQL <code>XML</code> value
810 * at the head of the stream; <code>null</code> if the value read is
811 * SQL <code>NULL</code>
812 * @exception SQLException if a database access error occurs
813 */
814 public SQLXML readSQLXML() throws SQLException {
815 throw new UnsupportedOperationException(
816 "Operation not supported");
817 }
818
819 /**
820 * Reads an SQL <code>ROWID</code> value from the stream and returns it as a
821 * <code>RowId</code> object in the Java programming language.
822 *
823 * @return a <code>RowId</code> object representing data of the SQL <code>ROWID</code> value
824 * at the head of the stream; <code>null</code> if the value read is
825 * SQL <code>NULL</code>
826 * @exception SQLException if a database access error occurs
827 */
828 public RowId readRowId() throws SQLException {
829 throw new UnsupportedOperationException(
830 "Operation not supported");
831 }
832
833 }
|