- 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 anArrayobject, which is the mapping in the Java programming language of an SQLARRAYvalue.The
SerialArrayclass provides a constructor for creating aSerialArrayinstance from anArrayobject, methods for getting the base type and the SQL name for the base type, and methods for copying all or part of aSerialArrayobject.Note: In order for this class to function correctly, a connection to the data source must be available in order for the SQL
Arrayobject 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 newSerialArrayobject from the givenArrayobject.SerialArray(Array array, Map<String,Class<?>> map)Constructs a newSerialArrayobject from the givenArrayobject, using the given type map for the custom mapping of each element when the elements are SQL UDTs.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description Objectclone()Returns a clone of thisSerialArray.booleanequals(Object obj)Compares this SerialArray to the specified object.voidfree()This method frees theSerialArrayobject and releases the resources that it holds.ObjectgetArray()Returns a new array that is a copy of thisSerialArrayobject.ObjectgetArray(long index, int count)Returns a new array that is a copy of a slice of thisSerialArrayobject, starting with the element at the given index and containing the given number of consecutive elements.ObjectgetArray(long index, int count, Map<String,Class<?>> map)Returns a new array that is a copy of a slice of thisSerialArrayobject, starting with the element at the given index and containing the given number of consecutive elements.ObjectgetArray(Map<String,Class<?>> map)Returns a new array that is a copy of thisSerialArrayobject, using the given type map for the custom mapping of each element when the elements are SQL UDTs.intgetBaseType()Retrieves the SQL type of the elements in thisSerialArrayobject.StringgetBaseTypeName()Retrieves the DBMS-specific type name for the elements in thisSerialArrayobject.ResultSetgetResultSet()Retrieves aResultSetobject that contains all of the elements in theARRAYvalue that thisSerialArrayobject represents.ResultSetgetResultSet(long index, int count)Retrieves aResultSetobject holding the elements of the subarray that starts at index index and contains up to count successive elements.ResultSetgetResultSet(long index, int count, Map<String,Class<?>> map)Retrieves a result set holding the elements of the subarray that starts at Retrieves aResultSetobject that contains a subarray of the elements in thisSerialArrayobject, starting at index index and containing up to count successive elements.ResultSetgetResultSet(Map<String,Class<?>> map)Retrieves aResultSetobject that contains all of the elements of the SQLARRAYvalue represented by thisSerialArrayobject.inthashCode()Returns a hash code for this SerialArray.
-
-
-
Constructor Detail
-
SerialArray
public SerialArray(Array array, Map<String,Class<?>> map) throws SerialException, SQLException
Constructs a newSerialArrayobject from the givenArrayobject, 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
SerialArrayobject contains the same elements as theArrayobject from which it is built, except when the base type is the SQL typeSTRUCT,ARRAY,BLOB,CLOB,DATALINKorJAVA_OBJECT. In this case, each element in the newSerialArrayobject is the appropriate serialized form, that is, aSerialStruct,SerialArray,SerialBlob,SerialClob,SerialDatalink, orSerialJavaObjectobject.Note: (1) The
Arrayobject from which aSerialArrayobject is created must have materialized the SQLARRAYvalue's data on the client before it is passed to the constructor. Otherwise, the newSerialArrayobject will contain no data.Note: (2) If the
Arraycontainsjava.sql.Types.JAVA_OBJECTtypes, theSerialJavaObjectconstructor is called where checks are made to ensure this object is serializable.Note: (3) The
Arrayobject supplied to this constructor cannot returnnullfor anyArray.getArray()methods.SerialArraycannot serialize null array values.- Parameters:
array- theArrayobject to be serializedmap- ajava.util.Mapobject in which each entry consists of 1) aStringobject giving the fully qualified name of a UDT (an SQL structured type or distinct type) and 2) theClassobject for theSQLDataimplementation that defines how the UDT is to be mapped. The map parameter does not have any effect forBlob,Clob,DATALINK, orJAVA_OBJECTtypes.- Throws:
SerialException- if an error occurs serializing theArrayobjectSQLException- 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 newSerialArrayobject from the givenArrayobject.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
SerialArrayobject contains the same elements as theArrayobject from which it is built, except when the base type is the SQL typeBLOB,CLOB,DATALINKorJAVA_OBJECT. In this case, each element in the newSerialArrayobject is the appropriate serialized form, that is, aSerialBlob,SerialClob,SerialDatalink, orSerialJavaObjectobject.Note: (1) The
Arrayobject from which aSerialArrayobject is created must have materialized the SQLARRAYvalue's data on the client before it is passed to the constructor. Otherwise, the newSerialArrayobject will contain no data.Note: (2) The
Arrayobject supplied to this constructor cannot returnnullfor anyArray.getArray()methods.SerialArraycannot serializenullarray values.- Parameters:
array- theArrayobject to be serialized- Throws:
SerialException- if an error occurs serializing theArrayobjectSQLException- if a database access error occurs or the array parameter isnull.
-
-
Method Detail
-
free
public void free() throws SQLExceptionThis method frees theSerialArrayobject and releases the resources that it holds. The object is invalid once thefreemethod is called.If
freeis called multiple times, the subsequent calls tofreeare treated as a no-op.- Specified by:
freein 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 thisSerialArrayobject.- Specified by:
getArrayin interfaceArray- Returns:
- a copy of this
SerialArrayobject as anObjectin the Java programming language - Throws:
SerialException- if an error occurs; iffreehad 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 thisSerialArrayobject, 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:
getArrayin interfaceArray- Parameters:
map- ajava.util.Mapobject in which each entry consists of 1) aStringobject giving the fully qualified name of a UDT and 2) theClassobject for theSQLDataimplementation that defines how the UDT is to be mapped- Returns:
- a copy of this
SerialArrayobject as anObjectin the Java programming language - Throws:
SerialException- if an error occurs; iffreehad 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 thisSerialArrayobject, starting with the element at the given index and containing the given number of consecutive elements.- Specified by:
getArrayin interfaceArray- Parameters:
index- the index into thisSerialArrayobject of the first element to be copied; the index of the first element is0count- the number of consecutive elements to be copied, starting at the given index- Returns:
- a copy of the designated elements in this
SerialArrayobject as anObjectin the Java programming language - Throws:
SerialException- if an error occurs; iffreehad 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 thisSerialArrayobject, 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:
getArrayin interfaceArray- Parameters:
index- the index into thisSerialArrayobject of the first element to be copied; the index of the first element in the array is0count- the number of consecutive elements to be copied, starting at the given indexmap- ajava.util.Mapobject in which each entry consists of 1) aStringobject giving the fully qualified name of a UDT and 2) theClassobject for theSQLDataimplementation that defines how the UDT is to be mapped- Returns:
- a copy of the designated elements in this
SerialArrayobject as anObjectin the Java programming language - Throws:
SerialException- if an error occurs; iffreehad previously been called on this object
-
getBaseType
public int getBaseType() throws SerialExceptionRetrieves the SQL type of the elements in thisSerialArrayobject. Theintreturned is one of the constants in the classjava.sql.Types.- Specified by:
getBaseTypein interfaceArray- Returns:
- one of the constants in
java.sql.Types, indicating the SQL type of the elements in thisSerialArrayobject - Throws:
SerialException- if an error occurs; iffreehad previously been called on this object
-
getBaseTypeName
public String getBaseTypeName() throws SerialException
Retrieves the DBMS-specific type name for the elements in thisSerialArrayobject.- Specified by:
getBaseTypeNamein interfaceArray- Returns:
- the SQL type name used by the DBMS for the base type of this
SerialArrayobject - Throws:
SerialException- if an error occurs; iffreehad previously been called on this object
-
getResultSet
public ResultSet getResultSet(long index, int count) throws SerialException
Retrieves aResultSetobject 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:
getResultSetin interfaceArray- Parameters:
index- the index into thisSerialArrayobject of the first element to be copied; the index of the first element in the array is0count- the number of consecutive elements to be copied, starting at the given index- Returns:
- a
ResultSetobject containing the designated elements in thisSerialArrayobject, 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 aResultSetobject that contains all of the elements of the SQLARRAYvalue represented by thisSerialArrayobject. 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 methodgetResultSetuses either the given type map or the standard mapping; it never uses the type map associated with the connection.- Specified by:
getResultSetin interfaceArray- Parameters:
map- ajava.util.Mapobject in which each entry consists of 1) aStringobject giving the fully qualified name of a UDT and 2) theClassobject for theSQLDataimplementation that defines how the UDT is to be mapped- Returns:
- a
ResultSetobject containing all of the elements in thisSerialArrayobject, with a separate row for each element - Throws:
SerialException- if called with the cause set toUnsupportedOperationException
-
getResultSet
public ResultSet getResultSet() throws SerialException
Retrieves aResultSetobject that contains all of the elements in theARRAYvalue that thisSerialArrayobject represents. If appropriate, the elements of the array are mapped using the connection's type map; otherwise, the standard mapping is used.- Specified by:
getResultSetin interfaceArray- Returns:
- a
ResultSetobject containing all of the elements in thisSerialArrayobject, 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 aResultSetobject that contains a subarray of the elements in thisSerialArrayobject, 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 methodgetResultSetuses either the given type map or the standard mapping; it never uses the type map associated with the connection.- Specified by:
getResultSetin interfaceArray- Parameters:
index- the index into thisSerialArrayobject of the first element to be copied; the index of the first element in the array is0count- the number of consecutive elements to be copied, starting at the given indexmap- ajava.util.Mapobject in which each entry consists of 1) aStringobject giving the fully qualified name of a UDT and 2) theClassobject for theSQLDataimplementation that defines how the UDT is to be mapped- Returns:
- a
ResultSetobject containing the designated elements in thisSerialArrayobject, 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 istrueif and only if the argument is notnulland is aSerialArrayobject whose elements are identical to this object's elements- Overrides:
equalsin classObject- Parameters:
obj- The object to compare thisSerialArrayagainst- Returns:
trueif the given object represents aSerialArrayequivalent to this SerialArray,falseotherwise- See Also:
Object.hashCode(),HashMap
-
hashCode
public int hashCode()
Returns a hash code for this SerialArray. The hash code for aSerialArrayobject is computed using the hash codes of the elements of theSerialArrayobject- Overrides:
hashCodein 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 thisSerialArrayobject.
-
-