oracle.sql
Class ARRAY

java.lang.Object
  oracle.sql.Datum
      oracle.sql.DatumWithConnection
          oracle.sql.ARRAY

All Implemented Interfaces:

java.io.Serializable, java.sql.Array, oracle.jdbc.internal.OracleDatumWithConnection, OracleArray

public class ARRAY
extends DatumWithConnection
implements oracle.jdbc.internal.OracleArray

This class has two roles.

• It is the Oracle implementation class for the generic JDBC Array interface.
• It wraps the "raw bytes" of an Oracle Collection.

Like other classes in oracle.sql. it is a value class. That is, once it is constructed the user should not change its contents. The type of the array elements is called the "Base Type" An Oracle implementation for generic JDBC Array interface.

See Also:

Serialized Form

Field Summary

static int	ACCESS_FORWARD
static int	ACCESS_REVERSE
static int	ACCESS_UNKNOWN
static java.lang.String	BUILD_DATE
static boolean	TRACE

Constructor Summary

ARRAY(ArrayDescriptor type, java.sql.Connection conn, java.lang.Object elements)
Constructor.

Method Summary

java.lang.String	dump() Create a string which show the contents of this Array and of all its component parts.
int	getAccessDirection() Performance hint.
java.lang.Object	getArray() Implements Array interface method Retrieve the contents of the SQL array designated by the object.
java.lang.Object	getArray(long index, int count) Implements Array interface method Like getArray() above, but returns an array containing a slice of the SQL array, beginning with the given index and containing up to count successive elements of the SQL array.
java.lang.Object	getArray(long index, int count, java.util.Map map) Implements Array interface method Like getArray() above, but returns an array containing a slice of the SQL array, beginning with the given index and containing up to count successive elements of the SQL array.
java.lang.Object	getArray(java.util.Map map) Implements Array interface method Retrieve the contents of the SQL array designated by this object.
boolean	getAutoBuffering() Performance hint.
boolean	getAutoIndexing() Performance hint.
int	getBaseType() Implements Array interface method Determine the code, from java.sql.Types, of the type of the elements of the array.
java.lang.String	getBaseTypeName() Implements Array interface method Returns the SQL type name of the elements in the array designated by this Array object.
ArrayDescriptor	getDescriptor() Oracle extension.
double[]	getDoubleArray() Oracle extension.
double[]	getDoubleArray(long index, int count) Oracle extension.
float[]	getFloatArray() Oracle extension.
float[]	getFloatArray(long index, int count) Oracle extension.
int[]	getIntArray() Oracle extension.
int[]	getIntArray(long index, int count) Oracle extension.
long[]	getLongArray() Oracle extension.
long[]	getLongArray(long index, int count) Oracle extension.
Datum[]	getOracleArray() Oracle extension.
Datum[]	getOracleArray(long index, int count) Oracle extension.
OracleTypeMetaData	getOracleMetaData() Return the type data for this object
java.sql.ResultSet	getResultSet() Implements Array interface method Returns a result set that contains the elements of the array designated by this Array object.
java.sql.ResultSet	getResultSet(long index, int count) Implements Array interface method Returns a result set holding the elements of the subarray that starts at index index and contains up to count successive elements.
java.sql.ResultSet	getResultSet(long index, int count, java.util.Map map) Implements Array interface method Returns a result set holding the elements of the subarray that starts at index index and contains up to count successive elements.
java.sql.ResultSet	getResultSet(java.util.Map map) Implements Array interface method Returns a result set that contains the elements of the array designated by this Array object and uses the given map to map the array elements.
short[]	getShortArray() Oracle extension.
short[]	getShortArray(long index, int count)
java.lang.String	getSQLTypeName() Oracle extension.
boolean	isConvertibleTo(java.lang.Class jClass) Oracle extension.
int	length() Oracle extension.
void	setAutoBuffering(boolean enable) Performance hint.
void	setAutoIndexing(boolean enable) Performance hint.
void	setAutoIndexing(boolean enable, int direction) Performance hint.
java.lang.String	stringValue() Convert to a String representation of the datum object
java.lang.Object	toJdbc() Oracle extension.

Methods inherited from class oracle.sql.DatumWithConnection

assertNotNull, assertNotNull, getConnection, getJavaSqlConnection, getOracleConnection

