APIdia Launch Partner
Top Description Fields Constructors Methods
javax.sql.rowset.serial

public Class SerialArray

extends Object
implements Array, Serializable, Cloneable
Class Inheritance
All Implemented Interfaces
java.lang.Cloneable, java.io.Serializable, java.sql.Array, java.lang.AutoCloseable
Imports
java.sql.*, java.io.*, java.util.Map, .Arrays, java.net.URL
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.
Since
1.5

Field Summary

Modifier and TypeField and Description
private int
baseType

The SQL type of the elements in this SerialArray object.

private String
baseTypeName

The type name used by the DBMS for the elements in the SQL ARRAY value that this SerialArray object represents.

private Object[]
elements

A serialized array in which each element is an Object in the Java programming language that represents an element in the SQL ARRAY value.

private int
len

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.

pack-priv static final long
serialVersionUID

The identifier that assists in the serialization of this SerialArray object.

Constructor Summary

AccessConstructor and Description
public
SerialArray(Array
the Array object to be serialized
array, Map<String, Class<?>>
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.
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.

public
SerialArray(Array
the Array object to be serialized
array)

Constructs a new SerialArray object from the given Array object.

Method Summary

Modifier and TypeMethod and Description
public Object

Returns:

a clone of this SerialArray
clone()

Overrides java.lang.Object.clone.

Returns a clone of this SerialArray.

public boolean

Returns:

true if the given object represents a SerialArray equivalent to this SerialArray, false otherwise
equals(Object
The object to compare this SerialArray against
obj)

Overrides java.lang.Object.equals.

Compares this SerialArray to the specified object.

public void
free()

Implements java.sql.Array.free.

This method frees the SerialArray object and releases the resources that it holds.

public Object

Returns:

a copy of this SerialArray object as an Object in the Java programming language
getArray()

Implements java.sql.Array.getArray.

Returns a new array that is a copy of this SerialArray object.

public Object

Returns:

a copy of this SerialArray object as an Object in the Java programming language
getArray(Map<String, Class<?>>
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
map)

Implements java.sql.Array.getArray.

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.

public Object

Returns:

a copy of the designated elements in this SerialArray object as an Object in the Java programming language
getArray(long
the index into this SerialArray object of the first element to be copied; the index of the first element is 0
index, int
the number of consecutive elements to be copied, starting at the given index
count)

Implements java.sql.Array.getArray.

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.

public Object

Returns:

a copy of the designated elements in this SerialArray object as an Object in the Java programming language
getArray(long
the index into this SerialArray object of the first element to be copied; the index of the first element in the array is 0
index, int
the number of consecutive elements to be copied, starting at the given index
count, Map<String, Class<?>>
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
map)

Implements java.sql.Array.getArray.

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.

public int

Returns:

one of the constants in java.sql.Types, indicating the SQL type of the elements in this SerialArray object
getBaseType()

Implements java.sql.Array.getBaseType.

Retrieves the SQL type of the elements in this SerialArray object.

public String

Returns:

the SQL type name used by the DBMS for the base type of this SerialArray object
getBaseTypeName()

Implements java.sql.Array.getBaseTypeName.

Retrieves the DBMS-specific type name for the elements in this SerialArray object.

public ResultSet

Returns:

a ResultSet object containing the designated elements in this SerialArray object, with a separate row for each element
getResultSet(long
the index into this SerialArray object of the first element to be copied; the index of the first element in the array is 0
index, int
the number of consecutive elements to be copied, starting at the given index
count)

Implements java.sql.Array.getResultSet.

Retrieves a ResultSet object holding the elements of the subarray that starts at index index and contains up to count successive elements.

public ResultSet

Returns:

a ResultSet object containing all of the elements in this SerialArray object, with a separate row for each element
getResultSet(Map<String, Class<?>>
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
map)

Implements java.sql.Array.getResultSet.

Retrieves a ResultSet object that contains all of the elements of the SQL ARRAY value represented by this SerialArray object.

public ResultSet

Returns:

a ResultSet object containing all of the elements in this SerialArray object, with a separate row for each element
getResultSet()

Implements java.sql.Array.getResultSet.

Retrieves a ResultSet object that contains all of the elements in the ARRAY value that this SerialArray object represents.

public ResultSet

Returns:

a ResultSet object containing the designated elements in this SerialArray object, with a separate row for each element
getResultSet(long
the index into this SerialArray object of the first element to be copied; the index of the first element in the array is 0
index, int
the number of consecutive elements to be copied, starting at the given index
count, Map<String, Class<?>>
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
map)

Implements java.sql.Array.getResultSet.

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.

public int

Returns:

a hash code value for this object.
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code for this SerialArray.

private void
isValid()

Check to see if this object had previously had its free method called

private void
readObject(ObjectInputStream
the ObjectInputStream to read from.
s)

readObject is called to restore the state of the SerialArray from a stream.

private void
writeObject(ObjectOutputStream
the ObjectOutputStream to write to.
s)

writeObject is called to save the state of the SerialArray to a stream.

Inherited from java.lang.Object:
finalizegetClassnotifynotifyAlltoStringwaitwaitwait

Field Detail

baseTypeback to summary
private int baseType

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.

baseTypeNameback to summary
private String baseTypeName

The type name used by the DBMS for the elements in the SQL ARRAY value that this SerialArray object represents.

elementsback to summary
private Object[] elements

A serialized array in which each element is an Object in the Java programming language that represents an element in the SQL ARRAY value.

Annotations
@SuppressWarnings:serial
lenback to summary
private int len

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.

serialVersionUIDback to summary
pack-priv static final long serialVersionUID

The identifier that assists in the serialization of this SerialArray object.

Constructor Detail

SerialArrayback to summary
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.

Parameters
array:Array

the Array object to be serialized

map:Map<String, Class<?>>

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.

Exceptions
SerialException:
if an error occurs serializing the Array object
SQLException:
if a database access error occurs or if the array or the map values are null
SerialArrayback to summary
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.

Parameters
array:Array

the Array object to be serialized

Exceptions
SerialException:
if an error occurs serializing the Array object
SQLException:
if a database access error occurs or the array parameter is null.

Method Detail

cloneback to summary
public Object clone()

Overrides java.lang.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.

Returns:Object

a clone of this SerialArray

equalsback to summary
public boolean equals(Object obj)

Overrides java.lang.Object.equals.

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

Parameters
obj:Object

The object to compare this SerialArray against

Returns:boolean

true if the given object represents a SerialArray equivalent to this SerialArray, false otherwise

freeback to summary
public void free() throws SQLException

Implements java.sql.Array.free.

This method frees the SerialArray 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.

Exceptions
SQLException:
if an error occurs releasing the SerialArray's resources
Since
1.6
getArrayback to summary
public Object getArray() throws SerialException

Implements java.sql.Array.getArray.

Returns a new array that is a copy of this SerialArray object.

Returns:Object

a copy of this SerialArray object as an Object in the Java programming language

Exceptions
SerialException:
if an error occurs; if free had previously been called on this object
getArrayback to summary
public Object getArray(Map<String, Class<?>> map) throws SerialException

Implements java.sql.Array.getArray.

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.

Parameters
map:Map<String, Class<?>>

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

Returns:Object

a copy of this SerialArray object as an Object in the Java programming language

Exceptions
SerialException:
if an error occurs; if free had previously been called on this object
getArrayback to summary
public Object getArray(long index, int count) throws SerialException

Implements java.sql.Array.getArray.

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.

Parameters
index:long

the index into this SerialArray object of the first element to be copied; the index of the first element is 0

count:int

the number of consecutive elements to be copied, starting at the given index

Returns:Object

a copy of the designated elements in this SerialArray object as an Object in the Java programming language

Exceptions
SerialException:
if an error occurs; if free had previously been called on this object
getArrayback to summary
public Object getArray(long index, int count, Map<String, Class<?>> map) throws SerialException

Implements java.sql.Array.getArray.

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.

Parameters
index:long

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:int

the number of consecutive elements to be copied, starting at the given index

map:Map<String, Class<?>>

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

Returns:Object

a copy of the designated elements in this SerialArray object as an Object in the Java programming language

Exceptions
SerialException:
if an error occurs; if free had previously been called on this object
getBaseTypeback to summary
public int getBaseType() throws SerialException

Implements java.sql.Array.getBaseType.

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.

Returns:int

one of the constants in java.sql.Types, indicating the SQL type of the elements in this SerialArray object

Exceptions
SerialException:
if an error occurs; if free had previously been called on this object
getBaseTypeNameback to summary
public String getBaseTypeName() throws SerialException

Implements java.sql.Array.getBaseTypeName.

Retrieves the DBMS-specific type name for the elements in this SerialArray object.

Returns:String

the SQL type name used by the DBMS for the base type of this SerialArray object

Exceptions
SerialException:
if an error occurs; if free had previously been called on this object
getResultSetback to summary
public ResultSet getResultSet(long index, int count) throws SerialException

Implements java.sql.Array.getResultSet.

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.

Parameters
index:long

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:int

the number of consecutive elements to be copied, starting at the given index

Returns:ResultSet

a ResultSet object containing the designated elements in this SerialArray object, with a separate row for each element

Exceptions
SerialException:
if called with the cause set to UnsupportedOperationException
getResultSetback to summary
public ResultSet getResultSet(Map<String, Class<?>> map) throws SerialException

Implements java.sql.Array.getResultSet.

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.

Parameters
map:Map<String, Class<?>>

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

Returns:ResultSet

a ResultSet object containing all of the elements in this SerialArray object, with a separate row for each element

Exceptions
SerialException:
if called with the cause set to UnsupportedOperationException
getResultSetback to summary
public ResultSet getResultSet() throws SerialException

Implements java.sql.Array.getResultSet.

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.

Returns:ResultSet

a ResultSet object containing all of the elements in this SerialArray object, with a separate row for each element

Exceptions
SerialException:
if called with the cause set to UnsupportedOperationException
getResultSetback to summary
public ResultSet getResultSet(long index, int count, Map<String, Class<?>> map) throws SerialException

Implements java.sql.Array.getResultSet.

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.

Parameters
index:long

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:int

the number of consecutive elements to be copied, starting at the given index

map:Map<String, Class<?>>

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

Returns:ResultSet

a ResultSet object containing the designated elements in this SerialArray object, with a separate row for each element

Exceptions
SerialException:
if called with the cause set to UnsupportedOperationException
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.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

Returns:int

a hash code value for this object.

isValidback to summary
private void isValid() throws SerialException

Check to see if this object had previously had its free method called

readObjectback to summary
private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException

readObject is called to restore the state of the SerialArray from a stream.

Parameters
s:ObjectInputStream

the ObjectInputStream to read from.

Exceptions
IOException:
if an I/O error occurs.
ClassNotFoundException:
if the class of a serialized object could not be found.
writeObjectback to summary
private void writeObject(ObjectOutputStream s) throws IOException

writeObject is called to save the state of the SerialArray to a stream.

Parameters
s:ObjectOutputStream

the ObjectOutputStream to write to.

Exceptions
IOException:
if an I/O error occurs.