Overview

Cacheonix can be configured by providing an XML configuration file. Cacheonix uses a file named cacheonix-config.xml for all aspect of its configuration. Format of cacheonix-config.xml and the ways Cacheonix uses to find cacheonix-config.xml and its format are discussed in the following sections.

Format of cacheonix-config.xml

cacheonix-config.xml is a well-formed XML file.

Example:

<cacheonix tempDir="${java.io.temp}">

   <!--
   Clustered caches
   -->
   <cluster port="8877" address="127.0.0.1" multicastAddress="224.0.1.2" multicastPort="9999"
     multicastTTL="0" networkPartitionMode="exception">
      <cache name="distributed_test_cache" maxSize="1000" policy="lru" expirationSeconds="1000"
        overflowToDisk="yes"/>
   </cluster>

   <!--
   Local caches
   -->
   <local>
      <cache name="com.cacheonix.example.LRULocalExample1" maxSize="1000" policy="lru"
        expirationSeconds="1000" overflowToDisk="yes" maxOverflowSizeMBytes="1"/>

      <cache name="com.cacheonix.example.LRULocalExample2" maxSize="1000" policy="lru"
        expirationSeconds="1000" overflowToDisk="yes" maxOverflowSizeMBytes="1"/>

      <!--
      Cache to support testing.
      -->
      <cache name="local_test_cache" maxSize="10" policy="lru" expirationSeconds="1000"
        overflowToDisk="yes" maxOverflowSizeMBytes="1"/>

      <!--
      Cache to support testing of iBatis plugin.
      -->
      <cache name="test_ibatis_cache" maxSize="10" policy="lru" expirationSeconds="1000"
        overflowToDisk="yes" maxOverflowSizeMBytes="1"/>

      <!--
      Cache to support testing of Hibernate plugin.
      -->
      <cache name="test_hibernate_cache" maxSize="10" policy="lru" expirationSeconds="1000"
        overflowToDisk="yes" maxOverflowSizeMBytes="1"/>
   </local>
</cacheonix>

Names of elements and attributes in cacheonix-config.xml are case-sensitive

The format of the file is discussed in the following sections.

Element cacheonix

cacheonix is a top-level level element. Element cacheonix has the following attributes:

Element cacheonix has the following child elements:

Attribute tempDir

An optional attribute tempDir contains a path to Cacheonix temporary directory. Cacheonix uses the temporary directory to store its temporary files and files containing cache elements that were evicted to a disk.

Attribute homeAloneTimeoutMillis

An optional attribute homeAloneTimeoutMillis sets a timeout in milliseconds after that a Cacheonix process considers that there is no communication path to other processes and forms a single-process cluster. The default value is 30000 milliseconds or 30 seconds.

The value set by this attribute can be overridden by a command line parameter cacheonix.home.alone.timeout.millis.

Attribute defaultLockTimeoutMillis

An optional attribute defaultLockTimeoutMillis sets a timeout in milliseconds for a lock that was acquired without setting the timeout explicitly:

final Cache cache = CacheManager.getInstance().getCache("my.cache");
final CacheLock lock = cache.createLock();
lock.lock(); // Lock using default timeout
try {
   // Run application code
} finally {
 lock.unlock();
}

The default value is 30000 milliseconds or 30 seconds. The value set by this attribute can be overridden by a command line parameter cacheonix.default.lock.timeout.millis.

Attribute defaultStoreKeyByReference

An optional boolean attribute defaultStoreKeyByReference sets a default configuration-wide value for storing cached keys by reference. Storing keys by reference significantly speeds up cache read and write operations by eliminating the time to create a copy of the object when returning cached keys. The default value of defaultStoreKeyByReference is false.

Attribute defaultStoreValueByReference

An optional boolean attribute defaultStoreKeyByReference sets a default configuration-wide value for storing cached values by reference. Storing values by reference significantly speeds up cache read and write operations by eliminating the time to create a copy of the object hen returning cached values. The default value of defaultStoreValueByReference is false.

Element cluster

Element cluster provides network configuration parameters for one or more of distributed caches. The parameters define how a distributed cache communicates with other caches using network as a communication media.

