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