public class SerialArray extends Object implements Array, Serializable, Cloneable
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.
public SerialArray(Array array, Map<String,Class<?>> map) throws SerialException, SQLException
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.
array
- the Array
object to be serializedmap
- 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.SerialException
- if an error occurs serializing the Array
objectSQLException
- if a database access error occurs or if the array or the map values are null
public SerialArray(Array array) throws SerialException, SQLException
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.
array
- the Array
object to be serializedSerialException
- if an error occurs serializing the Array
objectSQLException
- if a database access error occurs or the array parameter is null
.public void free() throws SQLException
This method frees the SeriableArray
object and releases the resources that it holds. The object is invalid once the free
method is called.
If free
is called multiple times, the subsequent calls to free
are treated as a no-op.
free
in interface Array
SQLException
- if an error occurs releasing the SerialArray's resourcespublic Object getArray() throws SerialException
Returns a new array that is a copy of this SerialArray
object.
getArray
in interface Array
SerialArray
object as an Object
in the Java programming languageSerialException
- if an error occurs; if free
had previously been called on this objectpublic Object getArray(Map<String,Class<?>> map) throws SerialException
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.
getArray
in interface Array
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 mappedSerialArray
object as an Object
in the Java programming languageSerialException
- if an error occurs; if free
had previously been called on this objectpublic Object getArray(long index, int count) throws SerialException
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.
getArray
in interface Array
index
- the index into this SerialArray
object of the first element to be copied; the index of the first element is 0
count
- the number of consecutive elements to be copied, starting at the given indexSerialArray
object as an Object
in the Java programming languageSerialException
- if an error occurs; if free
had previously been called on this objectpublic Object getArray(long index, int count, Map<String,Class<?>> map) throws SerialException
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.
getArray
in interface Array
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
count
- the number of consecutive elements to be copied, starting at the given indexmap
- 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 mappedSerialArray
object as an Object
in the Java programming languageSerialException
- if an error occurs; if free
had previously been called on this objectpublic int getBaseType() throws SerialException
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
.
getBaseType
in interface Array
java.sql.Types
, indicating the SQL type of the elements in this SerialArray
objectSerialException
- if an error occurs; if free
had previously been called on this objectpublic String getBaseTypeName() throws SerialException
Retrieves the DBMS-specific type name for the elements in this SerialArray
object.
getBaseTypeName
in interface Array
SerialArray
objectSerialException
- if an error occurs; if free
had previously been called on this objectpublic ResultSet getResultSet(long index, int count) throws SerialException
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.
getResultSet
in interface Array
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
count
- the number of consecutive elements to be copied, starting at the given indexResultSet
object containing the designated elements in this SerialArray
object, with a separate row for each elementSerialException
- if called with the cause set to UnsupportedOperationException
public ResultSet getResultSet(Map<String,Class<?>> map) throws SerialException
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.
getResultSet
in interface Array
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 mappedResultSet
object containing all of the elements in this SerialArray
object, with a separate row for each elementSerialException
- if called with the cause set to UnsupportedOperationException
public ResultSet getResultSet() throws SerialException
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.
getResultSet
in interface Array
ResultSet
object containing all of the elements in this SerialArray
object, with a separate row for each elementSerialException
- if called with the cause set to UnsupportedOperationException
public ResultSet getResultSet(long index, int count, Map<String,Class<?>> map) throws SerialException
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.
getResultSet
in interface Array
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
count
- the number of consecutive elements to be copied, starting at the given indexmap
- 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 mappedResultSet
object containing the designated elements in this SerialArray
object, with a separate row for each elementSerialException
- if called with the cause set to UnsupportedOperationException
public boolean equals(Object obj)
Compares this SerialArray to the specified object. The result is true
if and only if the argument is not null
and is a SerialArray
object whose elements are identical to this object's elements
equals
in class Object
obj
- The object to compare this SerialArray
againsttrue
if the given object represents a SerialArray
equivalent to this SerialArray, false
otherwiseObject.hashCode()
, HashMap
public int hashCode()
Returns a hash code for this SerialArray. The hash code for a SerialArray
object is computed using the hash codes of the elements of the SerialArray
object
hashCode
in class Object
Object.equals(java.lang.Object)
, System.identityHashCode(java.lang.Object)
public Object clone()
Returns a clone of this 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 SerialArray
object.
© 1993–2017, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.