Element cluster has the following attributes:

Element cluster has the following child elements:

Attribute port

Attribute port defines a mandatory TCP port that this Cacheonix node should listen on. We recommend setting this port to a value greater then 1024.

Attribute Address

An optional attribute address defines the IP address to which connections the cluster node should be addressed. It must be one of the local interface addresses. If the address is not specified, the node should accept connections to any of the node's IP addresses. This may be useful for cluster nodes with multiple interfaces where the server socket should be accept connection on one of its interfaces. We recommend not setting this attribute or setting it to a blank value unless there is a reason for limiting addresses that Cacheonix should listen on to a single address.

Attribute multicastAddress

A mandatory attribute multicastAddress defines a logical IP address that identifies dynamic multicast group that Cacheonix should join. Cacheonix uses multicast address send and receive messages to support cluster membership and inter-cache communications. IP v.4 defines multicast addresses as addresses from 224.0.0.0 to 239.255.255.255. Addresses in the range 224.0.0.0 to 224.0.0.255 are reserved for low-level multicast support operations. We recommend using the range 239.000.000.000-239.255.255.255 for setting multicastAddress. For example: 239.0.10.1

Important: All Cacheonix instances that belong to the same cluster should use the same multicast address.

Attribute multicastPort

A mandatory attribute multicastPort defines a UDP port that Cacheonix should use to receive and to send multicast messages.

We recommend setting multicast port to 9999.

All Cacheonix instances that belong to the same cluster should use the same multicast port.

Attribute multicastTTL

Mandatory attribute multicastTTL defines multicast TTL that is used to control how far the multicast messages can propagate.

A value of zero indicates that a message should not be forwarded out of the current host. This value should be used in development mode to avoid unintentional communications with cluster nodes running on other developer's machines.

A value of one means that the message is not forwarded out of the current subnet. This value is suitable for QA and for most production environments.

Values of two or greater mean larger, scopes as shown in the table below:

Element cache

Element cache provides configuration parameters for a named cache. Element cache has the following attributes:

Attribute name

In Cacheonix each cache is identified by its name. The value of the attribute name should be unique across Cacheonix configuration.

Attribute maxSize

This attribute defines maximum number of elements the cache can hold. When the number of elements in cache exceeds maxSize, Cacheonix will evict the overflow from the cache according to the eviction policy defined by an attribute policy.

Either maxSize or maxSizeBytes must be provided.

Attribute maxSizeBytes

This attributed defines maximum heap size in bytes occupied by cache elements. If both maxSizeBytes and maxSize are provided, Cacheonix will evict elements using a maximum that has been reached. It is guaranteed that neither maximum is exceeded.

Cacheonix allows setting maxSizeBytes as relative to the size of the JVM heap by using percent suffix. Using relative maximum cache supports running Cacheonix in different JVM configuration such as development, test or production environments without changing Cacheonix configuration thus reducing maintenance efforts. The following example sets maximum size of the cache to 10% of the JVM heap:

<cache name="relative.sized.cache" maxSizeBytes="10%"/>

 Cacheonix supports kilobyte, megabyte and gigabyte suffixes when setting maxSizeBytes:

<cache name="kilobyte.sized.cache" maxSizeBytes="100kb"/>
<cache name="megabyte.sized.cache" maxSizeBytes="2mb"/>
<cache name="gigabyte.sized.cache" maxSizeBytes="1gb"/>

Attribute policy

Optional attribute policy defines which element should a cache evict if the number elements in Cache exceeds the allowed maxim. Cacheonix supports the following policies:

The default value for the attribute policy is "lru".

Attribute expirationTimeSecs

Attribute expirationTimeSecs defines the number seconds since the element was put into cache before an element is discarded from the cache.
 

Attribute idleTimeSecs

Attribute idleTimeSecs defines the number milliseconds since the element was accessed last time before an element is discarded from the cache.
 

Attribute overflowToDisk

This optional flag defines if Cacheonix should evict cache overflow to disk. The valid values for overflowToDisk are "yes", "no", "true" and "false". Values "yes" or "true" enable overflow to disk. If overflow to disk is enabled, Cacheonix will store the evicted items on a disk instead of discarding them from the cache.

