Introduction

Distributed Cacheonix is configured using element server. Below is a complete example of cacheonix-config.xml that contains a configuration of a cluster node that carries partitions for three distributed caches:

<?xml version ="1.0"?>
<cacheonix xmlns="http://www.cacheonix.com/schema/configuration"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.cacheonix.com/schema/configuration http://www.cacheonix.com/schema/cacheonix-config-2.0.xsd">

   <licensePath path="META-INF/cacheonix-license.xml"/>

   <server>

      <listener>
         <tcp port="8879" buffer="128k"/>
      </listener>

      <broadcast>
         <multicast multicastAddress="225.0.1.2" multicastPort="9998" multicastTTL="0"/>
      </broadcast>

      <partitionedCache name="customer.cache">
         <store>
            <lru maxElements="10000" maxBytes="10mb"/>
            <expiration idleTime="120s"/>
         </store>
      </partitionedCache>

      <partitionedCache name="invoice.cache">
         <store>
            <lru maxElements="10000" maxBytes="10mb"/>
            <expiration idleTime="120s"/>
         </store>
      </partitionedCache>

      <partitionedCache name="search.results.cache">
         <store>
            <lru maxBytes="5mb"/>
         </store>
      </partitionedCache>
   </server>
</cacheonix>

The following sections discusses configuring various aspects of Cacheonix.

Configuring Cacheonix License

Configuring Production License

Cacheonix requires a valid license file, usually cacheonix-license.xml, to operate properly. You can download a license file that allows to evaluate Cacheonix in a production-like environment such as test or QA from the Cacheonix download website. Contact us to order your production Cacheonix license. Once you have obtained the Cacheonix license, use one of the three following ways to make Cacheonix use the license.

The first approach is to point Cacheonix configuration to a location of the Cacheonix license file using element licensePath. This is a preferred way because it allows to establish a known, shared, easy-to-manage, location for the license file. The licensePath accepts any fully qualified URL. Below is an example of a Cacheonix configuration that points to a Cacheonix license file located on a shared mount, /mnt/cacheonix/cacheonix-license.xml:

<?xml version ="1.0"?>
<cacheonix xmlns="http://www.cacheonix.com/schema/configuration" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.cacheonix.com/schema/configuration http://www.cacheonix.com/schema/cacheonix-config-2.0.xsd">

   <licensePath path="file:///mnt/cacheonix/cacheonix-license.xml"/>

   <server>
   . . .
   </server>
</cacheonix>

If you prefer to package the license file with your application, licensePath will also work with an unqualified path. In this case Cacheonix will treat this path as a resource path; the root of the path should be included the classpath.

The second approach is to store the content of the license file inside the cacheonix-config.xml. This approach to managing the Cacheonix license is known as 'inline license'. The inline license is supported by a license element. The advantage of this approach is that the license can be managed using the same change management process that is used for cacheonix-config.xml. The disadvantage is that in a bigger cluster updating the license might become cumbersome as it would require modifying a lot of configuration files. Below is an example of using an inline license in cacheonix-config.xml:

<?xml version ="1.0"?>
<cacheonix xmlns="http://www.cacheonix.com/schema/configuration" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.cacheonix.com/schema/configuration http://www.cacheonix.com/schema/cacheonix-config-2.0.xsd">

   <license created="2011-06-20" customer="Developer"
            key="302C0214647DEE6516EFFDA7E4EE0FC1497F270B244820CF0214140D5EE36EF14D820BB7D9BDB57C6339DD8F27CF"
            maxServers="1" productName="Cacheonix" productVersion="2.0" productionLicense="false"
            type="Developer">
      <licenseAddress from="0.0.0.0" to="255.255.255.255"/>
   </license>

   <server>
   . . .
   </server>
</cacheonix>

The third approach is to pass to the JVM a property cacheonix.license using Java command line. This property will overwrite any licensePath and license present in cacheonix-config.xml. This approach allows to set the location of Cacheonix license file at the time of the application launch but introduces an additional point of change management. Example:

java -Dcachenix.license=file://C:/cacheonix/cacheonix-license.xml

Configuring Developer License

cacheonix.jar includes a developer license. The developer license allows to configure and to run a local multi-server cluster. The local cluster consist of a set of Cacheonix instances running on developer's machine. The local cluster allows developers to test Cacheonix applications while running Cacheonix in the distributed mode. Use path META-INF/cacheonix-license.xml to access the Cacheonix developer license. Here is an example of using licensePath with the developer license:

<?xml version ="1.0"?>
<cacheonix xmlns="http://www.cacheonix.com/schema/configuration" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.cacheonix.com/schema/configuration http://www.cacheonix.com/schema/cacheonix-config-2.0.xsd">

   <licensePath path="META-INF/cacheonix-license.xml"/>

   <server>
   . . .
   </server>
</cacheonix>

Below is an example of configuring the developer license using Java command line:

java -Dcachenix.license=META-INF/cacheonix-license.xml

