Coherence 3.3 User Guide : Sample Cache Configurations

This page provides a series of simple cache scheme configurations. The samples build upon one another and will often utilize a scheme-ref element to reuse other samples as nested schemes. Cache schemes are specified in the caching-schemes element of the cache configuration descriptor. These samples only specify a minimum number of settings, follow the embedded links to the scheme's documentation to see the full set of options.

Local caches

This section defines a series of local cache schemes. In this context "local" means that the cache is only directly accessible by a single JVM. Later in this document local caches will be used as building blocks for clustered caches.

In-memory cache

This sample uses a local-scheme to define an in-memory cache. The cache will store as much as the JVM heap will allow.

<local-scheme>
   <scheme-name>SampleMemoryScheme</scheme-name>
</local-scheme>

NIO in-memory cache

This sample uses an external-scheme to define an in-memory cache using an nio-memory-manager. The advantage of an NIO memory based cache is that it allows for large in-memory cache storage while not negatively impacting the JVM's GC times. The size of the cache is limited by the maximum size of the NIO memory region.

<external-scheme>
  <scheme-name>SampleNioMemoryScheme</scheme-name>
  <nio-memory-manager/>
</external-scheme>

Size limited in-memory cache

Adding a high-units element to the local-scheme limits the size of the cache. Here the cache is size limited to one thousand entries. Once the limit is exceeded, the scheme's eviction policy will determine which elements to evict from the cache.

<local-scheme>
   <scheme-name>SampleMemoryLimitedScheme</scheme-name>
   <high-units>1000</high-units>
</local-scheme>

In-memory cache with expiring entries

Adding a expiry-delay element to the local-scheme will cause cache entries to automatically expire, if they are not updated for a given time interval. Once expired the cache will invalidate the entry, and remove it from the cache.

<local-scheme>
   <scheme-name>SampleMemoryExpirationScheme</scheme-name>
   <expiry-delay>5m</expiry-delay>
</local-scheme>

Cache on disk

This sample uses an external-scheme to define an on-disk cache. The cache will store as much as the file system will allow.

This example uses the lh-file-manager for its on-disk storage implementation. See the external-scheme documentation for additional external storage options.

<external-scheme>
  <scheme-name>SampleDiskScheme</scheme-name>
  <lh-file-manager/>
</external-scheme>

Size limited cache on disk

