- java.lang.Object
-
- javax.sql.rowset.serial.SerialArray
-
- All Implemented Interfaces:
Serializable
,Cloneable
,Array
public class SerialArray extends Object implements Array, Serializable, Cloneable
A serialized version of anArray
object, which is the mapping in the Java programming language of an SQLARRAY
value.The
SerialArray
class provides a constructor for creating aSerialArray
instance from anArray
object, methods for getting the base type and the SQL name for the base type, and methods for copying all or part of aSerialArray
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.- Since:
- 1.5
- See Also:
- Serialized Form
-
-
Constructor Summary
Constructors Constructor Description SerialArray(Array array)
Constructs a newSerialArray
object from the givenArray
object.SerialArray(Array array, Map<String,Class<?>> map)
Constructs a newSerialArray
object from the givenArray
object, using the given type map for the custom mapping of each element when the elements are SQL UDTs.
-
Method Summary
Modifier and Type Method Description Object
clone()
Returns a clone of thisSerialArray
.boolean
equals(Object obj)
Compares this SerialArray to the specified object.void
free()
This method frees theSerialArray
object and releases the resources that it holds.Object
getArray()
Returns a new array that is a copy of thisSerialArray
object.Object
getArray(long index, int count)
Returns a new array that is a copy of a slice of thisSerialArray
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 thisSerialArray
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 thisSerialArray
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 thisSerialArray
object.String
getBaseTypeName()
Retrieves the DBMS-specific type name for the elements in thisSerialArray
object.ResultSet
getResultSet()
Retrieves aResultSet
object that contains all of the elements in theARRAY
value that thisSerialArray
object represents.ResultSet
getResultSet(long index, int count)
Retrieves aResultSet
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 aResultSet
object that contains a subarray of the elements in thisSerialArray
object, starting at index index and containing up to count successive elements.ResultSet
getResultSet(Map<String,Class<?>> map)
Retrieves aResultSet
object that contains all of the elements of the SQLARRAY
value represented by thisSerialArray
object.int
hashCode()
Returns a hash code for this SerialArray.
-
-
-
Constructor Detail
-
SerialArray
public SerialArray(Array array, Map<String,Class<?>> map) throws SerialException, SQLException
Constructs a newSerialArray
object from the givenArray
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 theArray
object from which it is built, except when the base type is the SQL typeSTRUCT
,ARRAY
,BLOB
,CLOB
,DATALINK
orJAVA_OBJECT
. In this case, each element in the newSerialArray
object is the appropriate serialized form, that is, aSerialStruct
,SerialArray
,SerialBlob
,SerialClob
,SerialDatalink
, orSerialJavaObject
object.Note: (1) The
Array
object from which aSerialArray
object is created must have materialized the SQLARRAY
value's data on the client before it is passed to the constructor. Otherwise, the newSerialArray
object will contain no data.Note: (2) If the
Array
containsjava.sql.Types.JAVA_OBJECT
types, theSerialJavaObject
constructor is called where checks are made to ensure this object is serializable.Note: (3) The
Array
object supplied to this constructor cannot returnnull
for anyArray.getArray()
methods.SerialArray
cannot serialize null array values.- Parameters:
array
- theArray
object to be serializedmap
- ajava.util.Map
object in which each entry consists of 1) aString
object giving the fully qualified name of a UDT (an SQL structured type or distinct type) and 2) theClass
object for theSQLData
implementation that defines how the UDT is to be mapped. The map parameter does not have any effect forBlob
,Clob
,DATALINK
, orJAVA_OBJECT
types.- Throws:
SerialException
- if an error occurs serializing theArray
objectSQLException
- if a database access error occurs or if the array or the map values arenull
-
SerialArray
public SerialArray(Array array) throws SerialException, SQLException
Constructs a newSerialArray
object from the givenArray
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 theArray
object from which it is built, except when the base type is the SQL typeBLOB
,CLOB
,DATALINK
orJAVA_OBJECT
. In this case, each element in the newSerialArray
object is the appropriate serialized form, that is, aSerialBlob
,SerialClob
,SerialDatalink
, orSerialJavaObject
object.Note: (1) The
Array
object from which aSerialArray
object is created must have materialized the SQLARRAY
value's data on the client before it is passed to the constructor. Otherwise, the newSerialArray
object will contain no data.Note: (2) The
Array
object supplied to this constructor cannot returnnull
for anyArray.getArray()
methods.SerialArray
cannot serializenull
array values.- Parameters:
array
- theArray
object to be serialized- Throws:
SerialException
- if an error occurs serializing theArray
objectSQLException
- if a database access error occurs or the array parameter isnull
.
-
-
Method Detail
-
free
public void free() throws SQLException
This method frees theSerialArray
object and releases the resources that it holds. The object is invalid once thefree
method is called.If
free
is called multiple times, the subsequent calls tofree
are treated as a no-op.- Specified by:
free
in interfaceArray
- Throws:
SQLException
- if an error occurs releasing the SerialArray's resources- Since:
- 1.6
-
getArray
public Object getArray() throws SerialException
Returns a new array that is a copy of thisSerialArray
object.- Specified by:
getArray
in interfaceArray
- Returns:
- a copy of this
SerialArray
object as anObject
in the Java programming language - Throws:
SerialException
- if an error occurs; iffree
had previously been called on this object
-
getArray
public Object getArray(Map<String,Class<?>> map) throws SerialException
Returns a new array that is a copy of thisSerialArray
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.
- Specified by:
getArray
in interfaceArray
- Parameters:
map
- ajava.util.Map
object in which each entry consists of 1) aString
object giving the fully qualified name of a UDT and 2) theClass
object for theSQLData
implementation that defines how the UDT is to be mapped- Returns:
- a copy of this
SerialArray
object as anObject
in the Java programming language - Throws:
SerialException
- if an error occurs; iffree
had previously been called on this object
-
getArray
public Object getArray(long index, int count) throws SerialException
Returns a new array that is a copy of a slice of thisSerialArray
object, starting with the element at the given index and containing the given number of consecutive elements.- Specified by:
getArray
in interfaceArray
- Parameters:
index
- the index into thisSerialArray
object of the first element to be copied; the index of the first element is0
count
- the number of consecutive elements to be copied, starting at the given index- Returns:
- a copy of the designated elements in this
SerialArray
object as anObject
in the Java programming language - Throws:
SerialException
- if an error occurs; iffree
had previously been called on this object
-
getArray
public Object getArray(long index, int count, Map<String,Class<?>> map) throws SerialException
Returns a new array that is a copy of a slice of thisSerialArray
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.
- Specified by:
getArray
in interfaceArray
- Parameters:
index
- the index into thisSerialArray
object of the first element to be copied; the index of the first element in the array is0
count
- the number of consecutive elements to be copied, starting at the given indexmap
- ajava.util.Map
object in which each entry consists of 1) aString
object giving the fully qualified name of a UDT and 2) theClass
object for theSQLData
implementation that defines how the UDT is to be mapped- Returns:
- a copy of the designated elements in this
SerialArray
object as anObject
in the Java programming language - Throws:
SerialException
- if an error occurs; iffree
had previously been called on this object
-
getBaseType
public int getBaseType() throws SerialException
Retrieves the SQL type of the elements in thisSerialArray
object. Theint
returned is one of the constants in the classjava.sql.Types
.- Specified by:
getBaseType
in interfaceArray
- Returns:
- one of the constants in
java.sql.Types
, indicating the SQL type of the elements in thisSerialArray
object - Throws:
SerialException
- if an error occurs; iffree
had previously been called on this object
-
getBaseTypeName
public String getBaseTypeName() throws SerialException
Retrieves the DBMS-specific type name for the elements in thisSerialArray
object.- Specified by:
getBaseTypeName
in interfaceArray
- Returns:
- the SQL type name used by the DBMS for the base type of this
SerialArray
object - Throws:
SerialException
- if an error occurs; iffree
had previously been called on this object
-
getResultSet
public ResultSet getResultSet(long index, int count) throws SerialException
Retrieves aResultSet
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.- Specified by:
getResultSet
in interfaceArray
- Parameters:
index
- the index into thisSerialArray
object of the first element to be copied; the index of the first element in the array is0
count
- the number of consecutive elements to be copied, starting at the given index- Returns:
- a
ResultSet
object containing the designated elements in thisSerialArray
object, with a separate row for each element - Throws:
SerialException
- if called with the cause set toUnsupportedOperationException
-
getResultSet
public ResultSet getResultSet(Map<String,Class<?>> map) throws SerialException
Retrieves aResultSet
object that contains all of the elements of the SQLARRAY
value represented by thisSerialArray
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 methodgetResultSet
uses either the given type map or the standard mapping; it never uses the type map associated with the connection.- Specified by:
getResultSet
in interfaceArray
- Parameters:
map
- ajava.util.Map
object in which each entry consists of 1) aString
object giving the fully qualified name of a UDT and 2) theClass
object for theSQLData
implementation that defines how the UDT is to be mapped- Returns:
- a
ResultSet
object containing all of the elements in thisSerialArray
object, with a separate row for each element - Throws:
SerialException
- if called with the cause set toUnsupportedOperationException
-
getResultSet
public ResultSet getResultSet() throws SerialException
Retrieves aResultSet
object that contains all of the elements in theARRAY
value that thisSerialArray
object represents. If appropriate, the elements of the array are mapped using the connection's type map; otherwise, the standard mapping is used.- Specified by:
getResultSet
in interfaceArray
- Returns:
- a
ResultSet
object containing all of the elements in thisSerialArray
object, with a separate row for each element - Throws:
SerialException
- if called with the cause set toUnsupportedOperationException
-
getResultSet
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 aResultSet
object that contains a subarray of the elements in thisSerialArray
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 methodgetResultSet
uses either the given type map or the standard mapping; it never uses the type map associated with the connection.- Specified by:
getResultSet
in interfaceArray
- Parameters:
index
- the index into thisSerialArray
object of the first element to be copied; the index of the first element in the array is0
count
- the number of consecutive elements to be copied, starting at the given indexmap
- ajava.util.Map
object in which each entry consists of 1) aString
object giving the fully qualified name of a UDT and 2) theClass
object for theSQLData
implementation that defines how the UDT is to be mapped- Returns:
- a
ResultSet
object containing the designated elements in thisSerialArray
object, with a separate row for each element - Throws:
SerialException
- if called with the cause set toUnsupportedOperationException
-
equals
public boolean equals(Object obj)
Compares this SerialArray to the specified object. The result istrue
if and only if the argument is notnull
and is aSerialArray
object whose elements are identical to this object's elements- Overrides:
equals
in classObject
- Parameters:
obj
- The object to compare thisSerialArray
against- Returns:
true
if the given object represents aSerialArray
equivalent to this SerialArray,false
otherwise- See Also:
Object.hashCode()
,HashMap
-
hashCode
public int hashCode()
Returns a hash code for this SerialArray. The hash code for aSerialArray
object is computed using the hash codes of the elements of theSerialArray
object- Overrides:
hashCode
in classObject
- Returns:
- a hash code value for this object.
- See Also:
Object.equals(java.lang.Object)
,System.identityHashCode(java.lang.Object)
-
clone
public Object clone()
Returns a clone of thisSerialArray
. The copy will contain a reference to a clone of the underlying objects array, not a reference to the original underlying object array of thisSerialArray
object.
-
-