| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| <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, be used to create a CacheManagerPeerProvider, |
| 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 |
| ======================== |
| (Enable for distributed operation) |
| |
| Specifies a CacheManagerPeerProviderFactory which will be used to create a |
| CacheManagerPeerProvider, which discovers other CacheManagers in the cluster. |
| |
| The attributes of cacheManagerPeerProviderFactory 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 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. |
| |
| Configuring JGroups replication: |
| <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 necessay 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. |
| |
| --> |
| |
| <!-- |
| 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, |
| 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 120000ms. |
| |
| --> |
| |
| <!-- |
| 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. |
| |
| 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. |
| |
| 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, |
| 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. |
| |
| * 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 |
| |
| |
| 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 property than the RMICacheReplicationFactory. |
| |
| Cluster Bootstrapping |
| |
| 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). |
| |
| |
| 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="false" |
| diskSpoolBufferSizeMB="30" |
| maxElementsOnDisk="10000000" |
| diskPersistent="false" |
| diskExpiryThreadIntervalSeconds="120" |
| memoryStoreEvictionPolicy="LRU" |
| /> |
| |
| <!-- |
| Sample caches. Following are some example caches. Remove these before use. |
| --> |
| |
| <!-- |
| Sample cache named sampleCache1 |
| This cache contains a maximum in memory of 10000 elements, and will expire |
| an element if it is idle for more than 5 minutes and lives for more than |
| 10 minutes. |
| |
| If there are more than 10000 elements it will overflow to the |
| disk cache, which in this configuration will go to wherever java.io.tmp is |
| defined on your system. On a standard Linux system this will be /tmp" |
| --> |
| <!-- |
| <cache name="sampleCache1" |
| maxElementsInMemory="10000" |
| maxElementsOnDisk="1000" |
| eternal="false" |
| overflowToDisk="true" |
| diskSpoolBufferSizeMB="20" |
| timeToIdleSeconds="300" |
| timeToLiveSeconds="600" |
| memoryStoreEvictionPolicy="LFU" |
| /> |
| --> |
| |
| |
| <!-- |
| Sample cache named sampleCache2 |
| This cache has a maximum of 1000 elements in memory. There is no overflow to disk, so 1000 |
| is also the maximum cache size. Note that when a cache is eternal, timeToLive and |
| timeToIdle are not used and do not need to be specified. |
| --> |
| <!-- |
| <cache name="sampleCache2" |
| maxElementsInMemory="1000" |
| eternal="true" |
| overflowToDisk="false" |
| memoryStoreEvictionPolicy="FIFO" |
| /> |
| --> |
| |
| |
| <!-- |
| Sample cache named sampleCache3. This cache overflows to disk. The disk store is |
| persistent between cache and VM restarts. The disk expiry thread interval is set to 10 |
| minutes, overriding the default of 2 minutes. |
| --> |
| <!-- |
| <cache name="sampleCache3" |
| maxElementsInMemory="500" |
| eternal="false" |
| overflowToDisk="true" |
| timeToIdleSeconds="300" |
| timeToLiveSeconds="600" |
| diskPersistent="true" |
| diskExpiryThreadIntervalSeconds="1" |
| memoryStoreEvictionPolicy="LFU" |
| /> |
| --> |
| |
| |
| <!-- |
| Sample distributed cache named sampleDistributedCache1. |
| This cache replicates using defaults. |
| It also bootstraps from the cluster, using default properties. |
| --> |
| <!-- |
| <cache name="sampleDistributedCache1" |
| maxElementsInMemory="10" |
| eternal="false" |
| timeToIdleSeconds="100" |
| timeToLiveSeconds="100" |
| overflowToDisk="false"> |
| <cacheEventListenerFactory |
| class="net.sf.ehcache.distribution.RMICacheReplicatorFactory"/> |
| <bootstrapCacheLoaderFactory |
| class="net.sf.ehcache.distribution.RMIBootstrapCacheLoaderFactory"/> |
| </cache> |
| --> |
| |
| |
| <!-- |
| Sample distributed cache named sampleDistributedCache2. |
| This cache replicates using specific properties. |
| It only replicates updates and does so synchronously via copy |
| --> |
| <!-- |
| <cache name="sampleDistributedCache2" |
| maxElementsInMemory="10" |
| eternal="false" |
| timeToIdleSeconds="100" |
| timeToLiveSeconds="100" |
| overflowToDisk="false"> |
| <cacheEventListenerFactory |
| class="net.sf.ehcache.distribution.RMICacheReplicatorFactory" |
| properties="replicateAsynchronously=false, replicatePuts=false, |
| replicateUpdates=true, replicateUpdatesViaCopy=true, |
| replicateRemovals=false"/> |
| </cache> |
| --> |
| |
| <!-- |
| Sample distributed cache named sampleDistributedCache3. |
| This cache replicates using defaults except that the asynchronous replication |
| interval is set to 200ms. |
| --> |
| <!-- |
| <cache name="sampleDistributedCache3" |
| maxElementsInMemory="10" |
| eternal="false" |
| timeToIdleSeconds="100" |
| timeToLiveSeconds="100" |
| overflowToDisk="false"> |
| <cacheEventListenerFactory |
| class="net.sf.ehcache.distribution.RMICacheReplicatorFactory" |
| properties="asynchronousReplicationIntervalMillis=200"/> |
| </cache> |
| --> |
| |
| </ehcache> |