Configuring Cacheonix I/O Subsystem

Configuring Cacheonix TCP Listener

Cacheonix uses TCP/IP for inter-node communications. Use element listener to configure the port that Cacheonix node is listening on. Example:

<listener>
    <tcp port="8879"/>
</listener>

Element tcp has a mandatory attribute port and optional attributes address and buffer.

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

By default Cacheonix listens on all local addresses. If, for some reason, the address that Cacheonix listens on should be limited, optional attribute address provides such an ability. It must be one of the local interface addresses. If the address is not specified, the node will listen on any of the node's IP addresses. This feature might be useful for multi-home cluster nodes where the server should accept connections only on one of its interfaces. We recommend not setting this attribute unless there is a reason setting it.

Attribute buffer allows to increase the socket I/O buffer.

Below is a more elaborate example of the listener configuration:

<listener>
    <tcp port="8879" address="192.168.1.2 buffer="64k"/>
</listener>

Configuring Cacheonix Broadcast

Element broadcast defines means that Cacheonix uses for broadcast-style communications such as cluster membership management.

Multicast Configuration

<broadcast>
   <multicast multicastAddress="225.0.1.2" multicastPort="9998" multicastTTL="0"/>
</broadcast>

Use element multicast if you'd like Cacheonix to use multicast. Cacheonix recommends multicast because it provides significant reduction in network traffic when it comes to sending a message to all nodes in the cluster. The bigger your Cacheonix cluster, the greater the savings.

A mandatory attribute multicastAddress defines a logical IP address that identifies dynamic multicast group that a Cacheonix node should join. Cacheonix uses multicast address to send and receive messages to support cluster membership and other broadcast-style 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

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 address and multicast port.

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:

Non-Multicast Networks

Some network environments don't allow use of multicast. Cacheonix fully supports such environments this by making it possible to designate a server which IP address is known to other machines in the cluster and by providing a simple configuration parameter that switches cluster nodes to a TCP-only mode. Here is an example of a server configuration for a environment that doesn't allow multicast:

<broadcast>
    <knownAddress>
        <tcp address="192.168.1.1" port="8879"/>
    </knownAddress>
</broadcast>

We strongly recommend using multicast for maximum reliability and performance. Multicast provides significant savings in network traffic and allows to monitor presence of servers on the network. It is important to understand a knownAddress-node inevitably becomes a single point of failure. It is critical that the knownAddress-node is very reliable and is always up.

Configuring Partitioned Distributed Cache

Use element partitionedCache to configure a partitioned distributed cache. Below is a fragment of cacheonix-config.xml that configures a partitioned distributed cache backed by an LRU store:

<partitionedCache name="invoice.cache">
    <store>
        <lru maxElements="100000" maxBytes="50m"/>
    </store>
</partitionedCache>

Configuring Cache Expiration

Cacheonix provides two ways to control cache eviction bases on time, particularly, attributes timeToLive and idleTime. Optional attribute timeToLive defines for how long a key may stay in the cache before the cache removes it. Optional attribute idleTime defines for how long a key may stay in the cache without being accessed for read or write. Example:

<partitionedCache name="invoice.cache">
    <store>
        <lru maxElements="100000" maxBytes="50m"/>
        <expiration timeToLive="60s" idleTime="30s"/>
    </store>
</partitionedCache>

Configuring Cache Replication

Cacheonix supports seamless cache replication for high availability. To enable replication, add replication element to the store element:

<partitionedCache name="invoice.cache">
     <store>
        <lru maxElements="100000" maxBytes="50m"/>
        <replication replicaCount="2"/>
     </store>
</partitionedCache>

Configuring Cache Data Source

A cache can be configured with an optional supplier of data for the case when a key is not in the cache (a cache miss). Implement interface cacheonix.cache.datasource.DataSource to be able to populate the cache lazily from a database or from any other source of data. Classes implementing cacheonix.cache.datasource.DataSource must provide a public un-protected no-argument constructor. Configure the cache data source by adding dataSource element to the cache configuration:

<partitionedCache name="property.cache">
     <store>
        <lru maxElements="10" maxBytes="10mb"/>
        <expiration timeToLive="1s"/>

        <dataSource className="example.PropertyCacheDataSource"/>

     </store>
</partitionedCache>

Check an example of an implementation of cacheonix.cache.datasource.DataSource.

Configuring Cacheonix Temporary Directory

Cacheonix uses the temporary directory to store its temporary files and files containing cache elements that were evicted to the disk. An optional element tempDir allows to set a path to Cacheonix temporary directory. We recommend leaving it set to the default value. Below is a fragment of cacheonix-config.xml that sets the temporary directory explicitely:

<?xml version ="1.0"?>
<cacheonix xmlns="http://www.cacheonix.com/schema/configuration"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.cacheonix.com/schema/configuration http://www.cacheonix.com/schema/cacheonix-config-2.0.xsd">

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

   . . .

</cacheonix>