Configuring Cache

Package
Description

Click on ^Javadoc link to open Javadoc documentation.

Package

org.gridgain.grid.cache ^Javadoc

Description

This interface defines grid cache configuration. This configuration is passed to grid via GridConfiguration.getCacheConfiguration() ^Javadoc method. It defines all configuration parameters required to start a cache within grid instance. You can have multiple caches configured with different names within one grid.

Note, that absolutely every configuration property in GridCacheConfiguration ^Javadoc is optional. One can simply create new instance of GridCacheConfigurationAdapter ^Javadoc , for example, and pass it to GridConfiguration#getCacheConfiguration() ^Javadoc to start grid cache with default configuration.

The following configuration parameters can be used to configure cache with GridCacheConfigurationAdapter ^Javadoc :

Setter Method	Description	Optional	Default
`setName(String)` ^Javadoc	Cache name.	Yes	`null`
`setCacheMode(GridCacheMode)` ^Javadoc	Caching mode to use. You can configure cache either to be local-only, fully replicated, partitioned, or near.	Yes	`GridCacheMode.REPLICATED` ^Javadoc
`setAffinity(GridCacheAffinity)` ^Javadoc	Key topology resolver to provide mapping from keys to nodes.	Yes	`null`
`setAffinityMapper(GridCacheAffinityMapper)` ^Javadoc	Affinity key mapper used to provide custom affinity key for any given key.	Yes	`GridCacheDefaultAffinityMapper`
`setAtomicSequenceReserveSize(int)`	Default number of sequence values reserved for `GridCacheAtomicSequence` instances.	Yes	`1000`
`setAutoIndexQueryTypes(Collection<GridCacheQueryType>)` ^Javadoc	Query types to use to auto index values of boxed and unboxed primitive types, Strings and Dates.	Yes	`null`
`setBatchUpdateOnCommit(boolean)` ^Javadoc	If `true`, then all transactional values will be written to persistent storage at commit phase. If `false`, then values will be persisted after every operation.	Yes	`true`
`setCloner(GridCacheCloner)` ^Javadoc	Cloner to be used for cloning values that are returned to user only if `GridCacheFlag.CLONE` ^Javadoc is set on `GridCacheProjection` ^Javadoc .	Yes	`GridCacheBasicCloner` ^Javadoc
`setDefaultLockTimeout(long)` ^Javadoc	Default lock timeout.	Yes	`0`, which means that lock acquisition will never timeout
`setDefaultTimeToLive(long)` ^Javadoc	Time to live for all objects in cache.	Yes	`0`, which means that objects never expire
`setDefaultTxConcurrency(GridCacheTxConcurrency)` ^Javadoc	Default cache transaction concurrency.	Yes	`GridCacheTxConcurrency.OPTIMISTIC` ^Javadoc
`setDefaultTxIsolation(GridCacheTxIsolation)` ^Javadoc	Default cache transaction isolation.	Yes	`GridCacheTxIsolation.REPEATABLE_READ` ^Javadoc
`setDefaultTxTimeout(long)` ^Javadoc	Default transaction timeout.	Yes	`0`, which means that transactions will never timeout
`setEvictionPolicy(GridCacheEvictionPolicy)` ^Javadoc	Cache eviction policy.	Yes	`GridCacheLirsEvictionPolicy` ^Javadoc
`setGarbageCollectorFrequency(int)` ^Javadoc	Frequency at which distributed garbage collector will check other nodes if there are any zombie locks left over.	Yes	`0`, which means that GC is disabled
`setIndexAnalyzeFrequency(long)` ^Javadoc	Frequency of running H2 `"ANALYZE"` command in order to update selectivity statistics of H2 database tables.	Yes	`10` minutes
`setIndexAnalyzeSampleSize(long)` ^Javadoc	Number of samples used to run H2 `"ANALYZE"` command in order to update selectivity statistics of H2 database tables.	Yes	`10000`
`setIndexCleanup(boolean)` ^Javadoc	Flag indicating whether query storage should be deleted or not upon start.	Yes	`true`
`setIndexFixedTyping(boolean)` ^Javadoc	Flag indicating that the same key object can only be associated with the same value type and a value type can only be associated with keys of the same type.	Yes	`true`
`setIndexFullClassName(boolean)` ^Javadoc	Flag indicating whether full class names or simple class namess should be used in queries.	Yes	`false`
`setIndexH2Options(String)` ^Javadoc	Addition options to H2 database (query storage).	Yes	`null`
`setIndexMemoryOnly(boolean)` ^Javadoc	Flag indicating whether query index should be stored only in memory (not on disk).	Yes	`false`
`setIndexMaxOperationMemory(int)` ^Javadoc	Maximum memory used per single operation with query index (store and remove), in bytes.	Yes	`100000`
`setIndexPassword(String)` ^Javadoc	Optional password for index store.	Yes	`null`
`setIndexPath(String)` ^Javadoc	Absolute or relative to `GRIDGAIN_HOME` path for storing query indexes on disk.	Yes	`GRIDGAIN_HOME/work/cache/indexes`
`setIndexUsername(String)` ^Javadoc	Optional user name for index store.	Yes	`null`
`setInvalidate(boolean)` ^Javadoc	Invalidation flag.	Yes	`false`
`setNearEnabled(boolean)` ^Javadoc	Indicates whether near cache is enabled in case of `GridCacheMode.PARTITIONED` ^Javadoc mode.	Yes	`true`
`setNearEvictionPolicy(GridCacheEvictionPolicy)` ^Javadoc	Eviction policy for near cache.	Yes	`GridCacheLirsEvictionPolicy` ^Javadoc with maximum size set to 10000
`setNearStartSize(int)` ^Javadoc	Initial cache size for near cache.	Yes	`1024`
`setPreloadBatchSize(int)` ^Javadoc	Size (in number bytes) to be loaded within a single preload message.	Yes	`102400`
`setPreloadMode(GridCachePreloadMode)` ^Javadoc	Preload mode for distributed cache.	Yes	`GridCachePreloadMode.ASYNC` ^Javadoc
`setPreloadThreadPoolSize(int)`	Size of preloading thread pool.	Yes	`2`
`setRefreshAheadRatio(double)` ^Javadoc	Refresh-ahead ratio.	Yes	`0`
`setStartSize(int)` ^Javadoc	Initial cache size.	Yes	`1024`
`setStore(GridCacheStore)` ^Javadoc	Persistent storage for read-through and write-through operations.	Yes	`null`
`setStoreEnabled(boolean)` ^Javadoc	Flag indicating whether GridGain should activate read-through/write-through behaviour by default.	Yes	`true`
`setSwapEnabled(boolean)` ^Javadoc	Flag indicating whether GridGain should use swap storage by default if user did not specify this explicitly using those methods whether it is possible.	Yes	`true`
`setSynchronousCommit(boolean)` ^Javadoc	Flag indicating whether GridGain should wait for commit replies from all nodes.	Yes	`false`
`setSynchronousRollback(boolean)` ^Javadoc	Flag indicating whether GridGain should wait for rollback replies from all nodes.	Yes	`false`
`setTransactionManagerLookup(GridCacheTmLookup)` ^Javadoc	Transaction manager finder for integration for JEE app servers.	Yes	`null`

