Fusion Middleware Documentation
Advanced Search


Developing Applications with Oracle Coherence
Close Window

Table of Contents

Show All | Collapse

18 Cache Configurations by Example

This chapter provides a series of basic cache scheme definitions that can be used or modified as required. See Chapter 13, "Configuring Caches," for detailed instructions on how to configure caches. In addition, the samples in this chapter build upon one another and often use a <scheme-ref> element to reuse other samples as nested schemes. See "Using Scheme Inheritance" for details on using the <scheme-ref> element. Lastly, these samples only specify a minimum number of settings, follow the embedded links to a scheme's documentation to see the full set of options.

This chapter contains the following sections:

18.1 Local Caches (accessible from a single JVM)

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 are used as building blocks for clustered caches. See "Clustered Caches (accessible from multiple JVMs)".

This section contains the following topics:

18.1.1 In-memory Cache

Example 18-1 uses a local-scheme to define an in-memory cache. The cache stores as much as the JVM heap allows.

Example 18-1 Configuration for a Local, In-memory Cache

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

18.1.2 NIO In-memory Cache

Example 18-2 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. See the <maximum-size> subelement of nio-memory-manager.

Example 18-2 Configuration for a NIO In-memory Cache

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

18.1.3 Size Limited In-memory Cache

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

Example 18-3 Configuration for a Size Limited, In-memory, Local Cache

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

18.1.4 In-memory Cache with Expiring Entries

Adding an <expiry-delay> subelement to <local-scheme> causes cache entries to automatically expire if they are not updated for a given time interval. When expired the cache invalidates the entry, and remove it from the cache.

Example 18-4 Configuration for an In-memory Cache with Expiring Entries

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

18.1.5 Cache on Disk

Example 18-5 uses an external-scheme to define an on disk cache.

Note:

This example uses the bdb-store-manager (Berkeley Database) for its on disk storage implementation. See external-scheme for additional external storage options.

Example 18-5 Configuration to Define a Cache on Disk

<external-scheme>
  <scheme-name>SampleDiskScheme</scheme-name>
  <bdb-store-manager/>
</external-scheme>

18.1.6 Size Limited Cache on Disk

Adding a <high-units> sub- element to external-scheme limits the size of the cache. The cache is size limited to one million entries. When the limit is exceeded, LRU eviction is used determine which elements to evict from the cache. Refer to "paged-external-scheme" for an alternate size limited external caching approach.

Example 18-6 Configuration for a Size Limited Cache on Disk

<external-scheme>
  <scheme-name>SampleDiskLimitedScheme</scheme-name>
  <bdb-store-manager/>
  <high-units>1000000</high-units>
</external-scheme>

18.1.7 Persistent Cache on Disk

Example 18-7 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 (see "Persistence (long-term storage)") in non-clustered caches when using either the 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 is stored in. See "Using Parameter Macros" for more information on this macro.

Example 18-7 Configuration for Persistent cache on disk with Berkeley DB

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

18.1.8 In-memory Cache with Disk Based Overflow

Example 18-8 uses an overflow-scheme to define a size limited in-memory cache, when the in-memory (<front-scheme>) size limit is reached, a portion of the cache contents are moved to the on disk (<back-scheme>). The front-scheme's <eviction-policy> determines which elements to move from the front to the back.

Note that this example reuses the examples in "Size Limited Cache on Disk" and "Cache on Disk". to implement the front and back of the cache.

Example 18-8 Configuration for In-memory Cache with Disk Based Overflow

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

18.1.9 Cache of a Database

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

The cachestore-scheme element is configured with a custom class implementing either the com.tangosol.net.cache.CacheLoader or com.tangosol.net.cache.CacheStore interface. This class is responsible for all operations against the database, such as reading and writing cache entries. See "Sample Cache Store Implementation" implementations for examples of writing a cache store.

The {cache-name} macro is used to inform the cache store implementation of the name of the cache it backs. See "Using Parameter Macros" for more information on this macro.

Example 18-9 Configuration for the Cache of a Database

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

18.2 Clustered Caches (accessible from multiple JVMs)

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 (see "Local Caches (accessible from a single JVM)"). The cache service provides the capability to access local caches from other cluster nodes.

This section contains the following topics:

