1 <?xml version="1.0" encoding="UTF-8"?>
4 CacheManager Configuration
5 ==========================
6 An ehcache.xml corresponds to a single CacheManager.
8 See instructions below or the ehcache schema (ehcache.xsd) on how to configure.
10 System property tokens can be specified in this file which are replaced when the configuration
11 is loaded. For example multicastGroupPort=${multicastGroupPort} can be replaced with the
12 System property either from an environment variable or a system property specified with a
13 command line switch such as -DmulticastGroupPort=4446.
15 The attributes of <ehcache> are:
16 * name - an optional name for the CacheManager. The name is optional and primarily used
17 for documentation or to distinguish Terracotta clustered cache state. With Terracotta
18 clustered caches, a combination of CacheManager name and cache name uniquely identify a
19 particular cache store in the Terracotta clustered memory.
20 * updateCheck - an optional boolean flag specifying whether this CacheManager should check
21 for new versions of Ehcache over the Internet. If not specified, updateCheck="true".
22 * dynamicConfig - an optional setting that can be used to disable dynamic configuration of caches
23 associated with this CacheManager. By default this is set to true - i.e. dynamic configuration
24 is enabled. Dynamically configurable caches can have their TTI, TTL and maximum disk and
25 in-memory capacity changed at runtime through the cache's configuration object.
26 * monitoring - an optional setting that determines whether the CacheManager should
27 automatically register the SampledCacheMBean with the system MBean server.
29 Currently, this monitoring is only useful when using Terracotta clustering and using the
30 Terracotta Developer Console. With the "autodetect" value, the presence of Terracotta clustering
31 will be detected and monitoring, via the Developer Console, will be enabled. Other allowed values
32 are "on" and "off". The default is "autodetect". This setting does not perform any function when
33 used with JMX monitors.
35 <ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
36 xsi:noNamespaceSchemaLocation="ehcache.xsd"
37 updateCheck="true" monitoring="autodetect"
41 DiskStore configuration
42 =======================
44 The diskStore element is optional. To turn off disk store path creation, comment out the diskStore
47 Configure it if you have overflowToDisk or diskPersistent enabled for any cache.
49 If it is not configured, and a cache is created which requires a disk store, a warning will be
50 issued and java.io.tmpdir will automatically be used.
52 diskStore has only one attribute - "path". It is the path to the directory where
53 .data and .index files will be created.
55 If the path is one of the following Java System Property it is replaced by its value in the
56 running VM. For backward compatibility these should be specified without being enclosed in the ${token}
59 The following properties are translated:
60 * user.home - User's home directory
61 * user.dir - User's current working directory
62 * java.io.tmpdir - Default temp file path
63 * ehcache.disk.store.dir - A system property you would normally specify on the command line
64 e.g. java -Dehcache.disk.store.dir=/u01/myapp/diskdir ...
66 Subdirectories can be specified below the property e.g. java.io.tmpdir/one
69 <diskStore path="java.io.tmpdir"/>
72 TransactionManagerLookup configuration
73 ======================================
74 This class is used by ehcache to lookup the JTA TransactionManager use in the application
75 using an XA enabled ehcache. If no class is specified then DefaultTransactionManagerLookup
76 will find the TransactionManager in the following order
78 *GenericJNDI (i.e. jboss, where the property jndiName controls the name of the TransactionManager object to look up)
83 You can provide you own lookup class that implements the net.sf.ehcache.transaction.manager.TransactionManagerLookup interface.
86 <transactionManagerLookup class="net.sf.ehcache.transaction.manager.DefaultTransactionManagerLookup"
87 properties="jndiName=java:/TransactionManager" propertySeparator=":"/>
91 CacheManagerEventListener
92 =========================
93 Specifies a CacheManagerEventListenerFactory which is notified when Caches are added
94 or removed from the CacheManager.
96 The attributes of CacheManagerEventListenerFactory are:
97 * class - a fully qualified factory class name
98 * properties - comma separated properties having meaning only to the factory.
100 Sets the fully qualified class name to be registered as the CacheManager event listener.
106 Callbacks to listener methods are synchronous and unsynchronized. It is the responsibility
107 of the implementer to safely handle the potential performance and thread safety issues
108 depending on what their listener is doing.
110 If no class is specified, no listener is created. There is no default.
112 <cacheManagerEventListenerFactory class="" properties=""/>
116 CacheManagerPeerProvider
117 ========================
118 (For distributed operation)
120 Specifies a CacheManagerPeerProviderFactory which will be used to create a
121 CacheManagerPeerProvider, which discovers other CacheManagers in the cluster.
123 One or more providers can be configured. The first one in the ehcache.xml is the default, which is used
124 for replication and bootstrapping.
126 The attributes of cacheManagerPeerProviderFactory are:
127 * class - a fully qualified factory class name
128 * properties - comma separated properties having meaning only to the factory.
130 Providers are available for RMI, JGroups and JMS as shown following.
132 RMICacheManagerPeerProvider
133 +++++++++++++++++++++++++++
135 Ehcache comes with a built-in RMI-based distribution system with two means of discovery of
136 CacheManager peers participating in the cluster:
137 * automatic, using a multicast group. This one automatically discovers peers and detects
138 changes such as peers entering and leaving the group
139 * manual, using manual rmiURL configuration. A hardcoded list of peers is provided at
142 Configuring Automatic Discovery:
143 Automatic discovery is configured as per the following example:
144 <cacheManagerPeerProviderFactory
145 class="net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory"
146 properties="hostName=fully_qualified_hostname_or_ip,
147 peerDiscovery=automatic, multicastGroupAddress=230.0.0.1,
148 multicastGroupPort=4446, timeToLive=32"/>
150 Valid properties are:
151 * peerDiscovery (mandatory) - specify "automatic"
152 * multicastGroupAddress (mandatory) - specify a valid multicast group address
153 * multicastGroupPort (mandatory) - specify a dedicated port for the multicast heartbeat
155 * timeToLive - specify a value between 0 and 255 which determines how far the packets will
158 By convention, the restrictions are:
163 128 - the same continent
166 * hostName - the hostname or IP of the interface to be used for sending and receiving multicast packets
167 (relevant to multi-homed hosts only)
169 Configuring Manual Discovery:
170 Manual discovery requires a unique configuration per host. It is contains a list of rmiURLs for the peers, other
171 than itself. So, if we have server1, server2 and server3 the configuration will be:
173 In server1's configuration:
174 <cacheManagerPeerProviderFactory class=
175 "net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory"
176 properties="peerDiscovery=manual,
177 rmiUrls=//server2:40000/sampleCache1|//server3:40000/sampleCache1
178 | //server2:40000/sampleCache2|//server3:40000/sampleCache2"
179 propertySeparator="," />
181 In server2's configuration:
182 <cacheManagerPeerProviderFactory class=
183 "net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory"
184 properties="peerDiscovery=manual,
185 rmiUrls=//server1:40000/sampleCache1|//server3:40000/sampleCache1
186 | //server1:40000/sampleCache2|//server3:40000/sampleCache2"
187 propertySeparator="," />
189 In server3's configuration:
190 <cacheManagerPeerProviderFactory class=
191 "net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory"
192 properties="peerDiscovery=manual,
193 rmiUrls=//server1:40000/sampleCache1|//server2:40000/sampleCache1
194 | //server1:40000/sampleCache2|//server2:40000/sampleCache2"
195 propertySeparator="," />
198 Valid properties are:
199 * peerDiscovery (mandatory) - specify "manual"
200 * rmiUrls (mandatory) - specify a pipe separated list of rmiUrls, in the form
202 * hostname (optional) - the hostname is the hostname of the remote CacheManager peer. The port is the listening
203 port of the RMICacheManagerPeerListener of the remote CacheManager peer.
205 JGroupsCacheManagerPeerProvider
206 +++++++++++++++++++++++++++++++
207 <cacheManagerPeerProviderFactory class="net.sf.ehcache.distribution.jgroups.JGroupsCacheManagerPeerProviderFactory"
208 properties="connect=UDP(mcast_addr=231.12.21.132;mcast_port=45566;ip_ttl=32;
209 mcast_send_buf_size=150000;mcast_recv_buf_size=80000):
210 PING(timeout=2000;num_initial_members=6):
211 MERGE2(min_interval=5000;max_interval=10000):
212 FD_SOCK:VERIFY_SUSPECT(timeout=1500):
213 pbcast.NAKACK(gc_lag=10;retransmit_timeout=3000):
214 UNICAST(timeout=5000):
215 pbcast.STABLE(desired_avg_gossip=20000):
217 pbcast.GMS(join_timeout=5000;join_retry_timeout=2000;shun=false;print_local_addr=false)"
218 propertySeparator="::"
220 The only property necessary is the connect String used by jgroups to configure itself. Refer to the Jgroups documentation for explanation
221 of all the protocols. The example above uses UDP multicast. If the connect property is not specified the default JGroups connection will be
225 JMSCacheManagerPeerProviderFactory
226 ++++++++++++++++++++++++++++++++++
227 <cacheManagerPeerProviderFactory
228 class="net.sf.ehcache.distribution.jms.JMSCacheManagerPeerProviderFactory"
230 propertySeparator=","
233 The JMS PeerProviderFactory uses JNDI to maintain message queue independence. Refer to the manual for full configuration
234 examples using ActiveMQ and Open Message Queue.
236 Valid properties are:
237 * initialContextFactoryName (mandatory) - the name of the factory used to create the message queue initial context.
238 * providerURL (mandatory) - the JNDI configuration information for the service provider to use.
239 * topicConnectionFactoryBindingName (mandatory) - the JNDI binding name for the TopicConnectionFactory
240 * topicBindingName (mandatory) - the JNDI binding name for the topic name
241 * getQueueBindingName (mandatory only if using jmsCacheLoader) - the JNDI binding name for the queue name
242 * securityPrincipalName - the JNDI java.naming.security.principal
243 * securityCredentials - the JNDI java.naming.security.credentials
244 * urlPkgPrefixes - the JNDI java.naming.factory.url.pkgs
245 * userName - the user name to use when creating the TopicConnection to the Message Queue
246 * password - the password to use when creating the TopicConnection to the Message Queue
247 * acknowledgementMode - the JMS Acknowledgement mode for both publisher and subscriber. The available choices are
248 AUTO_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE and SESSION_TRANSACTED. The default is AUTO_ACKNOWLEDGE.
250 <cacheManagerPeerProviderFactory
251 class="net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory"
252 properties="peerDiscovery=automatic,
253 multicastGroupAddress=230.0.0.1,
254 multicastGroupPort=4446, timeToLive=1"
255 propertySeparator=","
260 CacheManagerPeerListener
261 ========================
262 (Enable for distributed operation)
264 Specifies a CacheManagerPeerListenerFactory which will be used to create a
265 CacheManagerPeerListener, which listens for messages from cache replicators participating in the cluster.
267 The attributes of cacheManagerPeerListenerFactory are:
268 class - a fully qualified factory class name
269 properties - comma separated properties having meaning only to the factory.
271 Ehcache comes with a built-in RMI-based distribution system. The listener component is
272 RMICacheManagerPeerListener which is configured using
273 RMICacheManagerPeerListenerFactory. It is configured as per the following example:
275 <cacheManagerPeerListenerFactory
276 class="net.sf.ehcache.distribution.RMICacheManagerPeerListenerFactory"
277 properties="hostName=fully_qualified_hostname_or_ip,
279 remoteObjectPort=40002,
280 socketTimeoutMillis=120000"
281 propertySeparator="," />
283 All properties are optional. They are:
284 * hostName - the hostName of the host the listener is running on. Specify
285 where the host is multihomed and you want to control the interface over which cluster
286 messages are received. Defaults to the host name of the default interface if not
288 * port - the port the RMI Registry listener listens on. This defaults to a free port if not specified.
289 * remoteObjectPort - the port number on which the remote objects bound in the registry receive calls.
290 This defaults to a free port if not specified.
291 * socketTimeoutMillis - the number of ms client sockets will stay open when sending
292 messages to the listener. This should be long enough for the slowest message.
293 If not specified it defaults to 120000ms.
296 <cacheManagerPeerListenerFactory
297 class="net.sf.ehcache.distribution.RMICacheManagerPeerListenerFactory"/>
301 ========================
302 (Enable for Terracotta clustered operation)
304 Note: You need to install and run one or more Terracotta servers to use Terracotta clustering.
305 See http://www.terracotta.org/web/display/orgsite/Download.
307 Specifies a TerracottaConfig which will be used to configure the Terracotta
308 runtime for this CacheManager.
310 Configuration can be specified in two main ways: by reference to a source of
311 configuration or by use of an embedded Terracotta configuration file.
313 To specify a reference to a source (or sources) of configuration, use the url
314 attribute. The url attribute must contain a comma-separated list of:
315 * path to Terracotta configuration file (usually named tc-config.xml)
316 * URL to Terracotta configuration file
317 * <server host>:<port> of running Terracotta Server instance
319 Simplest example for pointing to a Terracotta server on this machine:
320 <terracottaConfig url="localhost:9510"/>
322 Example using a path to Terracotta configuration file:
323 <terracottaConfig url="/app/config/tc-config.xml"/>
325 Example using a URL to a Terracotta configuration file:
326 <terracottaConfig url="http://internal/ehcache/app/tc-config.xml"/>
328 Example using multiple Terracotta server instance URLs (for fault tolerance):
329 <terracottaConfig url="host1:9510,host2:9510,host3:9510"/>
331 To embed a Terracotta configuration file within the ehcache configuration, simply
332 place a normal Terracotta XML config within the <terracottaConfig> element.
338 <server host="server1" name="s1"/>
339 <server host="server2" name="s2"/>
342 <logs>app/logs-%i</logs>
347 For more information on the Terracotta configuration, see the Terracotta documentation.
354 The following attributes are required.
357 Sets the name of the cache. This is used to identify the cache. It must be unique.
360 Sets the maximum number of objects that will be created in memory. 0 == no limit.
363 Sets the maximum number of objects that will be maintained in the DiskStore
364 The default value is zero, meaning unlimited.
367 Sets whether elements are eternal. If eternal, timeouts are ignored and the
368 element is never expired.
371 Sets whether elements can overflow to disk when the memory store
372 has reached the maxInMemory limit.
374 The following attributes and elements are optional.
377 Sets the time to idle for an element before it expires.
378 i.e. The maximum amount of time between accesses before an element expires
379 Is only used if the element is not eternal.
380 Optional attribute. A value of 0 means that an Element can idle for infinity.
381 The default value is 0.
384 Sets the time to live for an element before it expires.
385 i.e. The maximum time between creation time and when an element expires.
386 Is only used if the element is not eternal.
387 Optional attribute. A value of 0 means that and Element can live for infinity.
388 The default value is 0.
391 Whether the disk store persists between restarts of the Virtual Machine.
392 The default value is false.
394 diskExpiryThreadIntervalSeconds:
395 The number of seconds between runs of the disk expiry thread. The default value
398 diskSpoolBufferSizeMB:
399 This is the size to allocate the DiskStore for a spool buffer. Writes are made
400 to this area and then asynchronously written to disk. The default size is 30MB.
401 Each spool buffer is used only by its cache. If you get OutOfMemory errors consider
402 lowering this value. To improve DiskStore performance consider increasing it. Trace level
403 logging in the DiskStore will show if put back ups are occurring.
406 whether the MemoryStore should be cleared when flush() is called on the cache.
407 By default, this is true i.e. the MemoryStore is cleared.
409 memoryStoreEvictionPolicy:
410 Policy would be enforced upon reaching the maxElementsInMemory limit. Default
411 policy is Least Recently Used (specified as LRU). Other policies available -
412 First In First Out (specified as FIFO) and Less Frequently Used
415 Cache elements can also contain sub elements which take the same format of a factory class
416 and properties. Defined sub-elements are:
418 * cacheEventListenerFactory - Enables registration of listeners for cache events, such as
419 put, remove, update, and expire.
421 * bootstrapCacheLoaderFactory - Specifies a BootstrapCacheLoader, which is called by a
422 cache on initialisation to prepopulate itself.
424 * cacheExtensionFactory - Specifies a CacheExtension, a generic mechansim to tie a class
425 which holds a reference to a cache to the cache lifecycle.
427 * cacheExceptionHandlerFactory - Specifies a CacheExceptionHandler, which is called when
428 cache exceptions occur.
430 * cacheLoaderFactory - Specifies a CacheLoader, which can be used both asynchronously and
431 synchronously to load objects into a cache. More than one cacheLoaderFactory element
432 can be added, in which case the loaders form a chain which are executed in order. If a
433 loader returns null, the next in chain is called.
436 Cache Event Listeners
437 +++++++++++++++++++++
439 All cacheEventListenerFactory elements can take an optional property listenFor that describes
440 which events will be delivered in a clustered environment. The listenFor attribute has the
441 following allowed values:
443 * all - the default is to deliver all local and remote events
444 * local - deliver only events originating in the current node
445 * remote - deliver only events originating in other nodes
447 Example of setting up a logging listener for local cache events:
449 <cacheEventListenerFactory class="my.company.log.CacheLogger"
453 RMI Cache Replication
454 +++++++++++++++++++++
456 Each cache that will be distributed needs to set a cache event listener which replicates
457 messages to the other CacheManager peers. For the built-in RMI implementation this is done
458 by adding a cacheEventListenerFactory element of type RMICacheReplicatorFactory to each
459 distributed cache's configuration as per the following example:
461 <cacheEventListenerFactory class="net.sf.ehcache.distribution.RMICacheReplicatorFactory"
462 properties="replicateAsynchronously=true,
464 replicatePutsViaCopy=false,
465 replicateUpdates=true,
466 replicateUpdatesViaCopy=true,
467 replicateRemovals=true
468 asynchronousReplicationIntervalMillis=<number of milliseconds"
469 propertySeparator="," />
471 The RMICacheReplicatorFactory recognises the following properties:
473 * replicatePuts=true|false - whether new elements placed in a cache are
474 replicated to others. Defaults to true.
476 * replicatePutsViaCopy=true|false - whether the new elements are
477 copied to other caches (true), or whether a remove message is sent. Defaults to true.
479 * replicateUpdates=true|false - whether new elements which override an
480 element already existing with the same key are replicated. Defaults to true.
482 * replicateRemovals=true - whether element removals are replicated. Defaults to true.
484 * replicateAsynchronously=true | false - whether replications are
485 asynchronous (true) or synchronous (false). Defaults to true.
487 * replicateUpdatesViaCopy=true | false - whether the new elements are
488 copied to other caches (true), or whether a remove message is sent. Defaults to true.
490 * asynchronousReplicationIntervalMillis=<number of milliseconds> - The asynchronous
491 replicator runs at a set interval of milliseconds. The default is 1000. The minimum
492 is 10. This property is only applicable if replicateAsynchronously=true
498 For the Jgroups replication this is done with:
499 <cacheEventListenerFactory class="net.sf.ehcache.distribution.jgroups.JGroupsCacheReplicatorFactory"
500 properties="replicateAsynchronously=true, replicatePuts=true,
501 replicateUpdates=true, replicateUpdatesViaCopy=false,
502 replicateRemovals=true,asynchronousReplicationIntervalMillis=1000"/>
503 This listener supports the same properties as the RMICacheReplicationFactory.
509 For JMS-based replication this is done with:
510 <cacheEventListenerFactory
511 class="net.sf.ehcache.distribution.jms.JMSCacheReplicatorFactory"
512 properties="replicateAsynchronously=true,
514 replicateUpdates=true,
515 replicateUpdatesViaCopy=true,
516 replicateRemovals=true,
517 asynchronousReplicationIntervalMillis=1000"
518 propertySeparator=","/>
520 This listener supports the same properties as the RMICacheReplicationFactory.
522 Cluster Bootstrapping
523 +++++++++++++++++++++
525 Bootstrapping a cluster may use a different mechanism to replication. e.g you can mix
526 JMS replication with bootstrap via RMI - just make sure you have the cacheManagerPeerProviderFactory
527 and cacheManagerPeerListenerFactory configured.
529 There are two bootstrapping mechanisms: RMI and JGroups.
533 The RMIBootstrapCacheLoader bootstraps caches in clusters where RMICacheReplicators are
534 used. It is configured as per the following example:
536 <bootstrapCacheLoaderFactory
537 class="net.sf.ehcache.distribution.RMIBootstrapCacheLoaderFactory"
538 properties="bootstrapAsynchronously=true, maximumChunkSizeBytes=5000000"
539 propertySeparator="," />
541 The RMIBootstrapCacheLoaderFactory recognises the following optional properties:
543 * bootstrapAsynchronously=true|false - whether the bootstrap happens in the background
544 after the cache has started. If false, bootstrapping must complete before the cache is
545 made available. The default value is true.
547 * maximumChunkSizeBytes=<integer> - Caches can potentially be very large, larger than the
548 memory limits of the VM. This property allows the bootstraper to fetched elements in
549 chunks. The default chunk size is 5000000 (5MB).
553 Here is an example of bootstrap configuration using JGroups boostrap:
555 <bootstrapCacheLoaderFactory class="net.sf.ehcache.distribution.jgroups.JGroupsBootstrapCacheLoaderFactory"
556 properties="bootstrapAsynchronously=true"/>
558 The configuration properties are the same as for RMI above. Note that JGroups bootstrap only supports
559 asynchronous bootstrap mode.
562 Cache Exception Handling
563 ++++++++++++++++++++++++
565 By default, most cache operations will propagate a runtime CacheException on failure. An
566 interceptor, using a dynamic proxy, may be configured so that a CacheExceptionHandler can
567 be configured to intercept Exceptions. Errors are not intercepted.
569 It is configured as per the following example:
571 <cacheExceptionHandlerFactory class="com.example.ExampleExceptionHandlerFactory"
572 properties="logLevel=FINE"/>
574 Caches with ExceptionHandling configured are not of type Cache, but are of type Ehcache only,
575 and are not available using CacheManager.getCache(), but using CacheManager.getEhcache().
581 A default CacheLoader may be set which loads objects into the cache through asynchronous and
582 synchronous methods on Cache. This is different to the bootstrap cache loader, which is used
583 only in distributed caching.
585 It is configured as per the following example:
587 <cacheLoaderFactory class="com.example.ExampleCacheLoaderFactory"
588 properties="type=int,startCounter=10"/>
593 To enable an ehcache as a participant in the JTA Transaction, just have the following attribute
595 transactionalMode="xa", otherwise the default is transactionalMode="off"
600 A CacheWriter maybe be set to write to an underlying resource. Only one CacheWriter can be
603 It is configured as per the following example for write-through:
605 <cacheWriter writeMode="write-through" notifyListenersOnException="true">
606 <cacheWriterFactory class="net.sf.ehcache.writer.TestCacheWriterFactory"
607 properties="type=int,startCounter=10"/>
610 And it is configured as per the following example for write-behind:
612 <cacheWriter writeMode="write-behind" minWriteDelay="1" maxWriteDelay="5"
613 rateLimitPerSecond="5" writeCoalescing="true" writeBatching="true" writeBatchSize="1"
614 retryAttempts="2" retryAttemptDelaySeconds="1">
615 <cacheWriterFactory class="net.sf.ehcache.writer.TestCacheWriterFactory"
616 properties="type=int,startCounter=10"/>
619 The cacheWriter element has the following attributes:
620 * writeMode: the write mode, write-through or write-behind
622 These attributes only apply to write-through mode:
623 * notifyListenersOnException: Sets whether to notify listeners when an exception occurs on a writer operation.
625 These attributes only apply to write-behind mode:
626 * minWriteDelay: Set the minimum number of seconds to wait before writing behind. If set to a value greater than 0,
627 it permits operations to build up in the queue. This is different from the maximum write delay in that by waiting
628 a minimum amount of time, work is always being built up. If the minimum write delay is set to zero and the
629 CacheWriter performs its work very quickly, the overhead of processing the write behind queue items becomes very
630 noticeable in a cluster since all the operations might be done for individual items instead of for a collection
632 * maxWriteDelay: Set the maximum number of seconds to wait before writing behind. If set to a value greater than 0,
633 it permits operations to build up in the queue to enable effective coalescing and batching optimisations.
634 * writeBatching: Sets whether to batch write operations. If set to true, writeAll and deleteAll will be called on
635 the CacheWriter rather than write and delete being called for each key. Resources such as databases can perform
636 more efficiently if updates are batched, thus reducing load.
637 * writeBatchSize: Sets the number of operations to include in each batch when writeBatching is enabled. If there are
638 less entries in the write-behind queue than the batch size, the queue length size is used.
639 * rateLimitPerSecond: Sets the maximum number of write operations to allow per second when writeBatching is enabled.
640 * writeCoalescing: Sets whether to use write coalescing. If set to true and multiple operations on the same key are
641 present in the write-behind queue, only the latest write is done, as the others are redundant.
642 * retryAttempts: Sets the number of times the operation is retried in the CacheWriter, this happens after the
644 * retryAttemptDelaySeconds: Sets the number of seconds to wait before retrying an failed operation.
649 CacheExtensions are a general purpose mechanism to allow generic extensions to a Cache.
650 CacheExtensions are tied into the Cache lifecycle.
652 CacheExtensions are created using the CacheExtensionFactory which has a
653 <code>createCacheCacheExtension()</code> method which takes as a parameter a
654 Cache and properties. It can thus call back into any public method on Cache, including, of
655 course, the load methods.
657 Extensions are added as per the following example:
659 <cacheExtensionFactory class="com.example.FileWatchingCacheRefresherExtensionFactory"
660 properties="refreshIntervalMillis=18000, loaderTimeout=3000,
661 flushPeriod=whatever, someOtherProperty=someValue ..."/>
663 Terracotta Clustering
664 +++++++++++++++++++++
666 Cache elements can also contain information about whether the cache can be clustered with Terracotta.
667 The <terracotta> sub-element has the following attributes:
669 * clustered=true|false - indicates whether this cache should be clustered with Terracotta. By
670 default, if the <terracotta> element is included, clustered=true.
672 * valueMode=serialization|identity - indicates whether this cache should be clustered with
673 serialized copies of the values or using Terracotta identity mode. By default, values will
674 be cached in serialization mode which is similar to other replicated Ehcache modes. The identity
675 mode is only available in certain Terracotta deployment scenarios and will maintain actual object
676 identity of the keys and values across the cluster. In this case, all users of a value retrieved from
677 the cache are using the same clustered value and must provide appropriate locking for any changes
678 made to the value (or objects referred to by the value).
680 * copyOnRead=true|false - indicates whether cache values are deserialized on every read or if the
681 materialized cache value can be re-used between get() calls. This setting is useful if a cache
682 is being shared by callers with disparate classloaders or to prevent local drift if keys/values
683 are mutated locally w/o putting back to the cache. NOTE: This setting is only relevant for caches
684 with valueMode=serialization
686 * coherent=true|false - indicates whether this cache should have coherent reads and writes with guaranteed
687 consistency across the cluster. By default, its value is true. If this attribute is set to false
688 (or "incoherent" mode), values from the cache are read without locking, possibly yielding stale data.
689 Writes to a cache in incoherent mode are batched and applied without acquiring cluster-wide locks,
690 possibly creating inconsistent values across cluster. Incoherent mode is a performance optimization
691 with weaker concurrency guarantees and should generally be used for bulk-loading caches, for loading
692 a read-only cache, or where the application that can tolerate reading stale data. This setting overrides
693 coherentReads, which is deprecated.
695 * synchronousWrites=true|false - When set to true, clustered caches use
696 Terracotta SYNCHRONOUS WRITE locks. Asynchronous writes (synchronousWrites="false") maximize performance by
697 allowing clients to proceed without waiting for a "transaction received" acknowledgement from the server.
698 Synchronous writes (synchronousWrites="true") maximize data safety by requiring that a client receive server
699 acknowledgement of a transaction before that client can proceed. If coherence mode is disabled using
700 configuration (coherent="false") or through the coherence API, only asynchronous writes can occur
701 (synchronousWrites="true" is ignored). By default this value is false (i.e. clustered caches use normal
702 Terracotta WRITE locks).
704 Simplest example to indicate clustering:
707 To indicate the cache should not be clustered (or remove the <terracotta> element altogether):
708 <terracotta clustered="false"/>
710 To indicate the cache should be clustered using identity mode:
711 <terracotta clustered="true" valueMode="identity"/>
713 To indicate the cache should be clustered using incoherent mode for bulk load:
714 <terracotta clustered="true" coherent="false"/>
716 To indicate the cache should be clustered using synchronous-write locking level:
717 <terracotta clustered="true" synchronousWrites="true"/>
722 Mandatory Default Cache configuration. These settings will be applied to caches
723 created programmtically using CacheManager.add(String cacheName).
725 The defaultCache has an implicit name "default" which is a reserved cache name.
728 maxElementsInMemory="10000"
730 timeToIdleSeconds="120"
731 timeToLiveSeconds="120"
732 overflowToDisk="true"
733 diskSpoolBufferSizeMB="30"
734 maxElementsOnDisk="10000000"
735 diskPersistent="false"
736 diskExpiryThreadIntervalSeconds="120"
737 memoryStoreEvictionPolicy="LRU"
741 Sample caches. Following are some example caches. Remove these before use.
745 Sample cache named sampleCache1
746 This cache contains a maximum in memory of 10000 elements, and will expire
747 an element if it is idle for more than 5 minutes and lives for more than
750 If there are more than 10000 elements it will overflow to the
751 disk cache, which in this configuration will go to wherever java.io.tmp is
752 defined on your system. On a standard Linux system this will be /tmp"
755 <cache name="sampleCache1"
756 maxElementsInMemory="10000"
757 maxElementsOnDisk="1000"
759 overflowToDisk="true"
760 diskSpoolBufferSizeMB="20"
761 timeToIdleSeconds="300"
762 timeToLiveSeconds="600"
763 memoryStoreEvictionPolicy="LFU"
764 transactionalMode="off"
770 Sample cache named sampleCache2
771 This cache has a maximum of 1000 elements in memory. There is no overflow to disk, so 1000
772 is also the maximum cache size. Note that when a cache is eternal, timeToLive and
773 timeToIdle are not used and do not need to be specified.
776 <cache name="sampleCache2"
777 maxElementsInMemory="1000"
779 overflowToDisk="false"
780 memoryStoreEvictionPolicy="FIFO"
786 Sample cache named sampleCache3. This cache overflows to disk. The disk store is
787 persistent between cache and VM restarts. The disk expiry thread interval is set to 10
788 minutes, overriding the default of 2 minutes.
791 <cache name="sampleCache3"
792 maxElementsInMemory="500"
794 overflowToDisk="true"
795 timeToIdleSeconds="300"
796 timeToLiveSeconds="600"
797 diskPersistent="true"
798 diskExpiryThreadIntervalSeconds="1"
799 memoryStoreEvictionPolicy="LFU"
805 Sample distributed cache named sampleDistributedCache1.
806 This cache replicates using defaults.
807 It also bootstraps from the cluster, using default properties.
810 <cache name="sampleDistributedCache1"
811 maxElementsInMemory="10"
813 timeToIdleSeconds="100"
814 timeToLiveSeconds="100"
815 overflowToDisk="false">
817 <cacheEventListenerFactory
818 class="net.sf.ehcache.distribution.RMICacheReplicatorFactory"/>
819 <bootstrapCacheLoaderFactory
820 class="net.sf.ehcache.distribution.RMIBootstrapCacheLoaderFactory"/>
826 Sample distributed cache named sampleDistributedCache2.
827 This cache replicates using specific properties.
828 It only replicates updates and does so synchronously via copy
831 <cache name="sampleDistributedCache2"
832 maxElementsInMemory="10"
834 timeToIdleSeconds="100"
835 timeToLiveSeconds="100"
836 overflowToDisk="false">
837 <cacheEventListenerFactory
838 class="net.sf.ehcache.distribution.RMICacheReplicatorFactory"
839 properties="replicateAsynchronously=false, replicatePuts=false,
840 replicatePutsViaCopy=false, replicateUpdates=true,
841 replicateUpdatesViaCopy=true, replicateRemovals=false"/>
846 Sample distributed cache named sampleDistributedCache3.
847 This cache replicates using defaults except that the asynchronous replication
848 interval is set to 200ms.
849 This one includes / and # which were illegal in ehcache 1.5.
852 <cache name="sample/DistributedCache3"
853 maxElementsInMemory="10"
855 timeToIdleSeconds="100"
856 timeToLiveSeconds="100"
857 overflowToDisk="true">
858 <cacheEventListenerFactory
859 class="net.sf.ehcache.distribution.RMICacheReplicatorFactory"
860 properties="asynchronousReplicationIntervalMillis=200"/>
865 Sample Terracotta clustered cache named sampleTerracottaCache.
866 This cache uses Terracotta to cluster the contents of the cache.
869 <cache name="sampleTerracottaCache"
870 maxElementsInMemory="1000"
872 timeToIdleSeconds="3600"
873 timeToLiveSeconds="1800"
874 overflowToDisk="false">
880 Sample xa enabled cache name xaCache
883 <cache name="xaCache"
884 maxElementsInMemory="500"
886 timeToIdleSeconds="300"
887 timeToLiveSeconds="600"
888 overflowToDisk="false"
889 diskPersistent="false"
890 diskExpiryThreadIntervalSeconds="1"
891 transactionalMode="xa">
892 <terracotta clustered="true"/>