root / ear / ehcache.xml @ 023f6f1e
History | View | Annotate | Download (40.2 kB)
1 |
<?xml version="1.0" encoding="UTF-8"?>
|
---|---|
2 |
|
3 |
<!--
|
4 |
CacheManager Configuration
|
5 |
==========================
|
6 |
An ehcache.xml corresponds to a single CacheManager.
|
7 |
|
8 |
See instructions below or the ehcache schema (ehcache.xsd) on how to configure.
|
9 |
|
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.
|
14 |
|
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.
|
28 |
|
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.
|
34 |
-->
|
35 |
<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
36 |
xsi:noNamespaceSchemaLocation="ehcache.xsd" |
37 |
updateCheck="true" monitoring="autodetect" |
38 |
dynamicConfig="true"> |
39 |
|
40 |
<!--
|
41 |
DiskStore configuration
|
42 |
=======================
|
43 |
|
44 |
The diskStore element is optional. To turn off disk store path creation, comment out the diskStore
|
45 |
element below.
|
46 |
|
47 |
Configure it if you have overflowToDisk or diskPersistent enabled for any cache.
|
48 |
|
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.
|
51 |
|
52 |
diskStore has only one attribute - "path". It is the path to the directory where
|
53 |
.data and .index files will be created.
|
54 |
|
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}
|
57 |
replacement syntax.
|
58 |
|
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 ...
|
65 |
|
66 |
Subdirectories can be specified below the property e.g. java.io.tmpdir/one
|
67 |
|
68 |
-->
|
69 |
<diskStore path="java.io.tmpdir"/> |
70 |
|
71 |
<!--
|
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
|
77 |
|
78 |
*GenericJNDI (i.e. jboss, where the property jndiName controls the name of the TransactionManager object to look up)
|
79 |
*Websphere
|
80 |
*Bitronix
|
81 |
*Atomikos
|
82 |
|
83 |
You can provide you own lookup class that implements the net.sf.ehcache.transaction.manager.TransactionManagerLookup interface.
|
84 |
-->
|
85 |
|
86 |
<transactionManagerLookup class="net.sf.ehcache.transaction.manager.DefaultTransactionManagerLookup" |
87 |
properties="jndiName=java:/TransactionManager" propertySeparator=":"/> |
88 |
|
89 |
|
90 |
<!--
|
91 |
CacheManagerEventListener
|
92 |
=========================
|
93 |
Specifies a CacheManagerEventListenerFactory which is notified when Caches are added
|
94 |
or removed from the CacheManager.
|
95 |
|
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.
|
99 |
|
100 |
Sets the fully qualified class name to be registered as the CacheManager event listener.
|
101 |
|
102 |
The events include:
|
103 |
* adding a Cache
|
104 |
* removing a Cache
|
105 |
|
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.
|
109 |
|
110 |
If no class is specified, no listener is created. There is no default.
|
111 |
-->
|
112 |
<cacheManagerEventListenerFactory class="" properties=""/> |
113 |
|
114 |
|
115 |
<!--
|
116 |
CacheManagerPeerProvider
|
117 |
========================
|
118 |
(For distributed operation)
|
119 |
|
120 |
Specifies a CacheManagerPeerProviderFactory which will be used to create a
|
121 |
CacheManagerPeerProvider, which discovers other CacheManagers in the cluster.
|
122 |
|
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.
|
125 |
|
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.
|
129 |
|
130 |
Providers are available for RMI, JGroups and JMS as shown following.
|
131 |
|
132 |
RMICacheManagerPeerProvider
|
133 |
+++++++++++++++++++++++++++
|
134 |
|
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
|
140 |
configuration time.
|
141 |
|
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"/>
|
149 |
|
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
|
154 |
traffic
|
155 |
* timeToLive - specify a value between 0 and 255 which determines how far the packets will
|
156 |
propagate.
|
157 |
|
158 |
By convention, the restrictions are:
|
159 |
0 - the same host
|
160 |
1 - the same subnet
|
161 |
32 - the same site
|
162 |
64 - the same region
|
163 |
128 - the same continent
|
164 |
255 - unrestricted
|
165 |
|
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)
|
168 |
|
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:
|
172 |
|
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="," />
|
180 |
|
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="," />
|
188 |
|
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="," />
|
196 |
|
197 |
|
198 |
Valid properties are:
|
199 |
* peerDiscovery (mandatory) - specify "manual"
|
200 |
* rmiUrls (mandatory) - specify a pipe separated list of rmiUrls, in the form
|
201 |
//hostname:port
|
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.
|
204 |
|
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):
|
216 |
FRAG:
|
217 |
pbcast.GMS(join_timeout=5000;join_retry_timeout=2000;shun=false;print_local_addr=false)"
|
218 |
propertySeparator="::"
|
219 |
/>
|
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
|
222 |
used.
|
223 |
|
224 |
|
225 |
JMSCacheManagerPeerProviderFactory
|
226 |
++++++++++++++++++++++++++++++++++
|
227 |
<cacheManagerPeerProviderFactory
|
228 |
class="net.sf.ehcache.distribution.jms.JMSCacheManagerPeerProviderFactory"
|
229 |
properties="..."
|
230 |
propertySeparator=","
|
231 |
/>
|
232 |
|
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.
|
235 |
|
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.
|
249 |
-->
|
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="," |
256 |
/>
|
257 |
|
258 |
|
259 |
<!--
|
260 |
CacheManagerPeerListener
|
261 |
========================
|
262 |
(Enable for distributed operation)
|
263 |
|
264 |
Specifies a CacheManagerPeerListenerFactory which will be used to create a
|
265 |
CacheManagerPeerListener, which listens for messages from cache replicators participating in the cluster.
|
266 |
|
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.
|
270 |
|
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:
|
274 |
|
275 |
<cacheManagerPeerListenerFactory
|
276 |
class="net.sf.ehcache.distribution.RMICacheManagerPeerListenerFactory"
|
277 |
properties="hostName=fully_qualified_hostname_or_ip,
|
278 |
port=40001,
|
279 |
remoteObjectPort=40002,
|
280 |
socketTimeoutMillis=120000"
|
281 |
propertySeparator="," />
|
282 |
|
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
|
287 |
specified.
|
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.
|
294 |
|
295 |
-->
|
296 |
<cacheManagerPeerListenerFactory
|
297 |
class="net.sf.ehcache.distribution.RMICacheManagerPeerListenerFactory"/> |
298 |
|
299 |
<!--
|
300 |
TerracottaConfig
|
301 |
========================
|
302 |
(Enable for Terracotta clustered operation)
|
303 |
|
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.
|
306 |
|
307 |
Specifies a TerracottaConfig which will be used to configure the Terracotta
|
308 |
runtime for this CacheManager.
|
309 |
|
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.
|
312 |
|
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
|
318 |
|
319 |
Simplest example for pointing to a Terracotta server on this machine:
|
320 |
<terracottaConfig url="localhost:9510"/>
|
321 |
|
322 |
Example using a path to Terracotta configuration file:
|
323 |
<terracottaConfig url="/app/config/tc-config.xml"/>
|
324 |
|
325 |
Example using a URL to a Terracotta configuration file:
|
326 |
<terracottaConfig url="http://internal/ehcache/app/tc-config.xml"/>
|
327 |
|
328 |
Example using multiple Terracotta server instance URLs (for fault tolerance):
|
329 |
<terracottaConfig url="host1:9510,host2:9510,host3:9510"/>
|
330 |
|
331 |
To embed a Terracotta configuration file within the ehcache configuration, simply
|
332 |
place a normal Terracotta XML config within the <terracottaConfig> element.
|
333 |
|
334 |
Example:
|
335 |
<terracottaConfig>
|
336 |
<tc-config>
|
337 |
<servers>
|
338 |
<server host="server1" name="s1"/>
|
339 |
<server host="server2" name="s2"/>
|
340 |
</servers>
|
341 |
<clients>
|
342 |
<logs>app/logs-%i</logs>
|
343 |
</clients>
|
344 |
</tc-config>
|
345 |
</terracottaConfig>
|
346 |
|
347 |
For more information on the Terracotta configuration, see the Terracotta documentation.
|
348 |
-->
|
349 |
|
350 |
<!--
|
351 |
Cache configuration
|
352 |
===================
|
353 |
|
354 |
The following attributes are required.
|
355 |
|
356 |
name:
|
357 |
Sets the name of the cache. This is used to identify the cache. It must be unique.
|
358 |
|
359 |
maxElementsInMemory:
|
360 |
Sets the maximum number of objects that will be created in memory. 0 == no limit.
|
361 |
|
362 |
maxElementsOnDisk:
|
363 |
Sets the maximum number of objects that will be maintained in the DiskStore
|
364 |
The default value is zero, meaning unlimited.
|
365 |
|
366 |
eternal:
|
367 |
Sets whether elements are eternal. If eternal, timeouts are ignored and the
|
368 |
element is never expired.
|
369 |
|
370 |
overflowToDisk:
|
371 |
Sets whether elements can overflow to disk when the memory store
|
372 |
has reached the maxInMemory limit.
|
373 |
|
374 |
The following attributes and elements are optional.
|
375 |
|
376 |
timeToIdleSeconds:
|
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.
|
382 |
|
383 |
timeToLiveSeconds:
|
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.
|
389 |
|
390 |
diskPersistent:
|
391 |
Whether the disk store persists between restarts of the Virtual Machine.
|
392 |
The default value is false.
|
393 |
|
394 |
diskExpiryThreadIntervalSeconds:
|
395 |
The number of seconds between runs of the disk expiry thread. The default value
|
396 |
is 120 seconds.
|
397 |
|
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.
|
404 |
|
405 |
clearOnFlush:
|
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.
|
408 |
|
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
|
413 |
(specified as LFU)
|
414 |
|
415 |
Cache elements can also contain sub elements which take the same format of a factory class
|
416 |
and properties. Defined sub-elements are:
|
417 |
|
418 |
* cacheEventListenerFactory - Enables registration of listeners for cache events, such as
|
419 |
put, remove, update, and expire.
|
420 |
|
421 |
* bootstrapCacheLoaderFactory - Specifies a BootstrapCacheLoader, which is called by a
|
422 |
cache on initialisation to prepopulate itself.
|
423 |
|
424 |
* cacheExtensionFactory - Specifies a CacheExtension, a generic mechansim to tie a class
|
425 |
which holds a reference to a cache to the cache lifecycle.
|
426 |
|
427 |
* cacheExceptionHandlerFactory - Specifies a CacheExceptionHandler, which is called when
|
428 |
cache exceptions occur.
|
429 |
|
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.
|
434 |
|
435 |
|
436 |
Cache Event Listeners
|
437 |
+++++++++++++++++++++
|
438 |
|
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:
|
442 |
|
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
|
446 |
|
447 |
Example of setting up a logging listener for local cache events:
|
448 |
|
449 |
<cacheEventListenerFactory class="my.company.log.CacheLogger"
|
450 |
listenFor="local" />
|
451 |
|
452 |
|
453 |
RMI Cache Replication
|
454 |
+++++++++++++++++++++
|
455 |
|
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:
|
460 |
|
461 |
<cacheEventListenerFactory class="net.sf.ehcache.distribution.RMICacheReplicatorFactory"
|
462 |
properties="replicateAsynchronously=true,
|
463 |
replicatePuts=true,
|
464 |
replicatePutsViaCopy=false,
|
465 |
replicateUpdates=true,
|
466 |
replicateUpdatesViaCopy=true,
|
467 |
replicateRemovals=true
|
468 |
asynchronousReplicationIntervalMillis=<number of milliseconds"
|
469 |
propertySeparator="," />
|
470 |
|
471 |
The RMICacheReplicatorFactory recognises the following properties:
|
472 |
|
473 |
* replicatePuts=true|false - whether new elements placed in a cache are
|
474 |
replicated to others. Defaults to true.
|
475 |
|
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.
|
478 |
|
479 |
* replicateUpdates=true|false - whether new elements which override an
|
480 |
element already existing with the same key are replicated. Defaults to true.
|
481 |
|
482 |
* replicateRemovals=true - whether element removals are replicated. Defaults to true.
|
483 |
|
484 |
* replicateAsynchronously=true | false - whether replications are
|
485 |
asynchronous (true) or synchronous (false). Defaults to true.
|
486 |
|
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.
|
489 |
|
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
|
493 |
|
494 |
|
495 |
JGroups Replication
|
496 |
+++++++++++++++++++
|
497 |
|
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.
|
504 |
|
505 |
|
506 |
JMS Replication
|
507 |
+++++++++++++++
|
508 |
|
509 |
For JMS-based replication this is done with:
|
510 |
<cacheEventListenerFactory
|
511 |
class="net.sf.ehcache.distribution.jms.JMSCacheReplicatorFactory"
|
512 |
properties="replicateAsynchronously=true,
|
513 |
replicatePuts=true,
|
514 |
replicateUpdates=true,
|
515 |
replicateUpdatesViaCopy=true,
|
516 |
replicateRemovals=true,
|
517 |
asynchronousReplicationIntervalMillis=1000"
|
518 |
propertySeparator=","/>
|
519 |
|
520 |
This listener supports the same properties as the RMICacheReplicationFactory.
|
521 |
|
522 |
Cluster Bootstrapping
|
523 |
+++++++++++++++++++++
|
524 |
|
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.
|
528 |
|
529 |
There are two bootstrapping mechanisms: RMI and JGroups.
|
530 |
|
531 |
RMI Bootstrap
|
532 |
|
533 |
The RMIBootstrapCacheLoader bootstraps caches in clusters where RMICacheReplicators are
|
534 |
used. It is configured as per the following example:
|
535 |
|
536 |
<bootstrapCacheLoaderFactory
|
537 |
class="net.sf.ehcache.distribution.RMIBootstrapCacheLoaderFactory"
|
538 |
properties="bootstrapAsynchronously=true, maximumChunkSizeBytes=5000000"
|
539 |
propertySeparator="," />
|
540 |
|
541 |
The RMIBootstrapCacheLoaderFactory recognises the following optional properties:
|
542 |
|
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.
|
546 |
|
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).
|
550 |
|
551 |
JGroups Bootstrap
|
552 |
|
553 |
Here is an example of bootstrap configuration using JGroups boostrap:
|
554 |
|
555 |
<bootstrapCacheLoaderFactory class="net.sf.ehcache.distribution.jgroups.JGroupsBootstrapCacheLoaderFactory"
|
556 |
properties="bootstrapAsynchronously=true"/>
|
557 |
|
558 |
The configuration properties are the same as for RMI above. Note that JGroups bootstrap only supports
|
559 |
asynchronous bootstrap mode.
|
560 |
|
561 |
|
562 |
Cache Exception Handling
|
563 |
++++++++++++++++++++++++
|
564 |
|
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.
|
568 |
|
569 |
It is configured as per the following example:
|
570 |
|
571 |
<cacheExceptionHandlerFactory class="com.example.ExampleExceptionHandlerFactory"
|
572 |
properties="logLevel=FINE"/>
|
573 |
|
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().
|
576 |
|
577 |
|
578 |
Cache Loader
|
579 |
++++++++++++
|
580 |
|
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.
|
584 |
|
585 |
It is configured as per the following example:
|
586 |
|
587 |
<cacheLoaderFactory class="com.example.ExampleCacheLoaderFactory"
|
588 |
properties="type=int,startCounter=10"/>
|
589 |
|
590 |
XA Cache
|
591 |
++++++++
|
592 |
|
593 |
To enable an ehcache as a participant in the JTA Transaction, just have the following attribute
|
594 |
|
595 |
transactionalMode="xa", otherwise the default is transactionalMode="off"
|
596 |
|
597 |
Cache Writer
|
598 |
++++++++++++
|
599 |
|
600 |
A CacheWriter maybe be set to write to an underlying resource. Only one CacheWriter can be
|
601 |
been to a cache.
|
602 |
|
603 |
It is configured as per the following example for write-through:
|
604 |
|
605 |
<cacheWriter writeMode="write-through" notifyListenersOnException="true">
|
606 |
<cacheWriterFactory class="net.sf.ehcache.writer.TestCacheWriterFactory"
|
607 |
properties="type=int,startCounter=10"/>
|
608 |
</cacheWriter>
|
609 |
|
610 |
And it is configured as per the following example for write-behind:
|
611 |
|
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"/>
|
617 |
</cacheWriter>
|
618 |
|
619 |
The cacheWriter element has the following attributes:
|
620 |
* writeMode: the write mode, write-through or write-behind
|
621 |
|
622 |
These attributes only apply to write-through mode:
|
623 |
* notifyListenersOnException: Sets whether to notify listeners when an exception occurs on a writer operation.
|
624 |
|
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
|
631 |
of them.
|
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
|
643 |
original operation.
|
644 |
* retryAttemptDelaySeconds: Sets the number of seconds to wait before retrying an failed operation.
|
645 |
|
646 |
Cache Extension
|
647 |
+++++++++++++++
|
648 |
|
649 |
CacheExtensions are a general purpose mechanism to allow generic extensions to a Cache.
|
650 |
CacheExtensions are tied into the Cache lifecycle.
|
651 |
|
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.
|
656 |
|
657 |
Extensions are added as per the following example:
|
658 |
|
659 |
<cacheExtensionFactory class="com.example.FileWatchingCacheRefresherExtensionFactory"
|
660 |
properties="refreshIntervalMillis=18000, loaderTimeout=3000,
|
661 |
flushPeriod=whatever, someOtherProperty=someValue ..."/>
|
662 |
|
663 |
Terracotta Clustering
|
664 |
+++++++++++++++++++++
|
665 |
|
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:
|
668 |
|
669 |
* clustered=true|false - indicates whether this cache should be clustered with Terracotta. By
|
670 |
default, if the <terracotta> element is included, clustered=true.
|
671 |
|
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).
|
679 |
|
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
|
685 |
|
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.
|
694 |
|
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).
|
703 |
|
704 |
Simplest example to indicate clustering:
|
705 |
<terracotta/>
|
706 |
|
707 |
To indicate the cache should not be clustered (or remove the <terracotta> element altogether):
|
708 |
<terracotta clustered="false"/>
|
709 |
|
710 |
To indicate the cache should be clustered using identity mode:
|
711 |
<terracotta clustered="true" valueMode="identity"/>
|
712 |
|
713 |
To indicate the cache should be clustered using incoherent mode for bulk load:
|
714 |
<terracotta clustered="true" coherent="false"/>
|
715 |
|
716 |
To indicate the cache should be clustered using synchronous-write locking level:
|
717 |
<terracotta clustered="true" synchronousWrites="true"/>
|
718 |
|
719 |
-->
|
720 |
|
721 |
<!--
|
722 |
Mandatory Default Cache configuration. These settings will be applied to caches
|
723 |
created programmtically using CacheManager.add(String cacheName).
|
724 |
|
725 |
The defaultCache has an implicit name "default" which is a reserved cache name.
|
726 |
-->
|
727 |
<defaultCache
|
728 |
maxElementsInMemory="10000" |
729 |
eternal="false" |
730 |
timeToIdleSeconds="120" |
731 |
timeToLiveSeconds="120" |
732 |
overflowToDisk="true" |
733 |
diskSpoolBufferSizeMB="30" |
734 |
maxElementsOnDisk="10000000" |
735 |
diskPersistent="false" |
736 |
diskExpiryThreadIntervalSeconds="120" |
737 |
memoryStoreEvictionPolicy="LRU" |
738 |
/>
|
739 |
|
740 |
<!--
|
741 |
Sample caches. Following are some example caches. Remove these before use.
|
742 |
-->
|
743 |
|
744 |
<!--
|
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
|
748 |
10 minutes.
|
749 |
|
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"
|
753 |
-->
|
754 |
<!--
|
755 |
<cache name="sampleCache1"
|
756 |
maxElementsInMemory="10000"
|
757 |
maxElementsOnDisk="1000"
|
758 |
eternal="false"
|
759 |
overflowToDisk="true"
|
760 |
diskSpoolBufferSizeMB="20"
|
761 |
timeToIdleSeconds="300"
|
762 |
timeToLiveSeconds="600"
|
763 |
memoryStoreEvictionPolicy="LFU"
|
764 |
transactionalMode="off"
|
765 |
/>
|
766 |
-->
|
767 |
|
768 |
|
769 |
<!--
|
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.
|
774 |
-->
|
775 |
<!--
|
776 |
<cache name="sampleCache2"
|
777 |
maxElementsInMemory="1000"
|
778 |
eternal="true"
|
779 |
overflowToDisk="false"
|
780 |
memoryStoreEvictionPolicy="FIFO"
|
781 |
/>
|
782 |
-->
|
783 |
|
784 |
|
785 |
<!--
|
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.
|
789 |
-->
|
790 |
<!--
|
791 |
<cache name="sampleCache3"
|
792 |
maxElementsInMemory="500"
|
793 |
eternal="false"
|
794 |
overflowToDisk="true"
|
795 |
timeToIdleSeconds="300"
|
796 |
timeToLiveSeconds="600"
|
797 |
diskPersistent="true"
|
798 |
diskExpiryThreadIntervalSeconds="1"
|
799 |
memoryStoreEvictionPolicy="LFU"
|
800 |
/>
|
801 |
-->
|
802 |
|
803 |
|
804 |
<!--
|
805 |
Sample distributed cache named sampleDistributedCache1.
|
806 |
This cache replicates using defaults.
|
807 |
It also bootstraps from the cluster, using default properties.
|
808 |
-->
|
809 |
<!--
|
810 |
<cache name="sampleDistributedCache1"
|
811 |
maxElementsInMemory="10"
|
812 |
eternal="false"
|
813 |
timeToIdleSeconds="100"
|
814 |
timeToLiveSeconds="100"
|
815 |
overflowToDisk="false">
|
816 |
|
817 |
<cacheEventListenerFactory
|
818 |
class="net.sf.ehcache.distribution.RMICacheReplicatorFactory"/>
|
819 |
<bootstrapCacheLoaderFactory
|
820 |
class="net.sf.ehcache.distribution.RMIBootstrapCacheLoaderFactory"/>
|
821 |
</cache>
|
822 |
-->
|
823 |
|
824 |
|
825 |
<!--
|
826 |
Sample distributed cache named sampleDistributedCache2.
|
827 |
This cache replicates using specific properties.
|
828 |
It only replicates updates and does so synchronously via copy
|
829 |
-->
|
830 |
<!--
|
831 |
<cache name="sampleDistributedCache2"
|
832 |
maxElementsInMemory="10"
|
833 |
eternal="false"
|
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"/>
|
842 |
</cache>
|
843 |
-->
|
844 |
|
845 |
<!--
|
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.
|
850 |
-->
|
851 |
<!--
|
852 |
<cache name="sample/DistributedCache3"
|
853 |
maxElementsInMemory="10"
|
854 |
eternal="false"
|
855 |
timeToIdleSeconds="100"
|
856 |
timeToLiveSeconds="100"
|
857 |
overflowToDisk="true">
|
858 |
<cacheEventListenerFactory
|
859 |
class="net.sf.ehcache.distribution.RMICacheReplicatorFactory"
|
860 |
properties="asynchronousReplicationIntervalMillis=200"/>
|
861 |
</cache>
|
862 |
-->
|
863 |
|
864 |
<!--
|
865 |
Sample Terracotta clustered cache named sampleTerracottaCache.
|
866 |
This cache uses Terracotta to cluster the contents of the cache.
|
867 |
-->
|
868 |
<!--
|
869 |
<cache name="sampleTerracottaCache"
|
870 |
maxElementsInMemory="1000"
|
871 |
eternal="false"
|
872 |
timeToIdleSeconds="3600"
|
873 |
timeToLiveSeconds="1800"
|
874 |
overflowToDisk="false">
|
875 |
<terracotta/>
|
876 |
</cache>
|
877 |
-->
|
878 |
|
879 |
<!--
|
880 |
Sample xa enabled cache name xaCache
|
881 |
-->
|
882 |
<!--
|
883 |
<cache name="xaCache"
|
884 |
maxElementsInMemory="500"
|
885 |
eternal="false"
|
886 |
timeToIdleSeconds="300"
|
887 |
timeToLiveSeconds="600"
|
888 |
overflowToDisk="false"
|
889 |
diskPersistent="false"
|
890 |
diskExpiryThreadIntervalSeconds="1"
|
891 |
transactionalMode="xa">
|
892 |
<terracotta clustered="true"/>
|
893 |
</cache>
|
894 |
-->
|
895 |
</ehcache>
|