By default the overflow to disk is disabled.

Attribute maxOverflowSizeMBytes

Attribute maxOverflowSizeMBytes defines what maximum number of megabyte can entries evicted to disk should occupy. If this number is exceeded during put() Cacheonix will throw an exception.

By default the maximum is not set. The actual size is limited to free space on the disk used for storing the elements evicted to disk.

Attribute partitionContributor

Attribute partitionContributor determines if this clustered cache carries a cache partition. The valid values are "Yes", "No", "True" and "False". "Yes" means that this cache carries a cache partition.
 

Attribute partitionSizeBytes 

Attribute partitionSizeBytes defines the partition size this clustered cache. This attribute is required for a clustered cache configuration. The total size of the partitioned cache is determined as a multiple of the partition size and the number of cluster members participating in the partitioned cache.

Cacheonix supports kilobyte, megabyte and gigabyte suffixes when setting partitionSizeBytes: 

<cache name="kilobyte.sized.partitioned.cache" partitionSizeBytes="500kb"/>
<cache name="megabyte.sized.partitioned.cache" partitionSizeBytes="300mb"/>
<cache name="gigabyte.sized.partitioned.cache" partitionSizeBytes="1gb"/>

Important: partitionSizeBytes should set to the same value for cache configurations on all nodes in the cluster if they carry a cache partition.

Attribute storeKeyByReference

An optional boolean attribute storeKeyByReference defines how a cache stores keys.

A cache stores a reference to a key object if storeKeyByReference is set to "true" or "yes". Storing keys by reference  significantly speeds up read and write operations by eliminating the time needed to create a copy of the object when returning cached keys. For the cache to store keys by reference the keys have to be immutable. An immutable key is an object that state cannot be changed after the object is created. A key can be declared as immutable on demand by implementing signature interface cacheonix.cache.Immutable. Cacheonix always treats as immutable objects of the following types: java.lang.Byte, java.lang.Short, java.lang.Integer, java.lang.Long, java.lang.Boolean and java.lang.String. Please see the Immutable Key Pattern for a more detailed discussion on immutable keys.

The cache stores a copy of the key if storeKeyByReference is set to "false" or "no". 

Important: The default value of storeKeyByReference is false.

Attribute storeValueByReference

An optional boolean attribute storeValueByReference defines how a cache stores values.

A cache stores a reference to a value object if storeValueByReference set to "true" or "yes". Storing value by reference  significantly speeds up read and write operations by eliminating the time needed to create a copy of the object when returning cached values. For the cache to store values by reference the values have to be immutable. An immutable value is an object that state cannot be changed after the object is created. A value can be declared as immutable on demand by implementing signature interface cacheonix.cache.Immutable. Cacheonix always treats as immutable objects of the following types: java.lang.Byte, java.lang.Short, java.lang.Integer, java.lang.Long, java.lang.Boolean and java.lang.String.

The cache stores a copy of the key if storeValueByReference is set to "false" or "no". 

Important: The default value of storeValueByReference is false.

Attribute dataSource

An optional attribute dataSource defines the name of the class that serves as a supplier of data to the cache for the case when a key cannot be found in the cache (a cache miss). Use the cache data source to populate the cache lazily from a database or from other source of the cached data. The class should implement interface cacheonix.cache.datasource.CacheDataSource. Classes implementing cacheonix.cache.datasource.CacheDataSource must provide a public or an un-protected no-argument constructor.

Example:

<cache name="cache.with.data.source" maxSize="1000" dataSource="com.my.project.DataSourceImpl"/>

Attribute invalidator

An optional attribute invalidator defines a cache invalidator interface. Cacheonix uses classes implementing cacheonix.cache.invalidator.CacheInvalidator for backend invalidation of cache elements. The cache invalidator provides an ability to implement advanced custom invalidation schemes such as invalidating cache elements based on the database record's time stamps of version counters.

Classes implementing cacheonix.cache.invalidator.CacheInvalidator must provide a public or an un-protected no-argument constructor.

Example:

<cache name="cache.with.custom.invalidator" maxSize="1000" invalidator="com.my.project.InvalidatorImpl"/>