Methods inherited from class oracle.sql.Datum

asciiStreamValue, bigDecimalValue, binaryStreamValue, booleanValue, byteValue, characterStreamValue, dateValue, doubleValue, equals, floatValue, getBytes, getLength, getStream, intValue, longValue, setBytes, setShareBytes, shareBytes, stringValue, timestampValue, timestampValue, timeValue, timeValue

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface oracle.jdbc.internal.OracleDatumWithConnection

asciiStreamValue, bigDecimalValue, binaryStreamValue, booleanValue, byteValue, characterStreamValue, dateValue, doubleValue, floatValue, getBytes, getConnection, getInternalConnection, getJavaSqlConnection, getLength, getOracleConnection, getStream, intValue, longValue, setBytes, setPhysicalConnectionOf, setShareBytes, shareBytes, stringValue, timestampValue, timestampValue, timeValue, timeValue

Field Detail

ACCESS_FORWARD

public static final int ACCESS_FORWARD

See Also:

Constant Field Values

ACCESS_REVERSE

public static final int ACCESS_REVERSE

See Also:

Constant Field Values

ACCESS_UNKNOWN

public static final int ACCESS_UNKNOWN

See Also:

Constant Field Values

BUILD_DATE

public static final java.lang.String BUILD_DATE

See Also:

Constant Field Values

TRACE

public static final boolean TRACE

See Also:

Constant Field Values

Constructor Detail

ARRAY

public ARRAY(ArrayDescriptor type,
             java.sql.Connection conn,
             java.lang.Object elements)
      throws java.sql.SQLException

Constructor.

Parameters:

type - an ArrayDescriptor describing the SQL Type

elements - the contents of the array. These objects will be converted to raw bytes of the appropriate SQL Type

Throws:

java.sql.SQLException

Method Detail

getBaseTypeName

public java.lang.String getBaseTypeName()
                                 throws java.sql.SQLException

Implements Array interface method Returns the SQL type name of the elements in the array designated by this Array object. If the elements are a built-in type, it returns the database-specific type name of the elements. If the elements are a user-defined type (UDT), this method returns the fully-qualified SQL type name.

Specified by:

getBaseTypeName in interface java.sql.Array

Returns:

a String that is the database-specific name for a built-in base type or the fully-qualified SQL type name for a base type that is a UDT

Throws:

java.sql.SQLException - if an error occurs while attempting to access the type name

getBaseType

public int getBaseType()
                throws java.sql.SQLException

Implements Array interface method Determine the code, from java.sql.Types, of the type of the elements of the array.

Specified by:

getBaseType in interface java.sql.Array

Returns:

the type code of the elements of the array.

Throws:

java.sql.SQLException

See Also:

Types, OracleTypes

getArray

public java.lang.Object getArray()
                          throws java.sql.SQLException

Implements Array interface method Retrieve the contents of the SQL array designated by the object. Use the type-map associated with the connection for customizations of the type-mappings.

Specified by:

getArray in interface java.sql.Array

Returns:

a Java array containing the ordered elements of the SQL array designated by this object.

Throws:

java.sql.SQLException

getArray

public java.lang.Object getArray(java.util.Map map)
                          throws java.sql.SQLException

Implements Array interface method Retrieve the contents of the SQL array designated by this object. Use the given map for type-map customizations.

Specified by:

getArray in interface java.sql.Array

Parameters:

map - contains mapping of SQL type names to Java classes

Returns:

a Java array containing the ordered elements of the SQL array designated by this object.

Throws:

java.sql.SQLException

getArray

public java.lang.Object getArray(long index,
                                 int count)
                          throws java.sql.SQLException

Implements Array interface method Like getArray() above, but returns an array containing a slice of the SQL array, beginning with the given index and containing up to count successive elements of the SQL array. Use the type-map associated with the connection for customizations of the type-mappings.

Specified by:

getArray in interface java.sql.Array

Parameters:

index - the array-index of the first element to retrieve

count - the number of successive SQL array elements to retrieve

Returns:

an array containing up to count elements of the SQL array, beginning with element index.

Throws:

java.sql.SQLException

getArray

public java.lang.Object getArray(long index,
                                 int count,
                                 java.util.Map map)
                          throws java.sql.SQLException