Some of the most commonly used configuration properties are explained in more detail below.

Name

Name of the cache. If not provided or null, then this will be considered a default cache. It can be accessed via Grid.cache() ^Javadoc method. Otherwise, if name is provided, the cache will be accessed via Grid.cache(String) ^Javadoc method.

Cache Mode

Caching mode to use. You can configure cache either to be local-only, fully replicated, partitioned, or near. If not provided, REPLICATED ^Javadoc mode will be used by default.

In LOCAL ^Javadoc mode caches residing on different grid nodes will not know about each other. This mode is very useful when caching read-only data or data that automatically expires at a certain interval and then automatically reloaded from persistence store.

In REPLICATED ^Javadoc mode all the keys are distributed to all participating nodes. User still has affinity control over subset of nodes for any given key via GridCacheAffinity ^Javadoc configuration.

In PARTITIONED mode the overall key set will be divided into partitions and all partitions will be split equally between participating nodes. User has affinity control over key assignment via GridCacheAffinity ^Javadoc configuration. Note that partitioned cache is always fronted by local 'near' cache which stores most recent data. You can configure the size of near cache via setNearEvictionPolicy(GridCacheEvictionPolicy) ^Javadoc configuration property. If you don't want to store any data in near cache, you should configure GridCacheAlwaysEvictionPolicy ^Javadoc which evicts all entries from cache immediately.

