| <?xml version="1.0" encoding="UTF-8"?> |
| |
| <ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:noNamespaceSchemaLocation="ehcache.xsd" > |
| |
| <!-- |
| CacheManager Configuration |
| ========================== |
| An ehcache.xml corresponds to a single CacheManager. |
| |
| See instructions below or the ehcache schema (ehcache.xsd) on how to configure. |
| |
| System property tokens can be specified in this file which are replaced when the configuration |
| is loaded. For example multicastGroupPort=${multicastGroupPort} can be replaced with the |
| System property either from an environment variable or a system property specified with a |
| command line switch such as -DmulticastGroupPort=4446. |
| |
| DiskStore configuration |
| ======================= |
| |
| The diskStore element is optional. To turn off disk store path creation, comment out the diskStore |
| element below. |
| |
| Configure it if you have overflowToDisk or diskPersistent enabled for any cache. |
| |
| If it is not configured, and a cache is created which requires a disk store, a warning will be |
| issued and java.io.tmpdir will automatically be used. |
| |
| diskStore has only one attribute - "path". It is the path to the directory where |
| .data and .index files will be created. |
| |
| If the path is one of the following Java System Property it is replaced by its value in the |
| running VM. For backward compatibility these are not specified without being enclosed in the ${token} |
| replacement syntax. |
| |
| The following properties are translated: |
| * user.home - User's home directory |
| * user.dir - User's current working directory |
| * java.io.tmpdir - Default temp file path |
| * ehcache.disk.store.dir - A system property you would normally specify on the command line |
| e.g. java -Dehcache.disk.store.dir=/u01/myapp/diskdir ... |
| |
| Subdirectories can be specified below the property e.g. java.io.tmpdir/one |
| |
| --> |
| <diskStore path="java.io.tmpdir"/> |
| |
| <!-- |
| CacheManagerEventListener |
| ========================= |
| Specifies a CacheManagerEventListenerFactory which is notified when Caches are added |
| or removed from the CacheManager. |
| |
| The attributes of CacheManagerEventListenerFactory are: |
| * class - a fully qualified factory class name |
| * properties - comma separated properties having meaning only to the factory. |
| |
| Sets the fully qualified class name to be registered as the CacheManager event listener. |
| |
| The events include: |
| * adding a Cache |
| * removing a Cache |
| |
| Callbacks to listener methods are synchronous and unsynchronized. It is the responsibility |
| of the implementer to safely handle the potential performance and thread safety issues |
| depending on what their listener is doing. |
| |
| If no class is specified, no listener is created. There is no default. |
| --> |
| <cacheManagerEventListenerFactory class="" properties=""/> |
| |
| |
| <!-- |
| CacheManagerPeerProvider |
| ======================== |
| (For distributed operation) |
| |
| Specifies a CacheManagerPeerProviderFactory which will be used to create a |
| CacheManagerPeerProvider, which discovers other CacheManagers in the cluster. |
| |
| One or more providers can be configured. The first one in the ehcache.xml is the default, which is used |
| for replication and bootstrapping. |
| |
| The attributes of cacheManagerPeerProviderFactory are: |
| * class - a fully qualified factory class name |
| * properties - comma separated properties having meaning only to the factory. |
| |
| Providers are available for RMI, JGroups and JMS as shown following. |
| |
| RMICacheManagerPeerProvider |
| +++++++++++++++++++++++++++ |
| |
| Ehcache comes with a built-in RMI-based distribution system with two means of discovery of |
| CacheManager peers participating in the cluster: |
| * automatic, using a multicast group. This one automatically discovers peers and detects |
| changes such as peers entering and leaving the group |
| * manual, using manual rmiURL configuration. A hardcoded list of peers is provided at |
| configuration time. |
| |
| Configuring Automatic Discovery: |
| Automatic discovery is configured as per the following example: |
| <cacheManagerPeerProviderFactory |
| class="net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory" |
| properties="peerDiscovery=automatic, multicastGroupAddress=230.0.0.1, |
| multicastGroupPort=4446, timeToLive=32"/> |
| |
| Valid properties are: |
| * peerDiscovery (mandatory) - specify "automatic" |
| * multicastGroupAddress (mandatory) - specify a valid multicast group address |
| * multicastGroupPort (mandatory) - specify a dedicated port for the multicast heartbeat |
| traffic |
| * timeToLive - specify a value between 0 and 255 which determines how far the packets will |
| propagate. |
| |
| By convention, the restrictions are: |
| 0 - the same host |
| 1 - the same subnet |
| 32 - the same site |
| 64 - the same region |
| 128 - the same continent |
| 255 - unrestricted |
| |
| Configuring Manual Discovery: |
| Manual discovery is configured as per the following example: |
| <cacheManagerPeerProviderFactory class= |
| "net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory" |
| properties="peerDiscovery=manual, |
| rmiUrls=//server1:40000/sampleCache1|//server2:40000/sampleCache1 |
| | //server1:40000/sampleCache2|//server2:40000/sampleCache2" |
| propertySeparator="," /> |
| |
| Valid properties are: |
| * peerDiscovery (mandatory) - specify "manual" |
| * rmiUrls (mandatory) - specify a pipe separated list of rmiUrls, in the form |
| //hostname:port |
| |
| The hostname is the hostname of the remote CacheManager peer. The port is the listening |
| port of the RMICacheManagerPeerListener of the remote CacheManager peer. |
| |
| JGroupsCacheManagerPeerProvider |
| +++++++++++++++++++++++++++++++ |
| <cacheManagerPeerProviderFactory class="net.sf.ehcache.distribution.jgroups.JGroupsCacheManagerPeerProviderFactory" |
| properties="connect=UDP(mcast_addr=231.12.21.132;mcast_port=45566;ip_ttl=32; |
| mcast_send_buf_size=150000;mcast_recv_buf_size=80000): |
| PING(timeout=2000;num_initial_members=6): |
| MERGE2(min_interval=5000;max_interval=10000): |
| FD_SOCK:VERIFY_SUSPECT(timeout=1500): |
| pbcast.NAKACK(gc_lag=10;retransmit_timeout=3000): |
| UNICAST(timeout=5000): |
| pbcast.STABLE(desired_avg_gossip=20000): |
| FRAG: |
| pbcast.GMS(join_timeout=5000;join_retry_timeout=2000;shun=false;print_local_addr=false)" |
| propertySeparator="::" |
| /> |
| The only property necessary is the connect String used by jgroups to configure itself. Refer to the Jgroups documentation for explanation |
| of all the protocols. The example above uses UDP multicast. If the connect property is not specified the default JGroups connection will be |
| used. |
| |
| |
| JMSCacheManagerPeerProviderFactory |
| ++++++++++++++++++++++++++++++++++ |
| <cacheManagerPeerProviderFactory |
| class="net.sf.ehcache.distribution.jms.JMSCacheManagerPeerProviderFactory" |
| properties="..." |
| propertySeparator="," |
| /> |
| |
| The JMS PeerProviderFactory uses JNDI to maintain message queue independence. Refer to the manual for full configuration |
| examples using ActiveMQ and Open Message Queue. |
| |
| Valid properties are: |
| * initialContextFactoryName (mandatory) - the name of the factory used to create the message queue initial context. |
| * providerURL (mandatory) - the JNDI configuration information for the service provider to use. |
| * topicConnectionFactoryBindingName (mandatory) - the JNDI binding name for the TopicConnectionFactory |
| * topicBindingName (mandatory) - the JNDI binding name for the topic name |
| * getQueueBindingName (mandatory only if using jmsCacheLoader) - the JNDI binding name for the queue name |
| * securityPrincipalName - the JNDI java.naming.security.principal |
| * securityCredentials - the JNDI java.naming.security.credentials |
| * urlPkgPrefixes - the JNDI java.naming.factory.url.pkgs |
| * userName - the user name to use when creating the TopicConnection to the Message Queue |
| * password - the password to use when creating the TopicConnection to the Message Queue |
| * acknowledgementMode - the JMS Acknowledgement mode for both publisher and subscriber. The available choices are |
| AUTO_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE and SESSION_TRANSACTED. The default is AUTO_ACKNOWLEDGE. |
| --> |
| <cacheManagerPeerProviderFactory |
| class="net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory" |
| properties="peerDiscovery=automatic, |
| multicastGroupAddress=230.0.0.1, |
| multicastGroupPort=4446, timeToLive=1" |
| propertySeparator="," |
| /> |
| |
| |
| <!-- |
| CacheManagerPeerListener |
| ======================== |
| (Enable for distributed operation) |
| |
| Specifies a CacheManagerPeerListenerFactory which will be used to create a |
| CacheManagerPeerListener, which |
| listens for messages from cache replicators participating in the cluster. |
| |
| The attributes of cacheManagerPeerListenerFactory are: |
| class - a fully qualified factory class name |
| properties - comma separated properties having meaning only to the factory. |
| |
| Ehcache comes with a built-in RMI-based distribution system. The listener component is |
| RMICacheManagerPeerListener which is configured using |
| RMICacheManagerPeerListenerFactory. It is configured as per the following example: |
| |
| <cacheManagerPeerListenerFactory |
| class="net.sf.ehcache.distribution.RMICacheManagerPeerListenerFactory" |
| properties="hostName=fully_qualified_hostname_or_ip, |
| port=40001, |
| remoteObjectPort=40002, |
| socketTimeoutMillis=120000" |
| propertySeparator="," /> |
| |
| All properties are optional. They are: |
| * hostName - the hostName of the host the listener is running on. Specify |
| where the host is multihomed and you want to control the interface over which cluster |
| messages are received. Defaults to the host name of the default interface if not |
| specified. |
| * port - the port the RMI Registry listener listens on. This defaults to a free port if not specified. |
| * remoteObjectPort - the port number on which the remote objects bound in the registry receive calls. |
| This defaults to a free port if not specified. |
| * socketTimeoutMillis - the number of ms client sockets will stay open when sending |
| messages to the listener. This should be long enough for the slowest message. |
| If not specified it defaults to 120000ms. |
| |
| --> |
| <cacheManagerPeerListenerFactory |
| class="net.sf.ehcache.distribution.RMICacheManagerPeerListenerFactory"/> |
| |
| |
| <!-- |
| Cache configuration |
| =================== |
| |
| The following attributes are required. |
| |
| name: |
| Sets the name of the cache. This is used to identify the cache. It must be unique. |
| |
| maxElementsInMemory: |
| Sets the maximum number of objects that will be created in memory |
| |
| maxElementsOnDisk: |
| Sets the maximum number of objects that will be maintained in the DiskStore |
| The default value is zero, meaning unlimited. |
| |
| eternal: |
| Sets whether elements are eternal. If eternal, timeouts are ignored and the |
| element is never expired. |
| |
| overflowToDisk: |
| Sets whether elements can overflow to disk when the memory store |
| has reached the maxInMemory limit. |
| |
| The following attributes and elements are optional. |
| |
| timeToIdleSeconds: |
| Sets the time to idle for an element before it expires. |
| i.e. The maximum amount of time between accesses before an element expires |
| Is only used if the element is not eternal. |
| Optional attribute. A value of 0 means that an Element can idle for infinity. |
| The default value is 0. |
| |
| timeToLiveSeconds: |
| Sets the time to live for an element before it expires. |
| i.e. The maximum time between creation time and when an element expires. |
| Is only used if the element is not eternal. |
| Optional attribute. A value of 0 means that and Element can live for infinity. |
| The default value is 0. |
| |
| diskPersistent: |
| Whether the disk store persists between restarts of the Virtual Machine. |
| The default value is false. |
| |
| diskExpiryThreadIntervalSeconds: |
| The number of seconds between runs of the disk expiry thread. The default value |
| is 120 seconds. |
| |
| diskSpoolBufferSizeMB: |
| This is the size to allocate the DiskStore for a spool buffer. Writes are made |
| to this area and then asynchronously written to disk. The default size is 30MB. |
| Each spool buffer is used only by its cache. If you get OutOfMemory errors consider |
| lowering this value. To improve DiskStore performance consider increasing it. Trace level |
| logging in the DiskStore will show if put back ups are occurring. |
| |
| clearOnFlush: |
| whether the MemoryStore should be cleared when flush() is called on the cache. |
| By default, this is true i.e. the MemoryStore is cleared. |
| |
| memoryStoreEvictionPolicy: |
| Policy would be enforced upon reaching the maxElementsInMemory limit. Default |
| policy is Least Recently Used (specified as LRU). Other policies available - |
| First In First Out (specified as FIFO) and Less Frequently Used |
| (specified as LFU) |
| |
| Cache elements can also contain sub elements which take the same format of a factory class |
| and properties. Defined sub-elements are: |
| |
| * cacheEventListenerFactory - Enables registration of listeners for cache events, such as |
| put, remove, update, and expire. |
| |
| * bootstrapCacheLoaderFactory - Specifies a BootstrapCacheLoader, which is called by a |
| cache on initialisation to prepopulate itself. |
| |
| * cacheExtensionFactory - Specifies a CacheExtension, a generic mechansim to tie a class |
| which holds a reference to a cache to the cache lifecycle. |
| |
| * cacheExceptionHandlerFactory - Specifies a CacheExceptionHandler, which is called when |
| cache exceptions occur. |
| |
| * cacheLoaderFactory - Specifies a CacheLoader, which can be used both asynchronously and |
| synchronously to load objects into a cache. More than one cacheLoaderFactory element |
| can be added, in which case the loaders form a chain which are executed in order. If a |
| loader returns null, the next in chain is called. |
| |
| RMI Cache Replication |
| +++++++++++++++++++++ |
| |
| Each cache that will be distributed needs to set a cache event listener which replicates |
| messages to the other CacheManager peers. For the built-in RMI implementation this is done |
| by adding a cacheEventListenerFactory element of type RMICacheReplicatorFactory to each |
| distributed cache's configuration as per the following example: |
| |
| <cacheEventListenerFactory class="net.sf.ehcache.distribution.RMICacheReplicatorFactory" |
| properties="replicateAsynchronously=true, |
| replicatePuts=true, |
| replicatePutsViaCopy=false, |
| replicateUpdates=true, |
| replicateUpdatesViaCopy=true, |
| replicateRemovals=true |
| asynchronousReplicationIntervalMillis=<number of milliseconds" |
| propertySeparator="," /> |
| |
| The RMICacheReplicatorFactory recognises the following properties: |
| |
| * replicatePuts=true|false - whether new elements placed in a cache are |
| replicated to others. Defaults to true. |
| |
| * replicatePutsViaCopy=true|false - whether the new elements are |
| copied to other caches (true), or whether a remove message is sent. Defaults to true. |
| |
| * replicateUpdates=true|false - whether new elements which override an |
| element already existing with the same key are replicated. Defaults to true. |
| |
| * replicateRemovals=true - whether element removals are replicated. Defaults to true. |
| |
| * replicateAsynchronously=true | false - whether replications are |
| asynchronous (true) or synchronous (false). Defaults to true. |
| |
| * replicateUpdatesViaCopy=true | false - whether the new elements are |
| copied to other caches (true), or whether a remove message is sent. Defaults to true. |
| |
| * asynchronousReplicationIntervalMillis=<number of milliseconds> - The asynchronous |
| replicator runs at a set interval of milliseconds. The default is 1000. The minimum |
| is 10. This property is only applicable if replicateAsynchronously=true |
| |
| |
| JGroups Replication |
| +++++++++++++++++++ |
| |
| For the Jgroups replication this is done with: |
| <cacheEventListenerFactory class="net.sf.ehcache.distribution.jgroups.JGroupsCacheReplicatorFactory" |
| properties="replicateAsynchronously=true, replicatePuts=true, |
| replicateUpdates=true, replicateUpdatesViaCopy=false, |
| replicateRemovals=true,asynchronousReplicationIntervalMillis=1000"/> |
| This listener supports the same properties as the RMICacheReplicationFactory. |
| |
| |
| JMS Replication |
| +++++++++++++++ |
| |
| For JMS-based replication this is done with: |
| <cacheEventListenerFactory |
| class="net.sf.ehcache.distribution.jms.JMSCacheReplicatorFactory" |
| properties="replicateAsynchronously=true, |
| replicatePuts=true, |
| replicateUpdates=true, |
| replicateUpdatesViaCopy=true, |
| replicateRemovals=true, |
| asynchronousReplicationIntervalMillis=1000" |
| propertySeparator=","/> |
| |
| This listener supports the same properties as the RMICacheReplicationFactory. |
| |
| Cluster Bootstrapping |
| +++++++++++++++++++++ |
| |
| Bootstrapping a cluster may use a different mechanism to replication. e.g you can mix |
| JMS replication with bootstrap via RMI - just make sure you have the cacheManagerPeerProviderFactory |
| and cacheManagerPeerListenerFactory configured. |
| |
| There are two bootstrapping mechanisms: RMI and JGroups. |
| |
| RMI Bootstrap |
| |
| The RMIBootstrapCacheLoader bootstraps caches in clusters where RMICacheReplicators are |
| used. It is configured as per the following example: |
| |
| <bootstrapCacheLoaderFactory |
| class="net.sf.ehcache.distribution.RMIBootstrapCacheLoaderFactory" |
| properties="bootstrapAsynchronously=true, maximumChunkSizeBytes=5000000" |
| propertySeparator="," /> |
| |
| The RMIBootstrapCacheLoaderFactory recognises the following optional properties: |
| |
| * bootstrapAsynchronously=true|false - whether the bootstrap happens in the background |
| after the cache has started. If false, bootstrapping must complete before the cache is |
| made available. The default value is true. |
| |
| * maximumChunkSizeBytes=<integer> - Caches can potentially be very large, larger than the |
| memory limits of the VM. This property allows the bootstraper to fetched elements in |
| chunks. The default chunk size is 5000000 (5MB). |
| |
| JGroups Bootstrap |
| |
| Here is an example of bootstrap configuration using JGroups boostrap: |
| |
| <bootstrapCacheLoaderFactory class="net.sf.ehcache.distribution.jgroups.JGroupsBootstrapCacheLoaderFactory" |
| properties="bootstrapAsynchronously=true"/> |
| |
| The configuration properties are the same as for RMI above. Note that JGroups bootstrap only supports |
| asynchronous bootstrap mode. |
| |
| |
| Cache Exception Handling |
| |
| By default, most cache operations will propagate a runtime CacheException on failure. An |
| interceptor, using a dynamic proxy, may be configured so that a CacheExceptionHandler can |
| be configured to intercept Exceptions. Errors are not intercepted. |
| |
| It is configured as per the following example: |
| |
| <cacheExceptionHandlerFactory class="com.example.ExampleExceptionHandlerFactory" |
| properties="logLevel=FINE"/> |
| |
| Caches with ExceptionHandling configured are not of type Cache, but are of type Ehcache only, |
| and are not available using CacheManager.getCache(), but using CacheManager.getEhcache(). |
| |
| |
| Cache Loader |
| |
| A default CacheLoader may be set which loads objects into the cache through asynchronous and |
| synchronous methods on Cache. This is different to the bootstrap cache loader, which is used |
| only in distributed caching. |
| |
| It is configured as per the following example: |
| |
| <cacheLoaderFactory class="com.example.ExampleCacheLoaderFactory" |
| properties="type=int,startCounter=10"/> |
| |
| Cache Extension |
| |
| CacheExtensions are a general purpose mechanism to allow generic extensions to a Cache. |
| CacheExtensions are tied into the Cache lifecycle. |
| |
| CacheExtensions are created using the CacheExtensionFactory which has a |
| <code>createCacheCacheExtension()</code> method which takes as a parameter a |
| Cache and properties. It can thus call back into any public method on Cache, including, of |
| course, the load methods. |
| |
| Extensions are added as per the following example: |
| |
| <cacheExtensionFactory class="com.example.FileWatchingCacheRefresherExtensionFactory" |
| properties="refreshIntervalMillis=18000, loaderTimeout=3000, |
| flushPeriod=whatever, someOtherProperty=someValue ..."/> |
| |
| --> |
| |
| |
| <!-- |
| Mandatory Default Cache configuration. These settings will be applied to caches |
| created programmtically using CacheManager.add(String cacheName). |
| |
| The defaultCache has an implicit name "default" which is a reserved cache name. |
| --> |
| <defaultCache |
| maxElementsInMemory="10000" |
| eternal="false" |
| timeToIdleSeconds="120" |
| timeToLiveSeconds="120" |
| overflowToDisk="true" |
| diskSpoolBufferSizeMB="30" |
| maxElementsOnDisk="10000000" |
| diskPersistent="false" |
| diskExpiryThreadIntervalSeconds="120" |
| memoryStoreEvictionPolicy="LRU" |
| /> |
| |
| </ehcache> |