Implements Array interface method Like getArray() above, but returns an array containing a slice of the SQL array, beginning with the given index and containing up to count successive elements of the SQL array. Use the given map for type-map customizations.

Specified by:

getArray in interface java.sql.Array

Parameters:

index - the array-index of the first element to retrieve

count - the number of successive SQL array elements to retrieve

map - contains mapping of SQL user-defined types to classes

Returns:

an array containing up to count elements of the SQL array, beginning with element index.

Throws:

java.sql.SQLException

getResultSet

public java.sql.ResultSet getResultSet()
                                throws java.sql.SQLException

Implements Array interface method Returns a result set that contains the elements of the array designated by this Array object. If appropriate, the elements of the array are mapped using the connection's type map; otherwise, the standard mapping is used.

The result set contains one row for each array element, with two columns in each row. The second column stores the element value; the first column stores the index into the array for that element (with the first array element being at index 1). The rows are in ascending order corresponding to the order of the indices.

Specified by:

getResultSet in interface java.sql.Array

Returns:

a ResultSet object containing one row for each of the elements in the array designated by this Array object, with the rows in ascending order based on the indices.

Throws:

java.sql.SQLException - if an error occurs while attempting to access the array

getResultSet

public java.sql.ResultSet getResultSet(java.util.Map map)
                                throws java.sql.SQLException

Implements Array interface method Returns a result set that contains the elements of the array designated by this Array object and uses the given map to map the array elements. If the base type of the array does not match a user-defined type in map, the standard mapping is used instead.

The result set contains one row for each array element, with two columns in each row. The second column stores the element value; the first column stores the index into the array for that element (with the first array element being at index 1). The rows are in ascending order corresponding to the order of the indices.

Specified by:

getResultSet in interface java.sql.Array

Parameters:

map - contains mapping of SQL user-defined types to classes in the Java(tm) programming language

Returns:

a ResultSet object containing one row for each of the elements in the array designated by this Array object, with the rows in ascending order based on the indices.

Throws:

java.sql.SQLException - if an error occurs while attempting to access the array

getResultSet

public java.sql.ResultSet getResultSet(long index,
                                       int count)
                                throws java.sql.SQLException

Implements Array interface method Returns a result set 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.

The result set has one row for each element of the SQL array designated by this object, with the first row containing the element at index index. The result set has up to count rows in ascending order based on the indices. Each row has two columns: The second column stores the element value; the first column stroes the index into the array for that element.

Specified by:

getResultSet in interface java.sql.Array

Parameters:

index - the array index of the first element to retrieve; the first element is at index 1

count - the number of successive SQL array elements to retrieve

Returns:

a ResultSet object containing up to count consecutive elements of the SQL array designated by this Array object, starting at index index.

Throws:

java.sql.SQLException - if an error occurs while attempting to access the array

getResultSet

public java.sql.ResultSet getResultSet(long index,
                                       int count,
                                       java.util.Map map)
                                throws java.sql.SQLException

Implements Array interface method Returns a result set holding the elements of the subarray that starts at index index and contains up to count successive elements. This method uses the Map object map to map the elements of the array unless the base type of the array does not match a user-defined type in map, in which case it uses the standard mapping.

The result set has one row for each element of the SQL array designated by this object, with the first row containing the element at index index. The result set has up to count rows in ascending order based on the indices. Each row has two columns: The second column stores the element value; the first column stroes the index into the array for that element.

Specified by:

getResultSet in interface java.sql.Array

Parameters:

index - the array index of the first element to retrieve; the first element is at index 1

count - the number of successive SQL array elements to retrieve

map - the Map object that contains the mapping of SQL type names to classes in the Java(tm) programming language

Returns:

a ResultSet object containing up to count consecutive elements of the SQL array designated by this Array object, starting at index index.

Throws:

java.sql.SQLException - if an error occurs while attempting to access the array

getOracleArray

public Datum[] getOracleArray()
                       throws java.sql.SQLException

Oracle extension. Analogous to getArray except that it always returns an oracle.sql.XXX instead of whatever result.getObject would have returned.

Returns:

an array of Datum.

Throws:

java.sql.SQLException

length

public int length()
           throws java.sql.SQLException

Oracle extension. Get array size.

Specified by:

length in interface OracleArray

Returns:

