Working with Oracle Collections

ARRAY Performance Extension Methods

This section discusses the following topics:

Accessing oracle.sql.ARRAY Elements as Arrays of Java Primitive Types

The oracle.sql.ARRAY class contains methods that return array elements as Java primitive types. These methods allow you to access collection elements more efficiently than accessing them as Datum instances and then converting each Datum instance to its Java primitive value.

Note:
These specialized methods of the oracle.sql.ARRAY class are restricted to numeric collections.

Here are the methods:

public int[] getIntArray()throws SQLException

public int[] getIntArray(long index, int count) throws SQLException
public long[] getLongArray()throws SQLException

public long[] getLongArray(long index, int count) throws SQLException
public float[] getFloatArray()throws SQLException

public float[] getFloatArray(long index, int count) throws SQLException
public double[] getDoubleArray()throws SQLException

public double[] getDoubleArray(long index, int count) throws SQLException
public short[] getShortArray()throws SQLException

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

Each method using the first signature returns collection elements as an XXX[], where XXX is a Java primitive type. Each method using the second signature returns a slice of the collection containing the number of elements specified by count, starting at the index location.

ARRAY Automatic Element Buffering

The Oracle JDBC driver provides public methods to enable and disable buffering of ARRAY contents. (See "STRUCT Automatic Attribute Buffering" for a discussion of how to buffer STRUCT attributes.)

The following methods are included with the oracle.sql.ARRAY class:

public void setAutoBuffering(boolean enable)
public boolean getAutoBuffering()

The setAutoBuffering() method enables or disables auto-buffering. The getAutoBuffering() method returns the current auto-buffering mode. By default, auto-buffering is disabled.

It is advisable to enable auto-buffering in a JDBC application when the ARRAY elements will be accessed more than once by the getAttributes() and getArray() methods (presuming the ARRAY data is able to fit into the JVM memory without overflow).

Important:
Buffering the converted elements may cause the JDBC application to consume a significant amount of memory.

When you enable auto-buffering, the oracle.sql.ARRAY object keeps a local copy of all the converted elements. This data is retained so that a second access of this information does not require going through the data format conversion process.

ARRAY Automatic Indexing

If an array is in auto-indexing mode, the array object maintains an index table to hasten array element access.

The oracle.sql.ARRAY class contains the following methods to support automatic array-indexing:

public synchronized void setAutoIndexing (boolean enable, int direction) throws SQLException
public synchronized void setAutoIndexing (boolean enable) throws SQLException

The setAutoIndexing() method sets the auto-indexing mode for the oracle.sql.ARRAY object. The direction parameter gives the array object a hint: specify this parameter to help the JDBC driver determine the best indexing scheme. The following are the values you can specify for the direction parameter:

ARRAY.ACCESS_FORWARD
ARRAY.ACCESS_REVERSE
ARRAY.ACCESS_UNKNOWN

The setAutoIndexing(boolean) method signature sets the access direction as ARRAY.ACCESS_UNKNOWN by default.

By default, auto-indexing is not enabled. For a JDBC application, enable auto-indexing for ARRAY objects if random access of array elements may occur through the getArray() and getResultSet() methods.