Oracle8i JDBC Developer's Guide and Reference Release 3 (8.1.7) Part Number A83724-01 |
Library | Service | Contents | Index

## ARRAY Performance Extension Methods

This section discusses the following topics:

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

- ARRAY Automatic Element Buffering

- ARRAY Automatic Indexing

### 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.

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index