the number of elements in the array.

Throws:

java.sql.SQLException

getOracleArray

public Datum[] getOracleArray(long index,
                              int count)
                       throws java.sql.SQLException

Oracle extension. Like getOracleArray, but returns a slice.

Parameters:

index - the index of the first element to be returned

count - the number of elements to be returned.

Returns:

an array containing count elements starting at index

Throws:

java.sql.SQLException

getSQLTypeName

public java.lang.String getSQLTypeName()
                                throws java.sql.SQLException

Oracle extension. Retrieves the SQL type name of the SQL structured type that this Struct object represents.

Specified by:

getSQLTypeName in interface OracleArray

Throws:

java.sql.SQLException - if a database access error occurs

getOracleMetaData

public OracleTypeMetaData getOracleMetaData()
                                     throws java.sql.SQLException

Return the type data for this object

Specified by:

getOracleMetaData in interface OracleArray

Returns:

type metadata

Throws:

java.sql.SQLException - if an error occurs

Since:

11.2.0.3.0

getDescriptor

public ArrayDescriptor getDescriptor()
                              throws java.sql.SQLException

Oracle extension. Return the ArrayDescriptor object that contains the type information.

Returns:

the type descriptor

Throws:

java.sql.SQLException

toJdbc

public java.lang.Object toJdbc()
                        throws java.sql.SQLException

Oracle extension. Returns the JDBC representation of the datum object

Specified by:

toJdbc in interface oracle.jdbc.internal.OracleDatumWithConnection

Specified by:

toJdbc in interface OracleArray

Specified by:

toJdbc in class Datum

Returns:

an object containing the JDBC value

Throws:

java.sql.SQLException - if conversion to JDBC representation results in an error

isConvertibleTo

public boolean isConvertibleTo(java.lang.Class jClass)

Oracle extension. Determines if datum object can be converted to a particular class

Specified by:

isConvertibleTo in interface oracle.jdbc.internal.OracleDatumWithConnection

Specified by:

isConvertibleTo in class Datum

Parameters:

jClass - Class to convert to

Returns:

true, if conversion to cls is permitted false, if conversion to cls is not permitted

getIntArray

public int[] getIntArray()
                  throws java.sql.SQLException

Oracle extension. Analogous to getArray except that it always returns a int[].

Specified by:

getIntArray in interface OracleArray

Returns:

an array of int.

Throws:

java.sql.SQLException

getIntArray

public int[] getIntArray(long index,
                         int count)
                  throws java.sql.SQLException

Oracle extension. Like getIntArray, but returns a slice.

Specified by:

getIntArray in interface OracleArray

Parameters:

index - the index of the first element to be returned

count - the number of elements to be returned.

Returns:

an array containing count elements starting at index

Throws:

java.sql.SQLException

getDoubleArray

public double[] getDoubleArray()
                        throws java.sql.SQLException

Oracle extension. Analogous to getArray except that it always returns a double[].

Specified by:

getDoubleArray in interface OracleArray

Returns:

an array of double.

Throws:

java.sql.SQLException

getDoubleArray

public double[] getDoubleArray(long index,
                               int count)
                        throws java.sql.SQLException

Oracle extension. Like getDoubleArray, but returns a slice.

Specified by:

getDoubleArray in interface OracleArray

Parameters:

index - the index of the first element to be returned

count - the number of elements to be returned.

Returns:

an array containing count elements starting at index

Throws:

java.sql.SQLException

getShortArray

public short[] getShortArray()
                      throws java.sql.SQLException

Oracle extension. Analogous to getArray except that it always returns a short[].

Specified by:

getShortArray in interface OracleArray

Returns:

an array of short.

Throws:

java.sql.SQLException

getShortArray

public short[] getShortArray(long index,
                             int count)
                      throws java.sql.SQLException

Specified by:

getShortArray in interface OracleArray

Throws:

java.sql.SQLException

getLongArray

public long[] getLongArray()
                    throws java.sql.SQLException

Oracle extension. Analogous to getArray except that it always returns a long[].

Specified by:

getLongArray in interface OracleArray

Returns:

an array of long.

Throws:

java.sql.SQLException

getLongArray

public long[] getLongArray(long index,
                           int count)
                    throws java.sql.SQLException

