Cayenne User Documentation
Configuring Caching Behavior

## Cache Memory Management

"Cache Configuration" panel allows to configure a max number of objects in the shared LRU cache. By default it is set to 10000, which is appropriate for most applications. It is up to the user whether to change this parameter, however we advise to set it to a value to be higher than an estimated max. number of objects committed in a single transaction.

## Cache Sharing

Cayenne supports local and distributed caching of fetched data. When a new DataDomain is created, it uses default caching settings - data is cached within JVM, but no remote synchronization is performed. User can change these settings depending on the target application deployment strategy.

### No Cache Sharing Configuration

This type of configuration may result in somewhat faster commit operations, but is likely to lead to stale data when multiple users modify data in the same application. To disable any cache sharing uncheck "Use Shared Cache" checkbox.

### Local VM Cache Sharing Configuration

Default configuration for the new DataDomains. Ideal for applications that do not care about data being modified outside of the application. This configuration is acceptable for a lot of client-server and web applications.

### Cross-VM Cache Sharing Configuration

Configuration that allows to notify other applications about changes made by an application and to listen for such changes made by others. This type of configuration incurs the most overhead, because it will constantly send and receive synchronization messages, but it is also the most powerful configuration. Cayenne currently supports the use of JMS and JavaGroups frameworks for synchronization, and also allows users to create their own transport mechanism.

| Cayenne distribution does not include JavaGroups or JMS libraries. Those must be downloaded and installed separately. However until deployment phase, Cayenne does not require those libraries to be installed.

To configure distributed cache sharing, check "Remote Change Notifications" checkbox, and click "Configure" button to select and configure the type of transport to use.

| Synchronization is only done between remote DataDomains with the same name. Note that for JavaGroups configuration, a combination of multicast address and port must be unique for each DataDomain name.

### Choosing JavaGroups over JMS

JavaGroups is the most portable and flexible mechanism. At the minimum, JMS setup requires a JMS server running, and subjects for each of the DataDomains to be configured. JavaGroups is peer-to-peer library that is embedded into applications. Default configuration provided by CayenneModeler will work out of the box, provided that IP multicast is enabled on the network.

The conclusion is that using JMS is probably most appropriate when deploying within J2EE containers that already support this service, while JavaGroups can be used in almost any environment.

### Example JMS Change Notification Configuration

This example shows how the JMS change notification configuration looks for a Cayenne servlet running in the Jetty servlet container. The example uses the Apache ActiveMQ messaging broker.

It is assumed that the Jetty deployment has been configured to "look in" `$JETTYHOME/lib/ext`. Also assumed is that the Jetty deployment is configured to support JNDI. Both of these configurations can be achieved by editing the following line in the `start.ini` to have the `ext` and `plus` values;

    OPTIONS=Server,jmx,resources,websocket,ext,plus

The use of ActiveMQ assumes that the necessary client ActiveMQ "driver jar files" from the ActiveMQ distribution have been installed into the `$JETTYHOME/lib/ext` directory in the Jetty deployment.

In this example, the ficticious Cayenne "Data Domain Name" is called "foo". In the Cayenne modeller, the "Remote Change Notifications" is checked and the "Connection Factory Name" is set to `jms/footopicconnectionfactory`.

The following would appear in the `$JETTYHOME/etc/jetty.xml` file;

    <New class="org.eclipse.jetty.plus.jndi.Resource">
    <Arg></Arg>
    <Arg>jms/footopicconnectionfactory</Arg>
    <Arg>
     <New class="org.apache.activemq.ActiveMQConnectionFactory">
      <Arg>tcp://msg01.foo.co.nz:61616</Arg>
     </New>
    </Arg>
    </New>

    <New class="org.eclipse.jetty.plus.jndi.Resource">
    <Arg>org_apache_cayenne_access_DataRowStore_foo</Arg>
    <Arg>
      <New class="org.apache.activemq.command.ActiveMQTopic">
       <Arg>foochangenotificationtopic</Arg>
      </New>
    </Arg>
    </New>

That following would appear in the servlet's `web.xml` deployment descriptor file;

    <resource-ref>
    <res-ref-name>jms/footopicconnectionfactory</res-ref-name>
    <res-type>javax.jms.TopicConnectionFactory</res-type>
    <res-auth>Container</res-auth>
    </resource-ref>

    <resource-env-ref>
    <resource-env-ref-name>org_apache_cayenne_access_DataRowStore_foo</resource-env-ref-name>
    <resource-env-ref-type>javax.jms.Topic</resource-env-ref-type>
    </resource-env-ref>

This configuration should enable change notification to function.

## More about caching

Read more about caching options here.

.
Copyright ©2001-2010 Apache Software Foundation