1. SODA for Java Developer's Guide
  2. SODA Collection Metadata Caching

4 SODA Collection Metadata Caching

SODA collection metadata is stored persistently in the database, just like collection data. It is fetched transparently when needed, to perform collection operations. Fetching metadata from the database carries a performance cost. You can cache collection metadata in clients, to improve performance by avoiding database access to retrieve the metadata.

These are the main use cases for collection metadata caching:

  • Listing the existing collections, then opening one or more of the collections listed.

  • Creating a collection, then opening it.

  • Reopening a collection.

In all of these cases, cached metadata can be used to open the collection.

A collection metadata cache can be shared by all of the OracleDatabase objects that are obtained from a given OracleRDBMSClient object, or it can be local to a single OracleDatabase object. Both kinds of caching are disabled by default.

If both local and shared caches are enabled for the same OracleDatabase object, entry lookup proceeds as follows:

  1. The local cache is checked for an entry pertaining to a given collection used by the database object.

  2. If not found in the local cache, the shared cache is checked for an entry for the collection.

  3. If an entry for the collection is found in neither cache then the database is accessed to try to obtain the its metadata.

Enabling Collection Metadata Caching

Collection metadata caching is disabled by default. You can use constructor OracleRDBMSClient(Properties props) to enable shared or local collection metadata caching.

Parameter props here is a Properties instance that you initialize with one or both of the following properties:

  • Property oracle.soda.sharedMetadataCache with value "true": enable the shared cache

  • Property oracle.soda.localMetadataCache with value "true": enable the local cache

Example 4-1 illustrates this; it enables both shared and local caching.

Example 4-1 Enabling Collection Metadata Caching

Properties props = new Properties();
props.put("oracle.soda.sharedMetadataCache", "true");
props.put("oracle.soda.localMetadataCache", "true");
OracleRDBMSClient cl = new OracleRDBMSClient(props);

Shared Collection Metadata Cache

Each SODA client (OracleRDBMSClient object) is optionally associated with a collection metadata cache that records metadata for all collections (OracleCollection objects) that are created for all OracleDatabase objects created from that client. The cache is released when its associated client is released.

The number of entries in a shared cache is limited to 10,000 entries (100 database schemas times 100 collections per schema). A shared cache uses a least-recently-used (LRU) replacement policy: the least recently used entry is replaced by the addition of a new entry, when the cache is full (it has 10,000 entries).

A shared metadata cache requires locking to avoid access conflict, which can affect performance negatively because it limits concurrency.

Local Collection Metadata Cache

Each OracleDatabase object is optionally associated with a local collection metadata cache. It records metadata only for collections that are created for that OracleDatabase object. A local cache is released when its associated OracleDatabase object is released.

There is no limit on the number of entries for a local cache — entries are never evicted. The number of entries continues to grow as new collections are created for the given database object.

The lack of an eviction policy for local metadata caches means that cached collection metadata is always available; once cached, the database need never be accessed to obtain it.

With local caching, because there is no sharing, using different database objects to access the same collection can result in more round trips and more data replication than is the case for shared caching.

Unlike a shared metadata cache, a local cache requires no locking.

Caution:

Because the number of entries in the local cache is unbounded, Oracle does not recommend using the local cache if a particular Oracle Database object is used to create a large number of collections, as it could result in running out of memory.