Chapter 13. Cache Stores

Procedure 13.1. Configure the Single File Store

1. Add the Cache Name

   The name parameter of the local-cache attribute is used to specify a name for the cache.

   <local-cache name="default">
   

2. Per-cache Statistics

   If statistics are enabled at the container level, per-cache statistics can be selectively disabled for caches that do not require monitoring by setting the statistics attribute to false.

   <local-cache name="default" statistics="true">
   

3. Configure the file-store Element

   The file-store element specifies configuration information for the single file store.
   The name parameter of the file-store element is used to specify a name for the file store.

   <local-cache name="default" statistics="true">
       <file-store name="myFileStore" />
   

4. Set the passivation Parameter

   The passivation parameter determines whether entries in the cache are passivated (true) or if the cache store retains a copy of the contents in memory (false).

   <local-cache name="default" statistics="true">
       <file-store name="myFileStore"
                   passivation="true" />
   

5. Set the purge Parameter

   The purge parameter specifies whether or not the cache store is purged when it is started. Valid values for this parameter are true and false.

   <local-cache name="default" statistics="true">
       <file-store name="myFileStore"
                   passivation="true"
                   purge="true" />
   

6. Set the shared Parameter

   The shared parameter is used when multiple cache instances share a cache store. This parameter can be set to prevent multiple cache instances writing the same modification multiple times. Valid values for this parameter are true and false. However, the shared parameter is not recommended for file-store.

   <local-cache name="default" statistics="true">
       <file-store name="myFileStore"
                   passivation="true"
                   purge="true"
                   shared="false" />
   

7. Specify the Directory Path Within the relative-to Parameter

   The relative-to property is the directory where the file-store stores the data. It is used to define a named path.
   The path property is the name of the file where the data is stored. It is a relative path name that is appended to the value of the relative-to property to determine the complete path.

   <local-cache name="default" statistics="true">
       <file-store name="myFileStore"
                   passivation="true"
                   purge="true"
                   shared="false"
                   relative-to="{PATH}"
                   path="{DIRECTORY}" />
   </local-cache>
   

8. Specify the maximum number of entries

   The maxEntries parameter provides maximum number of entries allowed. The default value is -1 for unlimited entries.

   <local-cache name="default" statistics="true">
       <file-store name="myFileStore"
                   passivation="true"
                   purge="true"
                   shared="false"
                   relative-to="{PATH}"
                   path="{DIRECTORY}"
                   max-entries="10000"/>
   </local-cache>
   

9. Set the fetch-state Parameter

   The fetch-state parameter when set to true fetches the persistent state when joining a cluster. If multiple cache stores are chained, only one of them can have this property enabled. Persistent state transfer with a shared cache store does not make sense, as the same persistent store that provides the data will just end up receiving it. Therefore, if a shared cache store is used, the cache does not allow a persistent state transfer even if a cache store has this property set to true. It is recommended to set this property to true only in a clustered environment. The default value for this parameter is false.

   <local-cache name="default" statistics="true">
       <file-store name="myFileStore"
                   passivation="true"
                   purge="true"
                   shared="false"
                   relative-to="{PATH}"
                   path="{DIRECTORY}"
                   max-entries="10000"
                   fetch-state="true"/>
   </local-cache>
   

10. Set the preload Parameter

    The preload parameter when set to true, loads the data stored in the cache store into memory when the cache starts. However, setting this parameter to true affects the performance as the startup time is increased. The default value for this parameter is false.

    <local-cache name="default" statistics="true">
        <file-store name="myFileStore"
                    passivation="true"
                    purge="true"
                    shared="false"
                    relative-to="{PATH}"
                    path="{DIRECTORY}"
                    max-entries="10000"
                    fetch-state="true"
                    preload="false"/>
    </local-cache>
    

11. Set the singleton Parameter

    The singleton parameter enables a singleton store cache store. SingletonStore is a delegating cache store used when only one instance in a cluster can interact with the underlying store. However, singleton parameter is not recommended for file-store.

    <local-cache name="default" statistics="true">
        <file-store name="myFileStore"
                    passivation="true"
                    purge="true"
                    shared="false"
                    relative-to="{PATH}"
                    path="{DIRECTORY}"
                    max-entries="10000"
                    fetch-state="true"
                    preload="false"
                    singleton="true"/>
    </local-cache>
    

Procedure 13.2. Configuring the Single File Store in Library Mode

1. Add the name value to the namedCache element. The following is an example of this step:

   <namedCache name="writeThroughToFile">
   

2. In the persistence element, set the passivation parameter to false. Possible values are true and false.

   <namedCache name="writeThroughToFile">
         <persistence passivation="false" />
   

3. Set up a single file configuration using the singleFile element:
   • fetchPersistentState - If set to true, the persistent state is fetched when joining a cluster. If multiple cache stores are chained, only one cache store can have this property set to true . The default for this value is false.
   • The ignoreModifications parameter determines whether operations that modify the cache (e.g. put, remove, clear, store, etc.) do not affect the cache store. As a result, the cache store can become out of sync with the cache.
   • The purgeOnStartup parameter specifies whether the cache store is purged when initially started.
   • The shared parameter is set to true when multiple cache instances share a cache store, which prevents multiple cache instances writing the same modification individually. The default for this attribute is false. However, the shared parameter is not recommended for file-store.
   • The preload parameter sets whether the cache store data is pre-loaded into memory and becomes immediately accessible after starting up. The disadvantage of setting this to true is that the start up time increases. The default value for this attribute is false.
   • The location parameter points to the location of file store.
   • The maxEntries parameter provides maximum number of entries allowed. The default value is -1 for unlimited entries.
   • The maxKeysInMemory parameter is used to speed up data lookup. The single file store keeps an index of keys and their positions in the file using the maxKeysInMemory parameter. The default value for this parameter is -1.

   <namedCache name="writeThroughToFile">
         <persistence passivation="false">
            <singleFile fetchPersistentState="true" 
                        ignoreModifications="false"
                        purgeOnStartup="false" 
                        shared="false"
                        preload="false"
                        location="/tmp/Another-FileCacheStore-Location"
                        maxEntries="100"
                        maxKeysInMemory="100">
            </singleFile>
         </persistence>
    </namedCache>
   

4. Add the async element to configure the asynchronous settings:
   • The enabled parameter determines whether the file store is asynchronous.
   • The threadPoolSize parameter specifies the number of threads that concurrently apply modifications to the store. The default value for this parameter is 5.
   • The flushLockTimeout parameter specifies the time to acquire the lock which guards the state to be flushed to the cache store periodically. The default value for this parameter is 1.
   • The modificationQueueSize parameter specifies the size of the modification queue for the asynchronous store. If updates are made at a rate that is faster than the underlying cache store can process this queue, then the asynchronous store behaves like a synchronous store for that period, blocking until the queue can accept more elements. The default value for this parameter is 1024 elements.
   • The shutdownTimeout parameter specifies the time to stop the cache store. Default value for this parameter is 25 seconds.

   <namedCache name="writeThroughToFile">
         <persistence passivation="false">
            <singleFile fetchPersistentState="true" 
                        ignoreModifications="false"
                        purgeOnStartup="false" 
                        shared="false"
                        preload="false"
                        location="/tmp/Another-FileCacheStore-Location"
                        maxEntries="100"
                        maxKeysInMemory="100">
               <async enabled="true" 
       	           threadPoolSize="500"
       	           flushLockTimeout="1"
   	           modificationQueueSize="1024"
   	           shutdownTimeout="25000"/>
           </singleFile>
         </persistence>
    </namedCache>