Oracle JDBC API Reference
11g Release 2 ("11.2.0.3.0")

oracle.sql
Class ARRAY

java.lang.Object
  extended by oracle.sql.Datum
      extended by oracle.sql.DatumWithConnection
          extended by 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.

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

Oracle JDBC API Reference
11g Release 2 ("11.2.0.3.0")

Copyright © 1998, 2007, Oracle. All rights reserved.