18.2.1 Replicated Cache

Example 18-10 uses the replicated-scheme element to define a clustered cache in which a copy of each cache entry is stored on all cluster nodes.

The sample in "In-memory Cache" 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.

Example 18-10 Configuration for a Replicated Cache

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

18.2.2 Replicated 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 cluster node would have a local overflow cache allowing for much greater storage capacity.

Example 18-11 Configuration for a 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>

18.2.3 Partitioned Cache

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

The "In-memory Cache" 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. See the <local-storage> subelement of "distributed-scheme".

Example 18-12 Configuration for a Partitioned Cache

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

18.2.4 Partitioned Cache with Overflow

The backing-map-scheme element can use a scheme reference to 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.

Example 18-13 Configuration for a Partitioned Cache with Overflow

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

18.2.5 Partitioned Cache with Journal Storage

Example 18-14 uses the backing-map-scheme element to define a partitioned cache that uses a RAM journal for the backing map. The RAM journal automatically delegates to a flash journal when the RAM journal exceeds a configured memory size. For details about configuring RAM journals and flash journals, see "Defining Journal Schemes".

Example 18-14 Configuration for a Partitioned Cache with RAM Journaling

<distributed-scheme>
   <scheme-name>SamplePartitionedJournalScheme</scheme-name>
      <backing-map-scheme>
         <ramjournal-scheme/>
      </backing-map-scheme>
   <autostart>true</autostart>
</distributed-scheme>

Example 18-15 define a partitioned cache that directly uses a flash journal for the backing map.

Example 18-15 Configuration for a Partitioned Cache with Flash Journaling

<distributed-scheme>
   <scheme-name>SamplePartitionedJournalScheme</scheme-name>
      <backing-map-scheme>
         <flashjournal-scheme/>
      </backing-map-scheme>
   <autostart>true</autostart>
</distributed-scheme>

18.2.6 Partitioned Cache of a Database

Switching the 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.

Example 18-16 reuses the "Cache of a Database" to define the database access.

Example 18-16 Configuration for a Partitioned Cache of a Database

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

18.2.7 Partitioned Cache with a Serializer

Example 18-17 uses the serializer element in distributed-scheme to define a serializer that is used to serialize and deserialize user types. In this case, the partitioned cache uses POF (ConfigurablePofContext) as its serialization format. Note that if you use POF and your application uses any custom user type classes, then you must also define a custom POF configuration for them. See Appendix D, "POF User Type Configuration Elements" for more information on POF elements.

Example 18-17 Configuration for a Partitioned Cache with a Serializer

<distributed-scheme>
  <scheme-name>SamplePartitionedPofScheme</scheme-name>
  <service-name>PartitionedPofCache</service-name>
  <serializer>
    <instance>
      <class-name>com.tangosol.io.pof.ConfigurablePofContext</class-name>
    </instance>
  </serializer>
  <backing-map-scheme>
    <local-scheme/>
  </backing-map-scheme>
  <autostart>true</autostart>
</distributed-scheme>

Serializers that are defined in the tangosol-coherence.xml deployment descriptor can also be referenced.

Example 18-18 Partitioned Cache that References a Serializer

<distributed-scheme>
  <scheme-name>SamplePartitionedPofScheme</scheme-name>
  <service-name>PartitionedPofCache</service-name>
  <serializer>pof</serializer>
  <backing-map-scheme>
    <local-scheme/>
  </backing-map-scheme>
  <autostart>true</autostart>
</distributed-scheme>

Lastly a default serializer can be defined for all cache schemes and alleviates having to explicitly include a <serializer> element in each cache scheme definition. The global serializer definitions can also reference serializers that are defined in the tangosol-coherence.xml deployment descriptor

Example 18-19 Defining a Default Serializer

<?xml version='1.0'?>

<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
   coherence-cache-config.xsd">
   <defaults>
      <serializer>pof</serializer>
   </defaults>
   ...

18.2.8 Near Cache

Example 18-20 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 maintains 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.

The "Size Limited In-memory Cache" sample is reused to define the "near" (<front-scheme>) cache, while the "Partitioned Cache" sample is reused to define the near-scheme.

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

Example 18-20 Configuration for a Local Cache of a Partitioned Cache

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