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 }