Affinity

Cache key affinity which maps keys to nodes (utilized for replicated and partitioned caches). Whenever a key is given to cache, it is first passed to a pluggable GridCacheAffinityMapper ^Javadoc which may potentially map this key to an alternate key which should be used for affinity. The key returned from GridCacheAffinityMapper.affinityKey(Object) ^Javadoc method is then passed to GridCacheAffinity.partition(Object) ^Javadoc method to find out the partition for the key. Then this partition together with all participating nodes are passed to GridCacheAffinity.nodes(int, Collection<GridRichNode>) ^Javadoc method which returns a collection of nodes. This collection of nodes is used for node affinity. In REPLICATED ^Javadoc cache mode the key will be cached on all returned nodes; generally, all caching nodes participate in caching every key in replicated mode. In PARTITIONED ^Javadoc mode, only primary and backup nodes are returned with primary node always in the first position. So if there is 1 backup node, then the returned collection will have 2 nodes in it - primary node in first position, and backup node in second.

Examples

GridCacheConfiguration ^Javadoc may be defined in code:

GridConfigurationAdapter c = new GridConfigurationAdapter();

GridCacheConfigurationAdapter cc = new GridCacheConfigurationAdapter();

cc.setName("replicated");
cc.setCacheMode(GridCacheMode.PARTITIONED);
cc.setSynchronousCommit(true);
cc.setStartSize(20);
cc.setAffinity(new GridCachePartitionedAffinity<Object>(0, 10));

c.setCacheConfiguration(cc);

G.start(c);

or from Spring configuration file:

<!-- Local cache with custom initial size. -->
<bean class="org.gridgain.grid.cache.GridCacheConfigurationAdapter">
    <!-- Cache name is 'local'. -->
    <property name="name" value="local"/>

    <!-- LOCAL cache mode. -->
    <property name="cacheMode" value="LOCAL"/>

    <!-- Initial cache size. -->
    <property name="startSize" value="20"/>
</bean>

<!-- Replicated cache with synchronous preloading and synchronous commit. -->
<bean class="org.gridgain.grid.cache.GridCacheConfigurationAdapter">
    <!-- Cache name is 'replicated'. -->
    <property name="name" value="replicated"/>

    <!-- REPLICATED cache mode. -->
    <property name="cacheMode" value="REPLICATED"/>

    <!-- Set synchronous preloading (default is asynchronous). -->
    <property name="preloadMode" value="SYNC"/>

    <!-- Set synchronous commit to true. -->
    <property name="synchronousCommit" value="true"/>
</bean>

<!-- Partitioned cache with LRU eviction policy and custom number of backups. -->
<bean class="org.gridgain.grid.cache.GridCacheConfigurationAdapter">
    <!-- Cache name is 'partitioned'. -->
    <property name="name" value="partitioned"/>

    <!-- PARTITIONED cache mode. -->
    <property name="cacheMode" value="PARTITIONED"/>

    <!-- Optional eviction policy (GridCacheLirsEvictionPolicy is used by default). -->
    <property name="evictionPolicy">
        <bean class="org.gridgain.grid.cache.eviction.lru.GridCacheLruEvictionPolicy">
            <property name="maxSize" value="100"/>
        </bean>
    </property>

    <!-- Set the number of backups to 0 (default is 1). -->
    <property name="affinity">
        <bean class="org.gridgain.grid.cache.affinity.partitioned.GridCachePartitionedAffinity">
            <constructor-arg value="0"/>
            <constructor-arg value="10"/>
        </bean>
    </property>
</bean>

For more information about using Spring framework for configuration click here.

Page Operations