1 /*
2 * Copyright (c) 2003, 2013, 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 javax.sql.rowset.serial;
27
28 import java.sql.*;
29 import java.io.*;
30 import java.util.Map;
31 import java.net.URL;
32 import java.util.Arrays;
33
34
35 /**
36 * A serialized version of an <code>Array</code>
37 * object, which is the mapping in the Java programming language of an SQL
38 * <code>ARRAY</code> value.
39 * <P>
40 * The <code>SerialArray</code> class provides a constructor for creating
41 * a <code>SerialArray</code> instance from an <code>Array</code> object,
42 * methods for getting the base type and the SQL name for the base type, and
43 * methods for copying all or part of a <code>SerialArray</code> object.
44 * <P>
45 *
46 * Note: In order for this class to function correctly, a connection to the
47 * data source
48 * must be available in order for the SQL <code>Array</code> object to be
49 * materialized (have all of its elements brought to the client server)
50 * if necessary. At this time, logical pointers to the data in the data source,
51 * such as locators, are not currently supported.
52 *
53 * <h3> Thread safety </h3>
54 *
55 * A SerialArray is not safe for use by multiple concurrent threads. If a
56 * SerialArray is to be used by more than one thread then access to the
57 * SerialArray should be controlled by appropriate synchronization.
58 *
59 */
60 public class SerialArray implements Array, Serializable, Cloneable {
61
62 /**
63 * A serialized array in which each element is an <code>Object</code>
64 * in the Java programming language that represents an element
65 * in the SQL <code>ARRAY</code> value.
66 * @serial
67 */
68 private Object[] elements;
69
70 /**
71 * The SQL type of the elements in this <code>SerialArray</code> object. The
72 * type is expressed as one of the constants from the class
73 * <code>java.sql.Types</code>.
74 * @serial
75 */
76 private int baseType;
77
78 /**
79 * The type name used by the DBMS for the elements in the SQL <code>ARRAY</code>
80 * value that this <code>SerialArray</code> object represents.
81 * @serial
82 */
83 private String baseTypeName;
84
85 /**
86 * The number of elements in this <code>SerialArray</code> object, which
87 * is also the number of elements in the SQL <code>ARRAY</code> value
88 * that this <code>SerialArray</code> object represents.
89 * @serial
90 */
91 private int len;
92
93 /**
94 * Constructs a new <code>SerialArray</code> object from the given
95 * <code>Array</code> object, using the given type map for the custom
96 * mapping of each element when the elements are SQL UDTs.
97 * <P>
98 * This method does custom mapping if the array elements are a UDT
99 * and the given type map has an entry for that UDT.
100 * Custom mapping is recursive,
101 * meaning that if, for instance, an element of an SQL structured type
102 * is an SQL structured type that itself has an element that is an SQL
103 * structured type, each structured type that has a custom mapping will be
104 * mapped according to the given type map.
105 * <P>
106 * The new <code>SerialArray</code>
107 * object contains the same elements as the <code>Array</code> object
108 * from which it is built, except when the base type is the SQL type
109 * <code>STRUCT</code>, <code>ARRAY</code>, <code>BLOB</code>,
110 * <code>CLOB</code>, <code>DATALINK</code> or <code>JAVA_OBJECT</code>.
111 * In this case, each element in the new
112 * <code>SerialArray</code> object is the appropriate serialized form,
113 * that is, a <code>SerialStruct</code>, <code>SerialArray</code>,
114 * <code>SerialBlob</code>, <code>SerialClob</code>,
115 * <code>SerialDatalink</code>, or <code>SerialJavaObject</code> object.
116 * <P>
117 * Note: (1) The <code>Array</code> object from which a <code>SerialArray</code>
118 * object is created must have materialized the SQL <code>ARRAY</code> value's
119 * data on the client before it is passed to the constructor. Otherwise,
120 * the new <code>SerialArray</code> object will contain no data.
121 * <p>
122 * Note: (2) If the <code>Array</code> contains <code>java.sql.Types.JAVA_OBJECT</code>
123 * types, the <code>SerialJavaObject</code> constructor is called where checks
124 * are made to ensure this object is serializable.
125 * <p>
126 * Note: (3) The <code>Array</code> object supplied to this constructor cannot
127 * return <code>null</code> for any <code>Array.getArray()</code> methods.
128 * <code>SerialArray</code> cannot serialize null array values.
129 *
130 *
131 * @param array the <code>Array</code> object to be serialized
132 * @param map a <code>java.util.Map</code> object in which
133 * each entry consists of 1) a <code>String</code> object
134 * giving the fully qualified name of a UDT (an SQL structured type or
135 * distinct type) and 2) the
136 * <code>Class</code> object for the <code>SQLData</code> implementation
137 * that defines how the UDT is to be mapped. The <i>map</i>
138 * parameter does not have any effect for <code>Blob</code>,
139 * <code>Clob</code>, <code>DATALINK</code>, or
140 * <code>JAVA_OBJECT</code> types.
141 * @throws SerialException if an error occurs serializing the
142 * <code>Array</code> object
143 * @throws SQLException if a database access error occurs or if the
144 * <i>array</i> or the <i>map</i> values are <code>null</code>
145 */
146 public SerialArray(Array array, Map<String,Class<?>> map)
147 throws SerialException, SQLException
148 {
149
150 if ((array == null) || (map == null)) {
151 throw new SQLException("Cannot instantiate a SerialArray " +
152 "object with null parameters");
153 }
154
155 if ((elements = (Object[])array.getArray()) == null) {
156 throw new SQLException("Invalid Array object. Calls to Array.getArray() " +
157 "return null value which cannot be serialized");
158 }
159
160 elements = (Object[])array.getArray(map);
161 baseType = array.getBaseType();
162 baseTypeName = array.getBaseTypeName();
163 len = elements.length;
164
165 switch (baseType) {
166 case java.sql.Types.STRUCT:
167 for (int i = 0; i < len; i++) {
168 elements[i] = new SerialStruct((Struct)elements[i], map);
169 }
170 break;
171
172 case java.sql.Types.ARRAY:
173 for (int i = 0; i < len; i++) {
174 elements[i] = new SerialArray((Array)elements[i], map);
175 }
176 break;
177
178 case java.sql.Types.BLOB:
179 for (int i = 0; i < len; i++) {
180 elements[i] = new SerialBlob((Blob)elements[i]);
181 }
182 break;
183
184 case java.sql.Types.CLOB:
185 for (int i = 0; i < len; i++) {
186 elements[i] = new SerialClob((Clob)elements[i]);
187 }
188 break;
189
190 case java.sql.Types.DATALINK:
191 for (int i = 0; i < len; i++) {
192 elements[i] = new SerialDatalink((URL)elements[i]);
193 }
194 break;
195
196 case java.sql.Types.JAVA_OBJECT:
197 for (int i = 0; i < len; i++) {
198 elements[i] = new SerialJavaObject(elements[i]);
199 }
200 }
201 }
202
203 /**
204 * This method frees the {@code SeriableArray} object and releases the
205 * resources that it holds. The object is invalid once the {@code free}
206 * method is called. <p> If {@code free} is called multiple times, the
207 * subsequent calls to {@code free} are treated as a no-op. </P>
208 *
209 * @throws SQLException if an error occurs releasing the SerialArray's resources
210 * @since 1.6
211 */
212 public void free() throws SQLException {
213 if (elements != null) {
214 elements = null;
215 baseTypeName= null;
216 }
217 }
218
219 /**
220 * Constructs a new <code>SerialArray</code> object from the given
221 * <code>Array</code> object.
222 * <P>
223 * This constructor does not do custom mapping. If the base type of the array
224 * is an SQL structured type and custom mapping is desired, the constructor
225 * <code>SerialArray(Array array, Map map)</code> should be used.
226 * <P>
227 * The new <code>SerialArray</code>
228 * object contains the same elements as the <code>Array</code> object
229 * from which it is built, except when the base type is the SQL type
230 * <code>BLOB</code>,
231 * <code>CLOB</code>, <code>DATALINK</code> or <code>JAVA_OBJECT</code>.
232 * In this case, each element in the new
233 * <code>SerialArray</code> object is the appropriate serialized form,
234 * that is, a <code>SerialBlob</code>, <code>SerialClob</code>,
235 * <code>SerialDatalink</code>, or <code>SerialJavaObject</code> object.
236 * <P>
237 * Note: (1) The <code>Array</code> object from which a <code>SerialArray</code>
238 * object is created must have materialized the SQL <code>ARRAY</code> value's
239 * data on the client before it is passed to the constructor. Otherwise,
240 * the new <code>SerialArray</code> object will contain no data.
241 * <p>
242 * Note: (2) The <code>Array</code> object supplied to this constructor cannot
243 * return <code>null</code> for any <code>Array.getArray()</code> methods.
244 * <code>SerialArray</code> cannot serialize <code>null</code> array values.
245 *
246 * @param array the <code>Array</code> object to be serialized
247 * @throws SerialException if an error occurs serializing the
248 * <code>Array</code> object
249 * @throws SQLException if a database access error occurs or the
250 * <i>array</i> parameter is <code>null</code>.
251 */
252 public SerialArray(Array array) throws SerialException, SQLException {
253 if (array == null) {
254 throw new SQLException("Cannot instantiate a SerialArray " +
255 "object with a null Array object");
256 }
257
258 if ((elements = (Object[])array.getArray()) == null) {
259 throw new SQLException("Invalid Array object. Calls to Array.getArray() " +
260 "return null value which cannot be serialized");
261 }
262
263 //elements = (Object[])array.getArray();
264 baseType = array.getBaseType();
265 baseTypeName = array.getBaseTypeName();
266 len = elements.length;
267
268 switch (baseType) {
269
270 case java.sql.Types.BLOB:
271 for (int i = 0; i < len; i++) {
272 elements[i] = new SerialBlob((Blob)elements[i]);
273 }
274 break;
275
276 case java.sql.Types.CLOB:
277 for (int i = 0; i < len; i++) {
278 elements[i] = new SerialClob((Clob)elements[i]);
279 }
280 break;
281
282 case java.sql.Types.DATALINK:
283 for (int i = 0; i < len; i++) {
284 elements[i] = new SerialDatalink((URL)elements[i]);
285 }
286 break;
287
288 case java.sql.Types.JAVA_OBJECT:
289 for (int i = 0; i < len; i++) {
290 elements[i] = new SerialJavaObject(elements[i]);
291 }
292 break;
293
294 }
295
296
297 }
298
299 /**
300 * Returns a new array that is a copy of this <code>SerialArray</code>
301 * object.
302 *
303 * @return a copy of this <code>SerialArray</code> object as an
304 * <code>Object</code> in the Java programming language
305 * @throws SerialException if an error occurs;
306 * if {@code free} had previously been called on this object
307 */
308 public Object getArray() throws SerialException {
309 isValid();
310 Object dst = new Object[len];
311 System.arraycopy((Object)elements, 0, dst, 0, len);
312 return dst;
313 }
314
315 //[if an error occurstype map used??]
316 /**
317 * Returns a new array that is a copy of this <code>SerialArray</code>
318 * object, using the given type map for the custom
319 * mapping of each element when the elements are SQL UDTs.
320 * <P>
321 * This method does custom mapping if the array elements are a UDT
322 * and the given type map has an entry for that UDT.
323 * Custom mapping is recursive,
324 * meaning that if, for instance, an element of an SQL structured type
325 * is an SQL structured type that itself has an element that is an SQL
326 * structured type, each structured type that has a custom mapping will be
327 * mapped according to the given type map.
328 *
329 * @param map a <code>java.util.Map</code> object in which
330 * each entry consists of 1) a <code>String</code> object
331 * giving the fully qualified name of a UDT and 2) the
332 * <code>Class</code> object for the <code>SQLData</code> implementation
333 * that defines how the UDT is to be mapped
334 * @return a copy of this <code>SerialArray</code> object as an
335 * <code>Object</code> in the Java programming language
336 * @throws SerialException if an error occurs;
337 * if {@code free} had previously been called on this object
338 */
339 public Object getArray(Map<String, Class<?>> map) throws SerialException {
340 isValid();
341 Object dst[] = new Object[len];
342 System.arraycopy((Object)elements, 0, dst, 0, len);
343 return dst;
344 }
345
346 /**
347 * Returns a new array that is a copy of a slice
348 * of this <code>SerialArray</code> object, starting with the
349 * element at the given index and containing the given number
350 * of consecutive elements.
351 *
352 * @param index the index into this <code>SerialArray</code> object
353 * of the first element to be copied;
354 * the index of the first element is <code>0</code>
355 * @param count the number of consecutive elements to be copied, starting
356 * at the given index
357 * @return a copy of the designated elements in this <code>SerialArray</code>
358 * object as an <code>Object</code> in the Java programming language
359 * @throws SerialException if an error occurs;
360 * if {@code free} had previously been called on this object
361 */
362 public Object getArray(long index, int count) throws SerialException {
363 isValid();
364 Object dst = new Object[count];
365 System.arraycopy((Object)elements, (int)index, dst, 0, count);
366 return dst;
367 }
368
369 /**
370 * Returns a new array that is a copy of a slice
371 * of this <code>SerialArray</code> object, starting with the
372 * element at the given index and containing the given number
373 * of consecutive elements.
374 * <P>
375 * This method does custom mapping if the array elements are a UDT
376 * and the given type map has an entry for that UDT.
377 * Custom mapping is recursive,
378 * meaning that if, for instance, an element of an SQL structured type
379 * is an SQL structured type that itself has an element that is an SQL
380 * structured type, each structured type that has a custom mapping will be
381 * mapped according to the given type map.
382 *
383 * @param index the index into this <code>SerialArray</code> object
384 * of the first element to be copied; the index of the
385 * first element in the array is <code>0</code>
386 * @param count the number of consecutive elements to be copied, starting
387 * at the given index
388 * @param map a <code>java.util.Map</code> object in which
389 * each entry consists of 1) a <code>String</code> object
390 * giving the fully qualified name of a UDT and 2) the
391 * <code>Class</code> object for the <code>SQLData</code> implementation
392 * that defines how the UDT is to be mapped
393 * @return a copy of the designated elements in this <code>SerialArray</code>
394 * object as an <code>Object</code> in the Java programming language
395 * @throws SerialException if an error occurs;
396 * if {@code free} had previously been called on this object
397 */
398 public Object getArray(long index, int count, Map<String,Class<?>> map)
399 throws SerialException
400 {
401 isValid();
402 Object dst = new Object[count];
403 System.arraycopy((Object)elements, (int)index, dst, 0, count);
404 return dst;
405 }
406
407 /**
408 * Retrieves the SQL type of the elements in this <code>SerialArray</code>
409 * object. The <code>int</code> returned is one of the constants in the class
410 * <code>java.sql.Types</code>.
411 *
412 * @return one of the constants in <code>java.sql.Types</code>, indicating
413 * the SQL type of the elements in this <code>SerialArray</code> object
414 * @throws SerialException if an error occurs;
415 * if {@code free} had previously been called on this object
416 */
417 public int getBaseType() throws SerialException {
418 isValid();
419 return baseType;
420 }
421
422 /**
423 * Retrieves the DBMS-specific type name for the elements in this
424 * <code>SerialArray</code> object.
425 *
426 * @return the SQL type name used by the DBMS for the base type of this
427 * <code>SerialArray</code> object
428 * @throws SerialException if an error occurs;
429 * if {@code free} had previously been called on this object
430 */
431 public String getBaseTypeName() throws SerialException {
432 isValid();
433 return baseTypeName;
434 }
435
436 /**
437 * Retrieves a <code>ResultSet</code> object holding the elements of
438 * the subarray that starts at
439 * index <i>index</i> and contains up to <i>count</i> successive elements.
440 * This method uses the connection's type map to map the elements of
441 * the array if the map contains
442 * an entry for the base type. Otherwise, the standard mapping is used.
443 *
444 * @param index the index into this <code>SerialArray</code> object
445 * of the first element to be copied; the index of the
446 * first element in the array is <code>0</code>
447 * @param count the number of consecutive elements to be copied, starting
448 * at the given index
449 * @return a <code>ResultSet</code> object containing the designated
450 * elements in this <code>SerialArray</code> object, with a
451 * separate row for each element
452 * @throws SerialException if called with the cause set to
453 * {@code UnsupportedOperationException}
454 */
455 public ResultSet getResultSet(long index, int count) throws SerialException {
456 SerialException se = new SerialException();
457 se.initCause(new UnsupportedOperationException());
458 throw se;
459 }
460
461 /**
462 *
463 * Retrieves a <code>ResultSet</code> object that contains all of
464 * the elements of the SQL <code>ARRAY</code>
465 * value represented by this <code>SerialArray</code> object. This method uses
466 * the specified map for type map customizations unless the base type of the
467 * array does not match a user-defined type (UDT) in <i>map</i>, in
468 * which case it uses the
469 * standard mapping. This version of the method <code>getResultSet</code>
470 * uses either the given type map or the standard mapping; it never uses the
471 * type map associated with the connection.
472 *
473 * @param map a <code>java.util.Map</code> object in which
474 * each entry consists of 1) a <code>String</code> object
475 * giving the fully qualified name of a UDT and 2) the
476 * <code>Class</code> object for the <code>SQLData</code> implementation
477 * that defines how the UDT is to be mapped
478 * @return a <code>ResultSet</code> object containing all of the
479 * elements in this <code>SerialArray</code> object, with a
480 * separate row for each element
481 * @throws SerialException if called with the cause set to
482 * {@code UnsupportedOperationException}
483 */
484 public ResultSet getResultSet(Map<String, Class<?>> map)
485 throws SerialException
486 {
487 SerialException se = new SerialException();
488 se.initCause(new UnsupportedOperationException());
489 throw se;
490 }
491
492 /**
493 * Retrieves a <code>ResultSet</code> object that contains all of
494 * the elements in the <code>ARRAY</code> value that this
495 * <code>SerialArray</code> object represents.
496 * If appropriate, the elements of the array are mapped using the connection's
497 * type map; otherwise, the standard mapping is used.
498 *
499 * @return a <code>ResultSet</code> object containing all of the
500 * elements in this <code>SerialArray</code> object, with a
501 * separate row for each element
502 * @throws SerialException if called with the cause set to
503 * {@code UnsupportedOperationException}
504 */
505 public ResultSet getResultSet() throws SerialException {
506 SerialException se = new SerialException();
507 se.initCause(new UnsupportedOperationException());
508 throw se;
509 }
510
511
512 /**
513 * Retrieves a result set holding the elements of the subarray that starts at
514 * Retrieves a <code>ResultSet</code> object that contains a subarray of the
515 * elements in this <code>SerialArray</code> object, starting at
516 * index <i>index</i> and containing up to <i>count</i> successive
517 * elements. This method uses
518 * the specified map for type map customizations unless the base type of the
519 * array does not match a user-defined type (UDT) in <i>map</i>, in
520 * which case it uses the
521 * standard mapping. This version of the method <code>getResultSet</code> uses
522 * either the given type map or the standard mapping; it never uses the type
523 * map associated with the connection.
524 *
525 * @param index the index into this <code>SerialArray</code> object
526 * of the first element to be copied; the index of the
527 * first element in the array is <code>0</code>
528 * @param count the number of consecutive elements to be copied, starting
529 * at the given index
530 * @param map a <code>java.util.Map</code> object in which
531 * each entry consists of 1) a <code>String</code> object
532 * giving the fully qualified name of a UDT and 2) the
533 * <code>Class</code> object for the <code>SQLData</code> implementation
534 * that defines how the UDT is to be mapped
535 * @return a <code>ResultSet</code> object containing the designated
536 * elements in this <code>SerialArray</code> object, with a
537 * separate row for each element
538 * @throws SerialException if called with the cause set to
539 * {@code UnsupportedOperationException}
540 */
541 public ResultSet getResultSet(long index, int count,
542 Map<String,Class<?>> map)
543 throws SerialException
544 {
545 SerialException se = new SerialException();
546 se.initCause(new UnsupportedOperationException());
547 throw se;
548 }
549
550
551 /**
552 * Compares this SerialArray to the specified object. The result is {@code
553 * true} if and only if the argument is not {@code null} and is a {@code
554 * SerialArray} object whose elements are identical to this object's elements
555 *
556 * @param obj The object to compare this {@code SerialArray} against
557 *
558 * @return {@code true} if the given object represents a {@code SerialArray}
559 * equivalent to this SerialArray, {@code false} otherwise
560 *
561 */
562 public boolean equals(Object obj) {
563 if (this == obj) {
564 return true;
565 }
566
567 if (obj instanceof SerialArray) {
568 SerialArray sa = (SerialArray)obj;
569 return baseType == sa.baseType &&
570 baseTypeName.equals(sa.baseTypeName) &&
571 Arrays.equals(elements, sa.elements);
572 }
573 return false;
574 }
575
576 /**
577 * Returns a hash code for this SerialArray. The hash code for a
578 * {@code SerialArray} object is computed using the hash codes
579 * of the elements of the {@code SerialArray} object
580 *
581 * @return a hash code value for this object.
582 */
583 public int hashCode() {
584 return (((31 + Arrays.hashCode(elements)) * 31 + len) * 31 +
585 baseType) * 31 + baseTypeName.hashCode();
586 }
587
588 /**
589 * Returns a clone of this {@code SerialArray}. The copy will contain a
590 * reference to a clone of the underlying objects array, not a reference
591 * to the original underlying object array of this {@code SerialArray} object.
592 *
593 * @return a clone of this SerialArray
594 */
595 public Object clone() {
596 try {
597 SerialArray sa = (SerialArray) super.clone();
598 sa.elements = (elements != null) ? Arrays.copyOf(elements, len) : null;
599 return sa;
600 } catch (CloneNotSupportedException ex) {
601 // this shouldn't happen, since we are Cloneable
602 throw new InternalError();
603 }
604
605 }
606
607 /**
608 * readObject is called to restore the state of the {@code SerialArray} from
609 * a stream.
610 */
611 private void readObject(ObjectInputStream s)
612 throws IOException, ClassNotFoundException {
613
614 ObjectInputStream.GetField fields = s.readFields();
615 Object[] tmp = (Object[])fields.get("elements", null);
616 if (tmp == null)
617 throw new InvalidObjectException("elements is null and should not be!");
618 elements = tmp.clone();
619 len = fields.get("len", 0);
620 if(elements.length != len)
621 throw new InvalidObjectException("elements is not the expected size");
622
623 baseType = fields.get("baseType", 0);
624 baseTypeName = (String)fields.get("baseTypeName", null);
625 }
626
627 /**
628 * writeObject is called to save the state of the {@code SerialArray}
629 * to a stream.
630 */
631 private void writeObject(ObjectOutputStream s)
632 throws IOException, ClassNotFoundException {
633
634 ObjectOutputStream.PutField fields = s.putFields();
635 fields.put("elements", elements);
636 fields.put("len", len);
637 fields.put("baseType", baseType);
638 fields.put("baseTypeName", baseTypeName);
639 s.writeFields();
640 }
641
642 /**
643 * Check to see if this object had previously had its {@code free} method
644 * called
645 *
646 * @throws SerialException
647 */
648 private void isValid() throws SerialException {
649 if (elements == null) {
650 throw new SerialException("Error: You cannot call a method on a "
651 + "SerialArray instance once free() has been called.");
652 }
653 }
654
655 /**
656 * The identifier that assists in the serialization of this <code>SerialArray</code>
657 * object.
658 */
659 static final long serialVersionUID = -8466174297270688520L;
660 }