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
|
* monitoring - an optional setting that determines whether the CacheManager should
|
23
|
automatically register the SampledCacheMBean with the system MBean server.
|
24
|
Currently, this monitoring is only useful when using Terracotta clustering and using the
|
25
|
Terracotta Developer Console. With the "autodetect" value, the presence of Terracotta clustering
|
26
|
will be detected and monitoring, via the Developer Console, will be enabled. Other allowed values
|
27
|
are "on" and "off". The default is "autodetect". This setting does not perform any function when
|
28
|
used with JMX monitors.
|
29
|
* dynamicConfig - an optional setting that can be used to disable dynamic configuration of caches
|
30
|
associated with this CacheManager. By default this is set to true - i.e. dynamic configuration
|
31
|
is enabled. Dynamically configurable caches can have their TTI, TTL and maximum disk and
|
32
|
in-memory capacity changed at runtime through the cache's configuration object.
|
33
|
-->
|
34
|
<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
35
|
xsi:noNamespaceSchemaLocation="ehcache.xsd"
|
36
|
updateCheck="true" monitoring="autodetect"
|
37
|
dynamicConfig="true" >
|
38
|
|
39
|
<!--
|
40
|
DiskStore configuration
|
41
|
=======================
|
42
|
|
43
|
The diskStore element is optional. To turn off disk store path creation, comment out the diskStore
|
44
|
element below.
|
45
|
|
46
|
Configure it if you have overflowToDisk or diskPersistent enabled for any cache.
|
47
|
|
48
|
If it is not configured, and a cache is created which requires a disk store, a warning will be
|
49
|
issued and java.io.tmpdir will automatically be used.
|
50
|
|
51
|
diskStore has only one attribute - "path". It is the path to the directory where
|
52
|
.data and .index files will be created.
|
53
|
|
54
|
If the path is one of the following Java System Property it is replaced by its value in the
|
55
|
running VM. For backward compatibility these should be specified without being enclosed in the ${token}
|
56
|
replacement syntax.
|
57
|
|
58
|
The following properties are translated:
|
59
|
* user.home - User's home directory
|
60
|
* user.dir - User's current working directory
|
61
|
* java.io.tmpdir - Default temp file path
|
62
|
* ehcache.disk.store.dir - A system property you would normally specify on the command line
|
63
|
e.g. java -Dehcache.disk.store.dir=/u01/myapp/diskdir ...
|
64
|
|
65
|
Subdirectories can be specified below the property e.g. java.io.tmpdir/one
|
66
|
|
67
|
-->
|
68
|
<diskStore path="java.io.tmpdir"/>
|
69
|
|
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" properties="" propertySeparator=":"/> -->
|
87
|
|
88
|
<!--
|
89
|
CacheManagerEventListener
|
90
|
=========================
|
91
|
Specifies a CacheManagerEventListenerFactory which is notified when Caches are added
|
92
|
or removed from the CacheManager.
|
93
|
|
94
|
The attributes of CacheManagerEventListenerFactory are:
|
95
|
* class - a fully qualified factory class name
|
96
|
* properties - comma separated properties having meaning only to the factory.
|
97
|
|
98
|
Sets the fully qualified class name to be registered as the CacheManager event listener.
|
99
|
|
100
|
The events include:
|
101
|
* adding a Cache
|
102
|
* removing a Cache
|
103
|
|
104
|
Callbacks to listener methods are synchronous and unsynchronized. It is the responsibility
|
105
|
of the implementer to safely handle the potential performance and thread safety issues
|
106
|
depending on what their listener is doing.
|
107
|
|
108
|
If no class is specified, no listener is created. There is no default.
|
109
|
-->
|
110
|
|
111
|
<cacheManagerEventListenerFactory class="" properties=""/>
|
112
|
|
113
|
<!--
|
114
|
TerracottaConfig
|
115
|
========================
|
116
|
(Enable for Terracotta clustered operation)
|
117
|
|
118
|
Note: You need to install and run one or more Terracotta servers to use Terracotta clustering.
|
119
|
See http://www.terracotta.org/web/display/orgsite/Download.
|
120
|
|
121
|
Specifies a TerracottaConfig which will be used to configure the Terracotta
|
122
|
runtime for this CacheManager.
|
123
|
|
124
|
Configuration can be specified in two main ways: by reference to a source of
|
125
|
configuration or by use of an embedded Terracotta configuration file.
|
126
|
|
127
|
To specify a reference to a source (or sources) of configuration, use the url
|
128
|
attribute. The url attribute must contain a comma-separated list of:
|
129
|
* path to Terracotta configuration file (usually named tc-config.xml)
|
130
|
* URL to Terracotta configuration file
|
131
|
* <server host>:<port> of running Terracotta Server instance
|
132
|
|
133
|
Simplest example for pointing to a Terracotta server on this machine:
|
134
|
<terracottaConfig url="localhost:9510"/>
|
135
|
|
136
|
Example using a path to Terracotta configuration file:
|
137
|
<terracottaConfig url="/app/config/tc-config.xml"/>
|
138
|
|
139
|
Example using a URL to a Terracotta configuration file:
|
140
|
<terracottaConfig url="http://internal/ehcache/app/tc-config.xml"/>
|
141
|
|
142
|
Example using multiple Terracotta server instance URLs (for fault tolerance):
|
143
|
<terracottaConfig url="host1:9510,host2:9510,host3:9510"/>
|
144
|
|
145
|
To embed a Terracotta configuration file within the ehcache configuration, simply
|
146
|
place a normal Terracotta XML config within the <terracottaConfig> element.
|
147
|
|
148
|
Example:
|
149
|
<terracottaConfig>
|
150
|
<tc-config>
|
151
|
<servers>
|
152
|
<server host="server1" name="s1"/>
|
153
|
<server host="server2" name="s2"/>
|
154
|
</servers>
|
155
|
<clients>
|
156
|
<logs>app/logs-%i</logs>
|
157
|
</clients>
|
158
|
</tc-config>
|
159
|
</terracottaConfig>
|
160
|
|
161
|
For more information on the Terracotta configuration, see the Terracotta documentation.
|
162
|
-->
|
163
|
<!-- <terracottaConfig url="localhost:9510"/> -->
|
164
|
|
165
|
<!--
|
166
|
Cache configuration
|
167
|
===================
|
168
|
|
169
|
The following attributes are required.
|
170
|
|
171
|
name:
|
172
|
Sets the name of the cache. This is used to identify the cache. It must be unique.
|
173
|
|
174
|
maxElementsInMemory:
|
175
|
Sets the maximum number of objects that will be created in memory
|
176
|
|
177
|
maxElementsOnDisk:
|
178
|
Sets the maximum number of objects that will be maintained in the DiskStore
|
179
|
The default value is zero, meaning unlimited.
|
180
|
|
181
|
eternal:
|
182
|
Sets whether elements are eternal. If eternal, timeouts are ignored and the
|
183
|
element is never expired.
|
184
|
|
185
|
overflowToDisk:
|
186
|
Sets whether elements can overflow to disk when the memory store
|
187
|
has reached the maxInMemory limit.
|
188
|
|
189
|
The following attributes and elements are optional.
|
190
|
|
191
|
timeToIdleSeconds:
|
192
|
Sets the time to idle for an element before it expires.
|
193
|
i.e. The maximum amount of time between accesses before an element expires
|
194
|
Is only used if the element is not eternal.
|
195
|
Optional attribute. A value of 0 means that an Element can idle for infinity.
|
196
|
The default value is 0.
|
197
|
|
198
|
timeToLiveSeconds:
|
199
|
Sets the time to live for an element before it expires.
|
200
|
i.e. The maximum time between creation time and when an element expires.
|
201
|
Is only used if the element is not eternal.
|
202
|
Optional attribute. A value of 0 means that and Element can live for infinity.
|
203
|
The default value is 0.
|
204
|
|
205
|
diskPersistent:
|
206
|
Whether the disk store persists between restarts of the Virtual Machine.
|
207
|
The default value is false.
|
208
|
|
209
|
diskExpiryThreadIntervalSeconds:
|
210
|
The number of seconds between runs of the disk expiry thread. The default value
|
211
|
is 120 seconds.
|
212
|
|
213
|
diskSpoolBufferSizeMB:
|
214
|
This is the size to allocate the DiskStore for a spool buffer. Writes are made
|
215
|
to this area and then asynchronously written to disk. The default size is 30MB.
|
216
|
Each spool buffer is used only by its cache. If you get OutOfMemory errors consider
|
217
|
lowering this value. To improve DiskStore performance consider increasing it. Trace level
|
218
|
logging in the DiskStore will show if put back ups are occurring.
|
219
|
|
220
|
clearOnFlush:
|
221
|
whether the MemoryStore should be cleared when flush() is called on the cache.
|
222
|
By default, this is true i.e. the MemoryStore is cleared.
|
223
|
|
224
|
memoryStoreEvictionPolicy:
|
225
|
Policy would be enforced upon reaching the maxElementsInMemory limit. Default
|
226
|
policy is Least Recently Used (specified as LRU). Other policies available -
|
227
|
First In First Out (specified as FIFO) and Less Frequently Used
|
228
|
(specified as LFU)
|
229
|
|
230
|
Cache elements can also contain sub elements which take the same format of a factory class
|
231
|
and properties. Defined sub-elements are:
|
232
|
|
233
|
* cacheEventListenerFactory - Enables registration of listeners for cache events, such as
|
234
|
put, remove, update, and expire.
|
235
|
|
236
|
* bootstrapCacheLoaderFactory - Specifies a BootstrapCacheLoader, which is called by a
|
237
|
cache on initialisation to prepopulate itself.
|
238
|
|
239
|
* cacheExtensionFactory - Specifies a CacheExtension, a generic mechansim to tie a class
|
240
|
which holds a reference to a cache to the cache lifecycle.
|
241
|
|
242
|
* cacheExceptionHandlerFactory - Specifies a CacheExceptionHandler, which is called when
|
243
|
cache exceptions occur.
|
244
|
|
245
|
* cacheLoaderFactory - Specifies a CacheLoader, which can be used both asynchronously and
|
246
|
synchronously to load objects into a cache. More than one cacheLoaderFactory element
|
247
|
can be added, in which case the loaders form a chain which are executed in order. If a
|
248
|
loader returns null, the next in chain is called.
|
249
|
|
250
|
Cache Event Listeners
|
251
|
|
252
|
All cacheEventListenerFactory elements can take an optional property listenFor that describes
|
253
|
which events will be delivered in a clustered environment. The listenFor attribute has the
|
254
|
following allowed values:
|
255
|
|
256
|
* all - the default is to deliver all local and remote events
|
257
|
* local - deliver only events originating in the current node
|
258
|
* remote - deliver only events originating in other nodes
|
259
|
|
260
|
Example of setting up a logging listener for local cache events:
|
261
|
|
262
|
<cacheEventListenerFactory class="my.company.log.CacheLogger"
|
263
|
listenFor="local" />
|
264
|
|
265
|
|
266
|
Cache Exception Handling
|
267
|
++++++++++++++++++++++++
|
268
|
|
269
|
By default, most cache operations will propagate a runtime CacheException on failure. An
|
270
|
interceptor, using a dynamic proxy, may be configured so that a CacheExceptionHandler can
|
271
|
be configured to intercept Exceptions. Errors are not intercepted.
|
272
|
|
273
|
It is configured as per the following example:
|
274
|
|
275
|
<cacheExceptionHandlerFactory class="com.example.ExampleExceptionHandlerFactory"
|
276
|
properties="logLevel=FINE"/>
|
277
|
|
278
|
Caches with ExceptionHandling configured are not of type Cache, but are of type Ehcache only,
|
279
|
and are not available using CacheManager.getCache(), but using CacheManager.getEhcache().
|
280
|
|
281
|
|
282
|
Cache Loader
|
283
|
++++++++++++
|
284
|
|
285
|
A default CacheLoader may be set which loads objects into the cache through asynchronous and
|
286
|
synchronous methods on Cache. This is different to the bootstrap cache loader, which is used
|
287
|
only in distributed caching.
|
288
|
|
289
|
It is configured as per the following example:
|
290
|
|
291
|
<cacheLoaderFactory class="com.example.ExampleCacheLoaderFactory"
|
292
|
properties="type=int,startCounter=10"/>
|
293
|
|
294
|
XA Cache
|
295
|
++++++++
|
296
|
|
297
|
To enable an ehcache as a participant in the JTA Transaction, just have the following attribute
|
298
|
|
299
|
transactionalMode="xa", otherwise the default is transactionalMode="off"
|
300
|
|
301
|
Cache Writer
|
302
|
++++++++++++
|
303
|
|
304
|
A CacheWriter maybe be set to write to an underlying resource. Only one CacheWriter can be
|
305
|
been to a cache.
|
306
|
|
307
|
It is configured as per the following example for write-through:
|
308
|
|
309
|
<cacheWriter writeMode="write-through" notifyListenersOnException="true">
|
310
|
<cacheWriterFactory class="net.sf.ehcache.writer.TestCacheWriterFactory"
|
311
|
properties="type=int,startCounter=10"/>
|
312
|
</cacheWriter>
|
313
|
|
314
|
And it is configured as per the following example for write-behind:
|
315
|
|
316
|
<cacheWriter writeMode="write-behind" minWriteDelay="1" maxWriteDelay="5"
|
317
|
rateLimitPerSecond="5" writeCoalescing="true" writeBatching="true" writeBatchSize="1"
|
318
|
retryAttempts="2" retryAttemptDelaySeconds="1">
|
319
|
<cacheWriterFactory class="net.sf.ehcache.writer.TestCacheWriterFactory"
|
320
|
properties="type=int,startCounter=10"/>
|
321
|
</cacheWriter>
|
322
|
|
323
|
The cacheWriter element has the following attributes:
|
324
|
* writeMode: the write mode, write-through or write-behind
|
325
|
|
326
|
These attributes only apply to write-through mode:
|
327
|
* notifyListenersOnException: Sets whether to notify listeners when an exception occurs on a writer operation.
|
328
|
|
329
|
These attributes only apply to write-behind mode:
|
330
|
* minWriteDelay: Set the minimum number of seconds to wait before writing behind. If set to a value greater than 0,
|
331
|
it permits operations to build up in the queue. This is different from the maximum write delay in that by waiting
|
332
|
a minimum amount of time, work is always being built up. If the minimum write delay is set to zero and the
|
333
|
CacheWriter performs its work very quickly, the overhead of processing the write behind queue items becomes very
|
334
|
noticeable in a cluster since all the operations might be done for individual items instead of for a collection
|
335
|
of them.
|
336
|
* maxWriteDelay: Set the maximum number of seconds to wait before writing behind. If set to a value greater than 0,
|
337
|
it permits operations to build up in the queue to enable effective coalescing and batching optimisations.
|
338
|
* writeBatching: Sets whether to batch write operations. If set to true, writeAll and deleteAll will be called on
|
339
|
the CacheWriter rather than write and delete being called for each key. Resources such as databases can perform
|
340
|
more efficiently if updates are batched, thus reducing load.
|
341
|
* writeBatchSize: Sets the number of operations to include in each batch when writeBatching is enabled. If there are
|
342
|
less entries in the write-behind queue than the batch size, the queue length size is used.
|
343
|
* rateLimitPerSecond: Sets the maximum number of write operations to allow per second when writeBatching is enabled.
|
344
|
* writeCoalescing: Sets whether to use write coalescing. If set to true and multiple operations on the same key are
|
345
|
present in the write-behind queue, only the latest write is done, as the others are redundant.
|
346
|
* retryAttempts: Sets the number of times the operation is retried in the CacheWriter, this happens after the
|
347
|
original operation.
|
348
|
* retryAttemptDelaySeconds: Sets the number of seconds to wait before retrying an failed operation.
|
349
|
|
350
|
Cache Extension
|
351
|
+++++++++++++++
|
352
|
|
353
|
CacheExtensions are a general purpose mechanism to allow generic extensions to a Cache.
|
354
|
CacheExtensions are tied into the Cache lifecycle.
|
355
|
|
356
|
CacheExtensions are created using the CacheExtensionFactory which has a
|
357
|
<code>createCacheCacheExtension()</code> method which takes as a parameter a
|
358
|
Cache and properties. It can thus call back into any public method on Cache, including, of
|
359
|
course, the load methods.
|
360
|
|
361
|
Extensions are added as per the following example:
|
362
|
|
363
|
<cacheExtensionFactory class="com.example.FileWatchingCacheRefresherExtensionFactory"
|
364
|
properties="refreshIntervalMillis=18000, loaderTimeout=3000,
|
365
|
flushPeriod=whatever, someOtherProperty=someValue ..."/>
|
366
|
|
367
|
Terracotta Clustering
|
368
|
+++++++++++++++++++++
|
369
|
|
370
|
Cache elements can also contain information about whether the cache can be clustered with Terracotta.
|
371
|
The <terracotta> sub-element has the following attributes:
|
372
|
|
373
|
* clustered=true|false - indicates whether this cache should be clustered with Terracotta. By
|
374
|
default, if the <terracotta> element is included, clustered=true.
|
375
|
* valueMode=serialization|identity - indicates whether this cache should be clustered with
|
376
|
serialized copies of the values or using Terracotta identity mode. By default, values will
|
377
|
be cached in serialization mode which is similar to other replicated Ehcache modes. The identity
|
378
|
mode is only available in certain Terracotta deployment scenarios and will maintain actual object
|
379
|
identity of the keys and values across the cluster. In this case, all users of a value retrieved from
|
380
|
the cache are using the same clustered value and must provide appropriate locking for any changes
|
381
|
made to the value (or objects referred to by the value).
|
382
|
* synchronousWrites=true|false - When set to true, clustered caches use
|
383
|
Terracotta SYNCHRONOUS WRITE locks. Asynchronous writes (synchronousWrites="false") maximize performance by
|
384
|
allowing clients to proceed without waiting for a "transaction received" acknowledgement from the server.
|
385
|
Synchronous writes (synchronousWrites="true") maximize data safety by requiring that a client receive server
|
386
|
acknowledgement of a transaction before that client can proceed. If coherence mode is disabled using
|
387
|
configuration (coherent="false") or through the coherence API, only asynchronous writes can occur
|
388
|
(synchronousWrites="true" is ignored). By default this value is false (i.e. clustered caches use normal
|
389
|
Terracotta WRITE locks).
|
390
|
* coherent=true|false - indicates whether this cache should have coherent reads and writes with guaranteed
|
391
|
consistency across the cluster. By default, its value is true. If this attribute is set to false
|
392
|
(or "incoherent" mode), values from the cache are read without locking, possibly yielding stale data.
|
393
|
Writes to a cache in incoherent mode are batched and applied without acquiring cluster-wide locks,
|
394
|
possibly creating inconsistent values across cluster. Incoherent mode is a performance optimization
|
395
|
with weaker concurrency guarantees and should generally be used for bulk-loading caches, for loading
|
396
|
a read-only cache, or where the application that can tolerate reading stale data. This setting overrides
|
397
|
coherentReads, which is deprecated.
|
398
|
* copyOnRead=true|false - indicates whether cache values are deserialized on every read or if the
|
399
|
materialized cache value can be re-used between get() calls. This setting is useful if a cache
|
400
|
is being shared by callers with disparate classloaders or to prevent local drift if keys/values
|
401
|
are mutated locally w/o putting back to the cache. NOTE: This setting is only relevant for caches
|
402
|
with valueMode=serialization
|
403
|
|
404
|
Simplest example to indicate clustering:
|
405
|
<terracotta/>
|
406
|
|
407
|
To indicate the cache should not be clustered (or remove the <terracotta> element altogether):
|
408
|
<terracotta clustered="false"/>
|
409
|
|
410
|
To indicate the cache should be clustered using identity mode:
|
411
|
<terracotta clustered="true" valueMode="identity"/>
|
412
|
|
413
|
To indicate the cache should be clustered using incoherent mode for bulk load:
|
414
|
<terracotta clustered="true" coherent="false"/>
|
415
|
|
416
|
To indicate the cache should be clustered using synchronous-write locking level:
|
417
|
<terracotta clustered="true" synchronousWrites="true"/>
|
418
|
-->
|
419
|
|
420
|
<!--
|
421
|
Mandatory Default Cache configuration. These settings will be applied to caches
|
422
|
created programmtically using CacheManager.add(String cacheName).
|
423
|
|
424
|
The defaultCache has an implicit name "default" which is a reserved cache name.
|
425
|
-->
|
426
|
<defaultCache
|
427
|
maxElementsInMemory="1"
|
428
|
eternal="true"
|
429
|
overflowToDisk="true">
|
430
|
</defaultCache>
|
431
|
|
432
|
<cache name="doar"
|
433
|
maxElementsInMemory="20000"
|
434
|
eternal="false"
|
435
|
timeToIdleSeconds="0"
|
436
|
memoryStoreEvictionPolicy="LRU"/>
|
437
|
<!-- timeToLiveSeconds="604800" -->
|
438
|
<!-- transactionalMode="off" -->
|
439
|
|
440
|
<cache name="cris"
|
441
|
maxElementsInMemory="20000"
|
442
|
eternal="false"
|
443
|
timeToIdleSeconds="0"
|
444
|
overflowToDisk="true"
|
445
|
memoryStoreEvictionPolicy="LRU"/>
|
446
|
</ehcache>
|
447
|
|