Oracle extension. Like getLongArray, but returns a slice.

Specified by:

getLongArray in interface OracleArray

Parameters:

index - the index of the first element to be returned

count - the number of elements to be returned.

Returns:

an array containing count elements starting at index

Throws:

java.sql.SQLException

getFloatArray

public float[] getFloatArray()
                      throws java.sql.SQLException

Oracle extension. Analogous to getArray except that it always returns a float[].

Specified by:

getFloatArray in interface OracleArray

Returns:

an array of float.

Throws:

java.sql.SQLException

getFloatArray

public float[] getFloatArray(long index,
                             int count)
                      throws java.sql.SQLException

Oracle extension. Like getFloatArray, but returns a slice.

Specified by:

getFloatArray in interface OracleArray

Parameters:

index - the index of the first element to be returned

count - the number of elements to be returned.

Returns:

an array containing count elements starting at index

Throws:

java.sql.SQLException

setAutoBuffering

public void setAutoBuffering(boolean enable)
                      throws java.sql.SQLException

Performance hint. Sets this array's auto-buffering mode. If a array is in auto-buffering mode, then the array will keep a local copy of all its elements. Then the next access to the same elements will return a cloned copy. Otherwise, type conversion for each element is required. By default, a ARRAY is NOT in auto-buffering mode.

Parameters:

enable - - true enables auto-buffering; false disables auto-buffering

Throws:

java.sql.SQLException

Since:

8.1.7

See Also:

getAutoBuffering()

getAutoBuffering

public boolean getAutoBuffering()
                         throws java.sql.SQLException

Performance hint. Get the current auto-buffering state.

Returns:

the current state of auto-buffering

Throws:

java.sql.SQLException

Since:

8.1.7

See Also:

setAutoBuffering(boolean)

setAutoIndexing

public void setAutoIndexing(boolean enable,
                            int direction)
                     throws java.sql.SQLException

Performance hint. Sets this array's auto-indexing mode. If a array is in auto-indexing mode, then the array will maintain a index table for array elements to fasten repeatedly access to the same elements or different elementes in the ARRAY. The second argument gives this array a hint as to the direction in which the elements will be accessed. Available direction values are ARRAY.ACCESS_FORWARD, ARRAY.ACCESS_REVERSE, and ARRAY.ACCESS_UNKNOWN.

Parameters:

enable - - true enables auto-indexing; false disables auto-indexing

direction - - overwrite default access direction.

Throws:

java.sql.SQLException

Since:

8.1.7

setAutoIndexing

public void setAutoIndexing(boolean enable)
                     throws java.sql.SQLException

Performance hint. Sets this array's auto-indexing mode. If a array is in auto-indexing mode, then the array will maintain a index table for array elements to fasten repeatedly access to the same elements or different elementes in the ARRAY. By default, access direction is set to ARRAY.ACCESS_UNKNOWN.

Parameters:

enable - - true enables auto-indexing; false disables auto-indexing

Throws:

java.sql.SQLException

Since:

8.1.7

getAutoIndexing

public boolean getAutoIndexing()
                        throws java.sql.SQLException

Performance hint. Get the current auto-indexing state.

Returns:

the current state of auto-indexing

Throws:

java.sql.SQLException

Since:

8.1.7

See Also:

oracle.sql.ARRAY#setAutoIndexinging(boolean), oracle.sql.ARRAY#setAutoIndexinging(boolean, int)

getAccessDirection

public int getAccessDirection()
                       throws java.sql.SQLException

Performance hint. Get the access direction value.

Returns:

the current access direction

Throws:

java.sql.SQLException

Since:

8.1.7

See Also:

oracle.sql.ARRAY#setAutoIndexinging(boolean), oracle.sql.ARRAY#setAutoIndexinging(boolean, int)

dump

public java.lang.String dump()
                      throws java.sql.SQLException

Create a string which show the contents of this Array and of all its component parts.

Throws:

java.sql.SQLException

stringValue

public java.lang.String stringValue()
                             throws java.sql.SQLException

Description copied from class: Datum

Convert to a String representation of the datum object

Specified by:

stringValue in interface oracle.jdbc.internal.OracleDatumWithConnection

Overrides:

stringValue in class Datum

Returns:

String representation of the datum object

Throws:

java.sql.SQLException