javax.sql.rowset.serial.SerialArray Maven / Gradle / Ivy
/*
* Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javax.sql.rowset.serial;
import java.sql.*;
import java.io.*;
import java.util.Map;
import java.net.URL;
import java.util.Arrays;
/**
* A serialized version of an Array
* object, which is the mapping in the Java programming language of an SQL
* ARRAY value.
*
* The SerialArray class provides a constructor for creating
* a SerialArray instance from an Array object,
* methods for getting the base type and the SQL name for the base type, and
* methods for copying all or part of a SerialArray object.
*
*
* Note: In order for this class to function correctly, a connection to the
* data source
* must be available in order for the SQL Array object to be
* materialized (have all of its elements brought to the client server)
* if necessary. At this time, logical pointers to the data in the data source,
* such as locators, are not currently supported.
*
*
Thread safety
*
* A SerialArray is not safe for use by multiple concurrent threads. If a
* SerialArray is to be used by more than one thread then access to the
* SerialArray should be controlled by appropriate synchronization.
*
*/
public class SerialArray implements Array, Serializable, Cloneable {
/**
* A serialized array in which each element is an Object
* in the Java programming language that represents an element
* in the SQL ARRAY value.
* @serial
*/
private Object[] elements;
/**
* The SQL type of the elements in this SerialArray object. The
* type is expressed as one of the constants from the class
* java.sql.Types.
* @serial
*/
private int baseType;
/**
* The type name used by the DBMS for the elements in the SQL ARRAY
* value that this SerialArray object represents.
* @serial
*/
private String baseTypeName;
/**
* The number of elements in this SerialArray object, which
* is also the number of elements in the SQL ARRAY value
* that this SerialArray object represents.
* @serial
*/
private int len;
/**
* Constructs a new SerialArray object from the given
* Array object, using the given type map for the custom
* mapping of each element when the elements are SQL UDTs.
*
* This method does custom mapping if the array elements are a UDT
* and the given type map has an entry for that UDT.
* Custom mapping is recursive,
* meaning that if, for instance, an element of an SQL structured type
* is an SQL structured type that itself has an element that is an SQL
* structured type, each structured type that has a custom mapping will be
* mapped according to the given type map.
*
* The new SerialArray
* object contains the same elements as the Array object
* from which it is built, except when the base type is the SQL type
* STRUCT, ARRAY, BLOB,
* CLOB, DATALINK or JAVA_OBJECT.
* In this case, each element in the new
* SerialArray object is the appropriate serialized form,
* that is, a SerialStruct, SerialArray,
* SerialBlob, SerialClob,
* SerialDatalink, or SerialJavaObject object.
*
* Note: (1) The Array object from which a SerialArray
* object is created must have materialized the SQL ARRAY value's
* data on the client before it is passed to the constructor. Otherwise,
* the new SerialArray object will contain no data.
*
* Note: (2) If the Array contains java.sql.Types.JAVA_OBJECT
* types, the SerialJavaObject constructor is called where checks
* are made to ensure this object is serializable.
*
* Note: (3) The Array object supplied to this constructor cannot
* return null for any Array.getArray() methods.
* SerialArray cannot serialize null array values.
*
*
* @param array the Array object to be serialized
* @param map a java.util.Map object in which
* each entry consists of 1) a String object
* giving the fully qualified name of a UDT (an SQL structured type or
* distinct type) and 2) the
* Class object for the SQLData implementation
* that defines how the UDT is to be mapped. The map
* parameter does not have any effect for Blob,
* Clob, DATALINK, or
* JAVA_OBJECT types.
* @throws SerialException if an error occurs serializing the
* Array object
* @throws SQLException if a database access error occurs or if the
* array or the map values are null
*/
public SerialArray(Array array, Map> map)
throws SerialException, SQLException
{
if ((array == null) || (map == null)) {
throw new SQLException("Cannot instantiate a SerialArray " +
"object with null parameters");
}
if ((elements = (Object[])array.getArray()) == null) {
throw new SQLException("Invalid Array object. Calls to Array.getArray() " +
"return null value which cannot be serialized");
}
elements = (Object[])array.getArray(map);
baseType = array.getBaseType();
baseTypeName = array.getBaseTypeName();
len = elements.length;
switch (baseType) {
case java.sql.Types.STRUCT:
for (int i = 0; i < len; i++) {
elements[i] = new SerialStruct((Struct)elements[i], map);
}
break;
case java.sql.Types.ARRAY:
for (int i = 0; i < len; i++) {
elements[i] = new SerialArray((Array)elements[i], map);
}
break;
case java.sql.Types.BLOB:
for (int i = 0; i < len; i++) {
elements[i] = new SerialBlob((Blob)elements[i]);
}
break;
case java.sql.Types.CLOB:
for (int i = 0; i < len; i++) {
elements[i] = new SerialClob((Clob)elements[i]);
}
break;
case java.sql.Types.DATALINK:
for (int i = 0; i < len; i++) {
elements[i] = new SerialDatalink((URL)elements[i]);
}
break;
case java.sql.Types.JAVA_OBJECT:
for (int i = 0; i < len; i++) {
elements[i] = new SerialJavaObject(elements[i]);
}
}
}
/**
* This method frees the {@code SeriableArray} object and releases the
* resources that it holds. The object is invalid once the {@code free}
* method is called. If {@code free} is called multiple times, the
* subsequent calls to {@code free} are treated as a no-op.
*
* @throws SQLException if an error occurs releasing the SerialArray's resources
* @since 1.6
*/
public void free() throws SQLException {
if (elements != null) {
elements = null;
baseTypeName= null;
}
}
/**
* Constructs a new SerialArray object from the given
* Array object.
*
* This constructor does not do custom mapping. If the base type of the array
* is an SQL structured type and custom mapping is desired, the constructor
* SerialArray(Array array, Map map) should be used.
*
* The new SerialArray
* object contains the same elements as the Array object
* from which it is built, except when the base type is the SQL type
* BLOB,
* CLOB, DATALINK or JAVA_OBJECT.
* In this case, each element in the new
* SerialArray object is the appropriate serialized form,
* that is, a SerialBlob, SerialClob,
* SerialDatalink, or SerialJavaObject object.
*
* Note: (1) The Array object from which a SerialArray
* object is created must have materialized the SQL ARRAY value's
* data on the client before it is passed to the constructor. Otherwise,
* the new SerialArray object will contain no data.
*
* Note: (2) The Array object supplied to this constructor cannot
* return null for any Array.getArray() methods.
* SerialArray cannot serialize null array values.
*
* @param array the Array object to be serialized
* @throws SerialException if an error occurs serializing the
* Array object
* @throws SQLException if a database access error occurs or the
* array parameter is null.
*/
public SerialArray(Array array) throws SerialException, SQLException {
if (array == null) {
throw new SQLException("Cannot instantiate a SerialArray " +
"object with a null Array object");
}
if ((elements = (Object[])array.getArray()) == null) {
throw new SQLException("Invalid Array object. Calls to Array.getArray() " +
"return null value which cannot be serialized");
}
//elements = (Object[])array.getArray();
baseType = array.getBaseType();
baseTypeName = array.getBaseTypeName();
len = elements.length;
switch (baseType) {
case java.sql.Types.BLOB:
for (int i = 0; i < len; i++) {
elements[i] = new SerialBlob((Blob)elements[i]);
}
break;
case java.sql.Types.CLOB:
for (int i = 0; i < len; i++) {
elements[i] = new SerialClob((Clob)elements[i]);
}
break;
case java.sql.Types.DATALINK:
for (int i = 0; i < len; i++) {
elements[i] = new SerialDatalink((URL)elements[i]);
}
break;
case java.sql.Types.JAVA_OBJECT:
for (int i = 0; i < len; i++) {
elements[i] = new SerialJavaObject(elements[i]);
}
break;
}
}
/**
* Returns a new array that is a copy of this SerialArray
* object.
*
* @return a copy of this SerialArray object as an
* Object in the Java programming language
* @throws SerialException if an error occurs;
* if {@code free} had previously been called on this object
*/
public Object getArray() throws SerialException {
isValid();
Object dst = new Object[len];
System.arraycopy((Object)elements, 0, dst, 0, len);
return dst;
}
//[if an error occurstype map used??]
/**
* Returns a new array that is a copy of this SerialArray
* object, using the given type map for the custom
* mapping of each element when the elements are SQL UDTs.
*
* This method does custom mapping if the array elements are a UDT
* and the given type map has an entry for that UDT.
* Custom mapping is recursive,
* meaning that if, for instance, an element of an SQL structured type
* is an SQL structured type that itself has an element that is an SQL
* structured type, each structured type that has a custom mapping will be
* mapped according to the given type map.
*
* @param map a java.util.Map object in which
* each entry consists of 1) a String object
* giving the fully qualified name of a UDT and 2) the
* Class object for the SQLData implementation
* that defines how the UDT is to be mapped
* @return a copy of this SerialArray object as an
* Object in the Java programming language
* @throws SerialException if an error occurs;
* if {@code free} had previously been called on this object
*/
public Object getArray(Map> map) throws SerialException {
isValid();
Object dst[] = new Object[len];
System.arraycopy((Object)elements, 0, dst, 0, len);
return dst;
}
/**
* Returns a new array that is a copy of a slice
* of this SerialArray object, starting with the
* element at the given index and containing the given number
* of consecutive elements.
*
* @param index the index into this SerialArray object
* of the first element to be copied;
* the index of the first element is 0
* @param count the number of consecutive elements to be copied, starting
* at the given index
* @return a copy of the designated elements in this SerialArray
* object as an Object in the Java programming language
* @throws SerialException if an error occurs;
* if {@code free} had previously been called on this object
*/
public Object getArray(long index, int count) throws SerialException {
isValid();
Object dst = new Object[count];
System.arraycopy((Object)elements, (int)index, dst, 0, count);
return dst;
}
/**
* Returns a new array that is a copy of a slice
* of this SerialArray object, starting with the
* element at the given index and containing the given number
* of consecutive elements.
*
* This method does custom mapping if the array elements are a UDT
* and the given type map has an entry for that UDT.
* Custom mapping is recursive,
* meaning that if, for instance, an element of an SQL structured type
* is an SQL structured type that itself has an element that is an SQL
* structured type, each structured type that has a custom mapping will be
* mapped according to the given type map.
*
* @param index the index into this SerialArray object
* of the first element to be copied; the index of the
* first element in the array is 0
* @param count the number of consecutive elements to be copied, starting
* at the given index
* @param map a java.util.Map object in which
* each entry consists of 1) a String object
* giving the fully qualified name of a UDT and 2) the
* Class object for the SQLData implementation
* that defines how the UDT is to be mapped
* @return a copy of the designated elements in this SerialArray
* object as an Object in the Java programming language
* @throws SerialException if an error occurs;
* if {@code free} had previously been called on this object
*/
public Object getArray(long index, int count, Map> map)
throws SerialException
{
isValid();
Object dst = new Object[count];
System.arraycopy((Object)elements, (int)index, dst, 0, count);
return dst;
}
/**
* Retrieves the SQL type of the elements in this SerialArray
* object. The int returned is one of the constants in the class
* java.sql.Types.
*
* @return one of the constants in java.sql.Types, indicating
* the SQL type of the elements in this SerialArray object
* @throws SerialException if an error occurs;
* if {@code free} had previously been called on this object
*/
public int getBaseType() throws SerialException {
isValid();
return baseType;
}
/**
* Retrieves the DBMS-specific type name for the elements in this
* SerialArray object.
*
* @return the SQL type name used by the DBMS for the base type of this
* SerialArray object
* @throws SerialException if an error occurs;
* if {@code free} had previously been called on this object
*/
public String getBaseTypeName() throws SerialException {
isValid();
return baseTypeName;
}
/**
* Retrieves a ResultSet object holding the elements of
* the subarray that starts at
* index index and contains up to count successive elements.
* This method uses the connection's type map to map the elements of
* the array if the map contains
* an entry for the base type. Otherwise, the standard mapping is used.
*
* @param index the index into this SerialArray object
* of the first element to be copied; the index of the
* first element in the array is 0
* @param count the number of consecutive elements to be copied, starting
* at the given index
* @return a ResultSet object containing the designated
* elements in this SerialArray object, with a
* separate row for each element
* @throws SerialException if called with the cause set to
* {@code UnsupportedOperationException}
*/
public ResultSet getResultSet(long index, int count) throws SerialException {
SerialException se = new SerialException();
se.initCause(new UnsupportedOperationException());
throw se;
}
/**
*
* Retrieves a ResultSet object that contains all of
* the elements of the SQL ARRAY
* value represented by this SerialArray object. This method uses
* the specified map for type map customizations unless the base type of the
* array does not match a user-defined type (UDT) in map, in
* which case it uses the
* standard mapping. This version of the method getResultSet
* uses either the given type map or the standard mapping; it never uses the
* type map associated with the connection.
*
* @param map a java.util.Map object in which
* each entry consists of 1) a String object
* giving the fully qualified name of a UDT and 2) the
* Class object for the SQLData implementation
* that defines how the UDT is to be mapped
* @return a ResultSet object containing all of the
* elements in this SerialArray object, with a
* separate row for each element
* @throws SerialException if called with the cause set to
* {@code UnsupportedOperationException}
*/
public ResultSet getResultSet(Map> map)
throws SerialException
{
SerialException se = new SerialException();
se.initCause(new UnsupportedOperationException());
throw se;
}
/**
* Retrieves a ResultSet object that contains all of
* the elements in the ARRAY value that this
* SerialArray object represents.
* If appropriate, the elements of the array are mapped using the connection's
* type map; otherwise, the standard mapping is used.
*
* @return a ResultSet object containing all of the
* elements in this SerialArray object, with a
* separate row for each element
* @throws SerialException if called with the cause set to
* {@code UnsupportedOperationException}
*/
public ResultSet getResultSet() throws SerialException {
SerialException se = new SerialException();
se.initCause(new UnsupportedOperationException());
throw se;
}
/**
* Retrieves a result set holding the elements of the subarray that starts at
* Retrieves a ResultSet object that contains a subarray of the
* elements in this SerialArray object, starting at
* index index and containing up to count successive
* elements. This method uses
* the specified map for type map customizations unless the base type of the
* array does not match a user-defined type (UDT) in map, in
* which case it uses the
* standard mapping. This version of the method getResultSet uses
* either the given type map or the standard mapping; it never uses the type
* map associated with the connection.
*
* @param index the index into this SerialArray object
* of the first element to be copied; the index of the
* first element in the array is 0
* @param count the number of consecutive elements to be copied, starting
* at the given index
* @param map a java.util.Map object in which
* each entry consists of 1) a String object
* giving the fully qualified name of a UDT and 2) the
* Class object for the SQLData implementation
* that defines how the UDT is to be mapped
* @return a ResultSet object containing the designated
* elements in this SerialArray object, with a
* separate row for each element
* @throws SerialException if called with the cause set to
* {@code UnsupportedOperationException}
*/
public ResultSet getResultSet(long index, int count,
Map> map)
throws SerialException
{
SerialException se = new SerialException();
se.initCause(new UnsupportedOperationException());
throw se;
}
/**
* Compares this SerialArray to the specified object. The result is {@code
* true} if and only if the argument is not {@code null} and is a {@code
* SerialArray} object whose elements are identical to this object's elements
*
* @param obj The object to compare this {@code SerialArray} against
*
* @return {@code true} if the given object represents a {@code SerialArray}
* equivalent to this SerialArray, {@code false} otherwise
*
*/
public boolean equals(Object obj) {
if (this == obj) {
return true;
}
if (obj instanceof SerialArray) {
SerialArray sa = (SerialArray)obj;
return baseType == sa.baseType &&
baseTypeName.equals(sa.baseTypeName) &&
Arrays.equals(elements, sa.elements);
}
return false;
}
/**
* Returns a hash code for this SerialArray. The hash code for a
* {@code SerialArray} object is computed using the hash codes
* of the elements of the {@code SerialArray} object
*
* @return a hash code value for this object.
*/
public int hashCode() {
return (((31 + Arrays.hashCode(elements)) * 31 + len) * 31 +
baseType) * 31 + baseTypeName.hashCode();
}
/**
* Returns a clone of this {@code SerialArray}. The copy will contain a
* reference to a clone of the underlying objects array, not a reference
* to the original underlying object array of this {@code SerialArray} object.
*
* @return a clone of this SerialArray
*/
public Object clone() {
try {
SerialArray sa = (SerialArray) super.clone();
sa.elements = (elements != null) ? Arrays.copyOf(elements, len) : null;
return sa;
} catch (CloneNotSupportedException ex) {
// this shouldn't happen, since we are Cloneable
throw new InternalError();
}
}
/**
* readObject is called to restore the state of the {@code SerialArray} from
* a stream.
*/
private void readObject(ObjectInputStream s)
throws IOException, ClassNotFoundException {
ObjectInputStream.GetField fields = s.readFields();
Object[] tmp = (Object[])fields.get("elements", null);
if (tmp == null)
throw new InvalidObjectException("elements is null and should not be!");
elements = tmp.clone();
len = fields.get("len", 0);
if(elements.length != len)
throw new InvalidObjectException("elements is not the expected size");
baseType = fields.get("baseType", 0);
baseTypeName = (String)fields.get("baseTypeName", null);
}
/**
* writeObject is called to save the state of the {@code SerialArray}
* to a stream.
*/
private void writeObject(ObjectOutputStream s)
throws IOException, ClassNotFoundException {
ObjectOutputStream.PutField fields = s.putFields();
fields.put("elements", elements);
fields.put("len", len);
fields.put("baseType", baseType);
fields.put("baseTypeName", baseTypeName);
s.writeFields();
}
/**
* Check to see if this object had previously had its {@code free} method
* called
*
* @throws SerialException
*/
private void isValid() throws SerialException {
if (elements == null) {
throw new SerialException("Error: You cannot call a method on a "
+ "SerialArray instance once free() has been called.");
}
}
/**
* The identifier that assists in the serialization of this SerialArray
* object.
*/
static final long serialVersionUID = -8466174297270688520L;
}