Adding a [high-units|local-cache#high-units element to external-scheme limits the size of the cache. The cache is size limited to one million entries. Once the limit is exceeded, LRU eviction is used determine which elements to evict from the cache. Refer to the paged-external-scheme for an alternate size limited external caching approach.

<external-scheme>
  <scheme-name>SampleDiskLimitedScheme</scheme-name>
  <lh-file-manager/>
  <high-units>1000000</high-units>
</external-scheme>

Persistent cache on disk

This sample uses an external-scheme to implement a cache suitable for use as long-term storage for a single JVM.

External caches are generally used for temporary storage of large data sets, and are automatically deleted on JVM shutdown. An external-cache can be used for long-term storage in non-clustered caches when using either the lh-file-manager or bdb-store-manager storage managers. For clustered persistence see the "Partitioned cache of a database" sample.

The {cache-name} macro is used to specify the name of the file the data will be stored in.

<external-scheme>
  <scheme-name>SampleDiskPersistentScheme</scheme-name>
  <lh-file-manager>
    <directory>/my/storage/directory</directory>
    <file-name>{cache-name}.store</file-name>
  </lh-file-manager>
</external-scheme>

<external-scheme>
  <scheme-name>SampleDiskPersistentScheme</scheme-name>
  <bdb-store-manager>
    <directory>/my/storage/directory</directory>
    <store-name>{cache-name}.store</store-name>
  </bdb-store-manager>
</external-scheme>

In-memory cache with disk based overflow

This sample uses an overflow-scheme to define a size limited in-memory cache, once the in-memory (front-scheme) size limit is reached, a portion of the cache contents will be moved to the on-disk (back-scheme). The front-scheme's eviction policy will determine which elements to move from the front to the back.

<overflow-scheme>
  <scheme-name>SampleOverflowScheme</scheme-name>
  <front-scheme>
    <local-scheme>
      <scheme-ref>SampleMemoryLimitedScheme</scheme-ref>
    </local-scheme>
  </front-scheme>
  <back-scheme>
    <external-scheme>
      <scheme-ref>SampleDiskScheme</scheme-ref>
    </external-scheme>
  </back-scheme>
</overflow-scheme>

Cache of a database

This sample uses a read-write-backing-map-scheme to define a cache of a database. This scheme maintains local cache cache of a portion of the database contents. Cache misses will read-through to the database, and cache writes will be written back to the database.

The {cache-name} macro is used to inform the cache store implementation of the name of the cache it will back.

<read-write-backing-map-scheme>
  <scheme-name>SampleDatabaseScheme</scheme-name>
  <internal-cache-scheme>
    <local-scheme>
      <scheme-ref>SampleMemoryScheme</scheme-ref>
    </local-scheme>
  </internal-cache-scheme>
  <cachestore-scheme>
    <class-scheme>
      <class-name>com.tangosol.examples.coherence.DBCacheStore</class-name>
      <init-params>
        <init-param>
          <param-type>java.lang.String</param-type>
          <param-value>{cache-name}</param-value>
        </init-param>
      </init-params>
    </class-scheme>
  </cachestore-scheme>
</read-write-backing-map-scheme>

Clustered caches

This section defines a series of clustered cache examples. Clustered caches are accessible from multiple JVMs (any cluster node running the same cache service). The internal cache storage (backing-map) on each cluster node is defined using local caches. The cache service provides the capability to access local caches from other cluster nodes.

Replicated cache

This sample uses the replicated-scheme to define a clustered cache in which a copy of each cache entry will be stored on all cluster nodes.

The "In-memory cache" sample is used to define the cache storage on each cluster node. The size of the cache is only limited by the cluster node with the smallest JVM heap.

<replicated-scheme>
  <scheme-name>SampleReplicatedScheme</scheme-name>
  <backing-map-scheme>
    <local-scheme>
      <scheme-ref>SampleMemoryScheme</scheme-ref>
    </local-scheme>
  </backing-map-scheme>
</replicated-scheme>

Replicated cache with overflow

<replicated-scheme>
  <scheme-name>SampleReplicatedOverflowScheme</scheme-name>
  <backing-map-scheme>
    <overflow-scheme>
      <scheme-ref>SampleOverflowScheme</scheme-ref>
    </overflow-scheme>
  </backing-map-scheme>
</replicated-scheme>

Partitioned cache

This sample uses the distributed-scheme to define a clustered cache in which cache storage is partitioned across all cluster nodes.

The "In-memory cache" sample is used to define the cache storage on each cluster node. The total storage capacity of the cache is the sum of all storage-enabled cluster nodes running the partitioned cache service.

<distributed-scheme>
  <scheme-name>SamplePartitionedScheme</scheme-name>
  <backing-map-scheme>
    <local-scheme>
      <scheme-ref>SampleMemoryScheme</scheme-ref>
    </local-scheme>
  </backing-map-scheme>
</distributed-scheme>

Partitioned cache with overflow

The backing-map-scheme element could just as easily specify any of the other local cache samples. For instance if it had used the "In-memory cache with disk based overflow" each storage-enabled cluster node would have a local overflow cache allowing for much greater storage capacity. Note that the cache's backup storage also uses the same overflow scheme which allows for backup data to be overflowed to disk.

<distributed-scheme>
  <scheme-name>SamplePartitionedOverflowScheme</scheme-name>
  <backing-map-scheme>
    <overflow-scheme>
      <scheme-ref>SampleOverflowScheme</scheme-ref>
    </overflow-scheme>
  </backing-map-scheme>
  <backup-storage>
    <type>scheme</type>
    <scheme-name>SampleOverflowScheme</scheme-name>
  </backup-storage>
</distributed-scheme>

Partitioned cache of a database

Switching the [backing-map|distributed-cache#backing-map-scheme element to use a read-write-backing-map-scheme allows the cache to load and store entries against an external source such as a database.

This sample reuses the "Cache of a database" sample to define the database access.

<distributed-scheme>
  <scheme-name>SamplePartitionedDatabaseScheme</scheme-name>
  <backing-map-scheme>
    <read-write-backing-map-scheme>
      <scheme-ref>SampleDatabaseScheme</scheme-ref>
    </read-write-backing-map-scheme>
  </backing-map-scheme>
</distributed-scheme>

Local cache of a partitioned cache (Near cache)

This sample uses the near-scheme to define a local in-memory cache of a subset of a partitioned cache. The result is that any cluster node accessing the partitioned cache will maintain a local copy of the elements it frequently accesses. This offers read performance close to the replicated-scheme based caches, while offering the high scalability of a distributed-scheme based cache.

Note that the size limited configuration of the front-scheme specifies the limit on how much of the back-scheme cache is locally cached.

<near-scheme>
  <scheme-name>SampleNearScheme</scheme-name>
  <front-scheme>
    <local-scheme>
       <scheme-ref>SampleLimitedMemoryScheme</scheme-ref>
    </local-scheme>
  </front-scheme>
  <back-scheme>
    <distributed-scheme>
      <scheme-ref>SamplePartitionedScheme</scheme-ref>
    </distributed-scheme>
  </back-scheme>
</near-scheme>

Sample Cache Configurations