public class SerialArray extends Object implements Array, Serializable, Cloneable
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.
| Constructor and Description |
|---|
SerialArray(Array array)
Constructs a new
SerialArray object from the given
Array object. |
SerialArray(Array array,
Map<String,Class<?>> map)
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. |
| Modifier and Type | Method and Description |
|---|---|
void |
free()
This method frees the
Array object and releases the resources that
it holds. |
Object |
getArray()
Returns a new array that is a copy of this
SerialArray
object. |
Object |
getArray(long index,
int count)
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. |
Object |
getArray(long index,
int count,
Map<String,Class<?>> map)
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. |
Object |
getArray(Map<String,Class<?>> map)
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. |
int |
getBaseType()
Retrieves the SQL type of the elements in this
SerialArray
object. |
String |
getBaseTypeName()
Retrieves the DBMS-specific type name for the elements in this
SerialArray object. |
ResultSet |
getResultSet()
Retrieves a
ResultSet object that contains all of
the elements in the ARRAY value that this
SerialArray object represents. |
ResultSet |
getResultSet(long index,
int count)
Retrieves a
ResultSet object holding the elements of
the subarray that starts at
index index and contains up to count successive elements. |
ResultSet |
getResultSet(long index,
int count,
Map<String,Class<?>> map)
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. |
ResultSet |
getResultSet(Map<String,Class<?>> map)
Retrieves a
ResultSet object that contains all of
the elements of the SQL ARRAY
value represented by this SerialArray object. |
public SerialArray(Array array, Map<String,Class<?>> map) throws SerialException, SQLException
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 nullpublic SerialArray(Array array) throws SerialException, SQLException
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
Array object and releases the resources that
it holds. The object is invalid once the free
method is called.
After free has been called, any attempt to invoke a
method other than free will result in a SQLException
being thrown. If free is called multiple times, the subsequent
calls to free are treated as a no-op.
free in interface ArraySQLException - if an error occurs releasing
the Array's resourcesSQLFeatureNotSupportedException - if the JDBC driver does not support
this methodpublic Object getArray() throws SerialException
SerialArray
object.getArray in interface ArraySerialArray object as an
Object in the Java programming languageSerialException - if an error occurs retrieving a copy of
this SerialArray objectpublic Object getArray(Map<String,Class<?>> map) throws SerialException
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 Arraymap - 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 occurspublic Object getArray(long index, int count) throws SerialException
SerialArray object, starting with the
element at the given index and containing the given number
of consecutive elements.getArray in interface Arrayindex - the index into this SerialArray object
of the first element to be copied;
the index of the first element is 0count - 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 occurspublic Object getArray(long index, int count, Map<String,Class<?>> map) throws SerialException
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 Arrayindex - the index into this SerialArray object
of the first element to be copied; the index of the
first element in the array is 0count - 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 occurspublic int getBaseType()
throws SerialException
SerialArray
object. The int returned is one of the constants in the class
java.sql.Types.getBaseType in interface Arrayjava.sql.Types, indicating
the SQL type of the elements in this SerialArray objectSerialException - if an error occurspublic String getBaseTypeName() throws SerialException
SerialArray object.getBaseTypeName in interface ArraySerialArray objectSerialException - if an error occurspublic ResultSet getResultSet(long index, int count) throws SerialException
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 Arrayindex - the index into this SerialArray object
of the first element to be copied; the index of the
first element in the array is 0count - 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, - which in turn throws an
UnsupportedOperationException, if this method is calledSerialExceptionpublic ResultSet getResultSet(Map<String,Class<?>> map) throws SerialException
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 Arraymap - 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, - which in turn throws an
UnsupportedOperationException, if this method is calledSerialExceptionpublic ResultSet getResultSet() throws SerialException
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 ArrayResultSet object containing all of the
elements in this SerialArray object, with a
separate row for each elementSerialException - if called, which in turn throws an
UnsupportedOperationException, if this method is calledpublic ResultSet getResultSet(long index, int count, Map<String,Class<?>> map) throws SerialException
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 Arrayindex - the index into this SerialArray object
of the first element to be copied; the index of the
first element in the array is 0count - 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, which in turn throws an
UnsupportedOperationException Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved.
DRAFT ea-b138