Debian Codegraph @

src/main/config/ehcache-terracotta.xml

raw
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. Another example, useful for Terracotta
14 server based deployments is <terracottaConfig url="${serverAndPort}"/ and specify a command line
15 switch of -Dserver36:9510
16
17 The attributes of <ehcache> are:
18 * name - an optional name for the CacheManager. The name is optional and primarily used
19 for documentation or to distinguish Terracotta clustered cache state. With Terracotta
20 clustered caches, a combination of CacheManager name and cache name uniquely identify a
21 particular cache store in the Terracotta clustered memory.
22 * updateCheck - an optional boolean flag specifying whether this CacheManager should check
23 for new versions of Ehcache over the Internet. If not specified, updateCheck="true".
24 * dynamicConfig - an optional setting that can be used to disable dynamic configuration of caches
25 associated with this CacheManager. By default this is set to true - i.e. dynamic configuration
26 is enabled. Dynamically configurable caches can have their TTI, TTL and maximum disk and
27 in-memory capacity changed at runtime through the cache's configuration object.
28 * monitoring - an optional setting that determines whether the CacheManager should
29 automatically register the SampledCacheMBean with the system MBean server.
30
31 Currently, this monitoring is only useful when using Terracotta clustering and using the
32 Terracotta Developer Console or the Terracotta Monitoring Console. With the "autodetect" value, the presence of Terracotta clustering
33 will be detected and monitoring, via the Developer Console or Monitoring Console, will be enabled. Other allowed values
34 are "on" and "off". The default is "autodetect". This setting does not perform any function when
35 used with JMX monitors.
36
37 * maxBytesLocalHeap - optional setting that constraints the memory usage of the Caches managed by the CacheManager
38 to use at most the specified number of bytes of the local VM's heap.
39 * maxBytesLocalOffHeap - optional setting that constraints the offHeap usage of the Caches managed by the CacheManager
40 to use at most the specified number of bytes of the local VM's offHeap memory.
41 * maxBytesLocalDisk - optional setting that constraints the disk usage of the Caches managed by the CacheManager
42 to use at most the specified number of bytes of the local disk.
43
44 These settings let you define "resource pools", caches will share. For instance setting maxBytesLocalHeap to 100M, will result in
45 all caches sharing 100 MegaBytes of ram. The CacheManager will balance these 100 MB across all caches based on their respective usage
46 patterns. You can allocate a precise amount of bytes to a particular cache by setting the appropriate maxBytes* attribute for that cache.
47 That amount will be subtracted from the CacheManager pools, so that if a cache a specified 30M requirement, the other caches will share
48 the remaining 70M.
49
50 Also, specifying a maxBytesLocalOffHeap at the CacheManager level will result in overflowToOffHeap to be true by default. If you don't want
51 a specific cache to overflow to off heap, you'll have to set overflowToOffHeap="false" explicitly
52
53 Here is an example of CacheManager level resource tuning, which will use up to 400M of heap and 2G of offHeap:
54
55 <ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
56 xsi:noNamespaceSchemaLocation="ehcache.xsd"
57 updateCheck="true" monitoring="autodetect"
58 dynamicConfig="true" maxBytesLocalHeap="400M" maxBytesLocalOffHeap="2G">
59
60 -->
61 <ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
62 xsi:noNamespaceSchemaLocation="ehcache.xsd"
63 updateCheck="true" monitoring="autodetect"
64 dynamicConfig="true">
65
66 <!--
67 DiskStore configuration
68 =======================
69
70 The diskStore element is optional. To turn off disk store path creation, comment out the diskStore
71 element below.
72
73 Configure it if you have disk persistence enabled for any cache or if you use
74 unclustered indexed search.
75
76 If it is not configured, and a cache is created which requires a disk store, a warning will be
77 issued and java.io.tmpdir will automatically be used.
78
79 diskStore has only one attribute - "path". It is the path to the directory where
80 any required disk files will be created.
81
82 If the path is one of the following Java System Property it is replaced by its value in the
83 running VM. For backward compatibility these should be specified without being enclosed in the ${token}
84 replacement syntax.
85
86 The following properties are translated:
87 * user.home - User's home directory
88 * user.dir - User's current working directory
89 * java.io.tmpdir - Default temp file path
90 * ehcache.disk.store.dir - A system property you would normally specify on the command line
91 e.g. java -Dehcache.disk.store.dir=/u01/myapp/diskdir ...
92
93 Subdirectories can be specified below the property e.g. java.io.tmpdir/one
94
95 -->
96 <diskStore path="java.io.tmpdir"/>
97
98 <!--
99 TransactionManagerLookup configuration
100 ======================================
101 This class is used by ehcache to lookup the JTA TransactionManager use in the application
102 using an XA enabled ehcache. If no class is specified then DefaultTransactionManagerLookup
103 will find the TransactionManager in the following order
104
105 *GenericJNDI (i.e. jboss, where the property jndiName controls the name of the
106 TransactionManager object to look up)
107 *Bitronix
108 *Atomikos
109
110 You can provide you own lookup class that implements the
111 net.sf.ehcache.transaction.manager.TransactionManagerLookup interface.
112 -->
113
114 <transactionManagerLookup class="net.sf.ehcache.transaction.manager.DefaultTransactionManagerLookup"
115 properties="jndiName=java:/TransactionManager" propertySeparator=";"/>
116
117
118 <!--
119 CacheManagerEventListener
120 =========================
121 Specifies a CacheManagerEventListenerFactory which is notified when Caches are added
122 or removed from the CacheManager.
123
124 The attributes of CacheManagerEventListenerFactory are:
125 * class - a fully qualified factory class name
126 * properties - comma separated properties having meaning only to the factory.
127
128 Sets the fully qualified class name to be registered as the CacheManager event listener.
129
130 The events include:
131 * adding a Cache
132 * removing a Cache
133
134 Callbacks to listener methods are synchronous and unsynchronized. It is the responsibility
135 of the implementer to safely handle the potential performance and thread safety issues
136 depending on what their listener is doing.
137
138 If no class is specified, no listener is created. There is no default.
139 -->
140 <cacheManagerEventListenerFactory class="" properties=""/>
141
142
143 <!--
144 TerracottaConfig
145 ========================
146 (Enable for Terracotta clustered operation)
147
148 Note: You need to install and run one or more Terracotta servers to use Terracotta clustering.
149 See http://www.terracotta.org/web/display/orgsite/Download.
150
151 Specifies a TerracottaConfig which will be used to configure the Terracotta
152 runtime for this CacheManager.
153
154 Configuration can be specified in two main ways: by reference to a source of
155 configuration or by use of an embedded Terracotta configuration file.
156
157 To specify a reference to a source (or sources) of configuration, use the url
158 attribute. The url attribute must contain a comma-separated list of:
159 * path to Terracotta configuration file (usually named tc-config.xml)
160 * URL to Terracotta configuration file
161 * <server host>:<port> of running Terracotta Server instance
162
163 Simplest example for pointing to a Terracotta server on this machine:
164 <terracottaConfig url="localhost:9510"/>
165
166 This element has one attribute "rejoin" which can take values of either "true" or "false":
167 <terracottaConfig rejoin="true" url="localhost:9510" />
168
169 By default, this attribute is false.
170
171 If rejoin is true, all Terracotta Clustered caches have to be configured with nonstop.
172 Without rejoin, if the Terracotta Server is restarted the client cannot connect back to the
173 server. When enabled, this allows the client to connect to the new cluster without the
174 need to restart the node.
175
176 Example using a path to Terracotta configuration file:
177 <terracottaConfig url="/app/config/tc-config.xml"/>
178
179 Example using a URL to a Terracotta configuration file:
180 <terracottaConfig url="http://internal/ehcache/app/tc-config.xml"/>
181
182 Example using multiple Terracotta server instance URLs (for fault tolerance):
183 <terracottaConfig url="host1:9510,host2:9510,host3:9510"/>
184
185 To embed a Terracotta configuration file within the ehcache configuration, simply
186 place a normal Terracotta XML config within the <terracottaConfig> element.
187
188 Example:
189 <terracottaConfig>
190 <tc-config>
191 <servers>
192 <server host="server1" name="s1"/>
193 <server host="server2" name="s2"/>
194 </servers>
195 <clients>
196 <logs>app/logs-%i</logs>
197 </clients>
198 </tc-config>
199 </terracottaConfig>
200
201 For more information on the Terracotta configuration, see the Terracotta documentation.
202 -->
203
204 <!--
205 Cache configuration
206 ===================
207
208 The following attributes are required.
209
210 name:
211 Sets the name of the cache. This is used to identify the cache. It must be unique.
212
213 maxEntriesLocalHeap:
214 Sets the maximum number of objects that will be created in memory. 0 = no limit.
215 In practice no limit means Integer.MAX_SIZE (2147483647) unless the cache is distributed
216 with a Terracotta server in which case it is limited by resources.
217
218 maxEntriesLocalDisk:
219 Sets the maximum number of objects that will be maintained in the DiskStore
220 The default value is zero, meaning unlimited.
221
222 eternal:
223 Sets whether elements are eternal. If eternal, timeouts are ignored and the
224 element is never expired.
225
226 The following attributes and elements are optional.
227
228 overflowToOffHeap:
229 (boolean) This feature is available only in enterprise versions of Ehcache.
230 When set to true, enables the cache to utilize off-heap memory
231 storage to improve performance. Off-heap memory is not subject to Java
232 GC. The default value is false.
233
234 maxBytesLocalHeap:
235 Defines how many bytes the cache may use from the VM's heap. If a CacheManager
236 maxBytesLocalHeap has been defined, this Cache's specified amount will be
237 subtracted from the CacheManager. Other caches will share the remainder.
238 This attribute's values are given as <number>k|K|m|M|g|G for
239 kilobytes (k|K), megabytes (m|M), or gigabytes (g|G).
240 For example, maxBytesLocalHeap="2g" allots 2 gigabytes of heap memory.
241 If you specify a maxBytesLocalHeap, you can't use the maxEntriesLocalHeap attribute.
242 maxEntriesLocalHeap can't be used if a CacheManager maxBytesLocalHeap is set.
243
244 Elements put into the cache will be measured in size using net.sf.ehcache.pool.sizeof.SizeOf
245 If you wish to ignore some part of the object graph, see net.sf.ehcache.pool.sizeof.annotations.IgnoreSizeOf
246
247 maxBytesLocalOffHeap:
248 This feature is available only in enterprise versions of Ehcache.
249 Sets the amount of off-heap memory this cache can use, and will reserve.
250
251 This setting will set overflowToOffHeap to true. Set explicitly to false to disable overflow behavior.
252
253 Note that it is recommended to set maxEntriesLocalHeap to at least 100 elements
254 when using an off-heap store, otherwise performance will be seriously degraded,
255 and a warning will be logged.
256
257 The minimum amount that can be allocated is 128MB. There is no maximum.
258
259 maxBytesLocalDisk:
260 As for maxBytesLocalHeap, but specifies the limit of disk storage this cache will ever use.
261
262 timeToIdleSeconds:
263 Sets the time to idle for an element before it expires.
264 i.e. The maximum amount of time between accesses before an element expires
265 Is only used if the element is not eternal.
266 Optional attribute. A value of 0 means that an Element can idle for infinity.
267 The default value is 0.
268
269 timeToLiveSeconds:
270 Sets the time to live for an element before it expires.
271 i.e. The maximum time between creation time and when an element expires.
272 Is only used if the element is not eternal.
273 Optional attribute. A value of 0 means that and Element can live for infinity.
274 The default value is 0.
275
276 diskExpiryThreadIntervalSeconds:
277 The number of seconds between runs of the disk expiry thread for the DiskStore (does not apply to RestartableStore). The default value
278 is 120 seconds.
279
280 diskSpoolBufferSizeMB:
281 This is the size to allocate the DiskStore (does not apply to RestartableStore) for a spool buffer. Writes are made
282 to this area and then asynchronously written to disk. The default size is 30MB.
283 Each spool buffer is used only by its cache. If you get OutOfMemory errors consider
284 lowering this value. To improve DiskStore performance consider increasing it. Trace level
285 logging in the DiskStore will show if put back ups are occurring.
286
287 clearOnFlush:
288 whether the MemoryStore should be cleared when flush() is called on the cache.
289 By default, this is true i.e. the MemoryStore is cleared.
290
291 statistics:
292 Whether to collect statistics. Note that this should be turned on if you are using
293 the Ehcache Monitor. By default statistics is turned off to favour raw performance.
294 To enable set statistics="true"
295
296 memoryStoreEvictionPolicy:
297 Policy would be enforced upon reaching the maxEntriesLocalHeap limit. Default
298 policy is Least Recently Used (specified as LRU). Other policies available -
299 First In First Out (specified as FIFO) and Less Frequently Used
300 (specified as LFU)
301
302 copyOnRead:
303 Whether an Element is copied when being read from a cache.
304 By default this is false.
305
306 copyOnWrite:
307 Whether an Element is copied when being added to the cache.
308 By default this is false.
309
310 Cache persistence is configured through the persistence sub-element. The attributes of the
311 persistence element are:
312
313 strategy:
314 Configures the type of persistence provided by the configured cache. This must be one of the
315 following values:
316
317 * localRestartable - Enables the RestartStore and copies all cache entries (on-heap and/or off-heap)
318 to disk. This option provides fast restartability with fault tolerant cache persistence on disk.
319 It is available for BigMemory and Enterprise Ehcache users only.
320
321 * localTempSwap - Swaps cache entries (on-heap and/or off-heap) to disk when the cache is full.
322 "localTempSwap" is not persistent.
323
324 * none - Does not persist cache entries.
325
326 * distributed - Defers to the <terracotta> configuration for persistence settings. This option
327 is not applicable for standalone.
328
329 synchronousWrites:
330 When set to true write operations on the cache do not return until after the operations data has been
331 successfully flushed to the disk storage. This option is only valid when used with the "localRestartable"
332 strategy, and defaults to false.
333
334 The following example configuration shows a cache configured for localTempSwap restartability.
335
336 <cache name="persistentCache" maxEntriesLocalHeap="1000">
337 <persistence strategy="localTempSwap"/>
338 </cache>
339
340 Cache elements can also contain sub elements which take the same format of a factory class
341 and properties. Defined sub-elements are:
342
343 * cacheEventListenerFactory - Enables registration of listeners for cache events, such as
344 put, remove, update, and expire.
345
346 * bootstrapCacheLoaderFactory - Specifies a BootstrapCacheLoader, which is called by a
347 cache on initialisation to prepopulate itself.
348
349 * cacheExtensionFactory - Specifies a CacheExtension, a generic mechanism to tie a class
350 which holds a reference to a cache to the cache lifecycle.
351
352 * cacheExceptionHandlerFactory - Specifies a CacheExceptionHandler, which is called when
353 cache exceptions occur.
354
355 * cacheLoaderFactory - Specifies a CacheLoader, which can be used both asynchronously and
356 synchronously to load objects into a cache. More than one cacheLoaderFactory element
357 can be added, in which case the loaders form a chain which are executed in order. If a
358 loader returns null, the next in chain is called.
359
360 * copyStrategy - Specifies a fully qualified class which implements
361 net.sf.ehcache.store.compound.CopyStrategy. This strategy will be used for copyOnRead
362 and copyOnWrite in place of the default which is serialization.
363
364 Example of cache level resource tuning:
365 <cache name="memBound" maxBytesLocalHeap="100m" maxBytesLocalOffHeap="4g" maxBytesLocalDisk="200g" />
366
367
368 Cache Event Listeners
369 +++++++++++++++++++++
370
371 All cacheEventListenerFactory elements can take an optional property listenFor that describes
372 which events will be delivered in a clustered environment. The listenFor attribute has the
373 following allowed values:
374
375 * all - the default is to deliver all local and remote events
376 * local - deliver only events originating in the current node
377 * remote - deliver only events originating in other nodes
378
379 Example of setting up a logging listener for local cache events:
380
381 <cacheEventListenerFactory class="my.company.log.CacheLogger"
382 listenFor="local" />
383
384
385 Search
386 ++++++
387
388 A <cache> can be made searchable by adding a <searchable/> sub-element. By default the keys
389 and value objects of elements put into the cache will be attributes against which
390 queries can be expressed.
391
392 <cache>
393 <searchable/>
394 </cache>
395
396
397 An "attribute" of the cache elements can also be defined to be searchable. In the example below
398 an attribute with the name "age" will be available for use in queries. The value for the "age"
399 attribute will be computed by calling the method "getAge()" on the value object of each element
400 in the cache. See net.sf.ehcache.search.attribute.ReflectionAttributeExtractor for the format of
401 attribute expressions. Attribute values must also conform to the set of types documented in the
402 net.sf.ehcache.search.attribute.AttributeExtractor interface
403
404 <cache>
405 <searchable>
406 <searchAttribute name="age" expression="value.getAge()"/>
407 </searchable>
408 </cache>
409
410
411 Attributes may also be defined using a JavaBean style. With the following attribute declaration
412 a public method getAge() will be expected to be found on either the key or value for cache elements
413
414 <cache>
415 <searchable>
416 <searchAttribute name="age"/>
417 </searchable>
418 </cache>
419
420 In more complex situations you can create your own attribute extractor by implementing the
421 AttributeExtractor interface. Providing your extractor class is shown in the following example:
422
423 <cache>
424 <searchable>
425 <searchAttribute name="age" class="com.example.MyAttributeExtractor"/>
426 </searchable>
427 </cache>
428
429 Use properties to pass state to your attribute extractor if needed. Your implementation must provide
430 a public constructor that takes a single java.util.Properties instance
431
432 <cache>
433 <searchable>
434 <searchAttribute name="age" class="com.example.MyAttributeExtractor" properties="foo=1,bar=2"/>
435 </searchable>
436 </cache>
437
438
439 Cache Exception Handling
440 ++++++++++++++++++++++++
441
442 By default, most cache operations will propagate a runtime CacheException on failure. An
443 interceptor, using a dynamic proxy, may be configured so that a CacheExceptionHandler can
444 be configured to intercept Exceptions. Errors are not intercepted.
445
446 It is configured as per the following example:
447
448 <cacheExceptionHandlerFactory class="com.example.ExampleExceptionHandlerFactory"
449 properties="logLevel=FINE"/>
450
451 Caches with ExceptionHandling configured are not of type Cache, but are of type Ehcache only,
452 and are not available using CacheManager.getCache(), but using CacheManager.getEhcache().
453
454
455 Cache Loader
456 ++++++++++++
457
458 A default CacheLoader may be set which loads objects into the cache through asynchronous and
459 synchronous methods on Cache. This is different to the bootstrap cache loader, which is used
460 only in distributed caching.
461
462 It is configured as per the following example:
463
464 <cacheLoaderFactory class="com.example.ExampleCacheLoaderFactory"
465 properties="type=int,startCounter=10"/>
466
467 Element value comparator
468 ++++++++++++++++++++++++
469
470 These two cache atomic methods:
471 removeElement(Element e)
472 replace(Element old, Element element)
473
474 rely on comparison of cached elements value. The default implementation relies on Object.equals()
475 but that can be changed in case you want to use a different way to compute equality of two elements.
476
477 This is configured as per the following example:
478
479 <elementValueComparator class="com.company.xyz.MyElementComparator"/>
480
481 The MyElementComparator class must implement the is net.sf.ehcache.store.ElementValueComparator
482 interface. The default implementation is net.sf.ehcache.store.DefaultElementValueComparator.
483
484
485 SizeOf Policy
486 +++++++++++++
487
488 Control how deep the SizeOf engine can go when sizing on-heap elements.
489
490 This is configured as per the following example:
491
492 <sizeOfPolicy maxDepth="100" maxDepthExceededBehavior="abort"/>
493
494 maxDepth controls how many linked objects can be visited before the SizeOf engine takes any action.
495 maxDepthExceededBehavior specifies what happens when the max depth is exceeded while sizing an object graph.
496 "continue" makes the SizeOf engine log a warning and continue the sizing. This is the default.
497 "abort" makes the SizeOf engine abort the sizing, log a warning and mark the cache as not correctly tracking
498 memory usage. This makes Ehcache.hasAbortedSizeOf() return true when this happens.
499
500 The SizeOf policy can be configured at the cache manager level (directly under <ehcache>) and at
501 the cache level (under <cache> or <defaultCache>). The cache policy always overrides the cache manager
502 one if both are set. This element has no effect on distributed caches.
503
504 Transactions
505 ++++++++++++
506
507 To enable an ehcache as transactions, set the transactionalMode
508
509 transactionalMode="xa" - high performance JTA/XA implementation
510 transactionalMode="xa_strict" - canonically correct JTA/XA implementation
511 transactionMode="local" - high performance local transactions involving caches only
512 transactionalMode="off" - the default, no transactions
513
514 If set, all cache operations will need to be done through transactions.
515
516 To prevent users keeping references on stored elements and modifying them outside of any transaction's control,
517 transactions also require the cache to be configured copyOnRead and copyOnWrite.
518
519 CacheWriter
520 ++++++++++++
521
522 A CacheWriter can be set to write to an underlying resource. Only one CacheWriter can be
523 configured per cache.
524
525 The following is an example of how to configure CacheWriter for write-through:
526
527 <cacheWriter writeMode="write-through" notifyListenersOnException="true">
528 <cacheWriterFactory class="net.sf.ehcache.writer.TestCacheWriterFactory"
529 properties="type=int,startCounter=10"/>
530 </cacheWriter>
531
532 The following is an example of how to configure CacheWriter for write-behind:
533
534 <cacheWriter writeMode="write-behind" minWriteDelay="1" maxWriteDelay="5"
535 rateLimitPerSecond="5" writeCoalescing="true" writeBatching="true" writeBatchSize="1"
536 retryAttempts="2" retryAttemptDelaySeconds="1">
537 <cacheWriterFactory class="net.sf.ehcache.writer.TestCacheWriterFactory"
538 properties="type=int,startCounter=10"/>
539 </cacheWriter>
540
541 The cacheWriter element has the following attributes:
542 * writeMode: the write mode, write-through or write-behind
543
544 These attributes only apply to write-through mode:
545 * notifyListenersOnException: Sets whether to notify listeners when an exception occurs on a writer operation.
546
547 These attributes only apply to write-behind mode:
548 * minWriteDelay: Set the minimum number of seconds to wait before writing behind. If set to a value greater than 0,
549 it permits operations to build up in the queue. This is different from the maximum write delay in that by waiting
550 a minimum amount of time, work is always being built up. If the minimum write delay is set to zero and the
551 CacheWriter performs its work very quickly, the overhead of processing the write behind queue items becomes very
552 noticeable in a cluster since all the operations might be done for individual items instead of for a collection
553 of them.
554 * maxWriteDelay: Set the maximum number of seconds to wait before writing behind. If set to a value greater than 0,
555 it permits operations to build up in the queue to enable effective coalescing and batching optimisations.
556 * writeBatching: Sets whether to batch write operations. If set to true, writeAll and deleteAll will be called on
557 the CacheWriter rather than write and delete being called for each key. Resources such as databases can perform
558 more efficiently if updates are batched, thus reducing load.
559 * writeBatchSize: Sets the number of operations to include in each batch when writeBatching is enabled. If there are
560 less entries in the write-behind queue than the batch size, the queue length size is used.
561 * rateLimitPerSecond: Sets the maximum number of write operations to allow per second when writeBatching is enabled.
562 * writeCoalescing: Sets whether to use write coalescing. If set to true and multiple operations on the same key are
563 present in the write-behind queue, only the latest write is done, as the others are redundant.
564 * retryAttempts: Sets the number of times the operation is retried in the CacheWriter, this happens after the
565 original operation.
566 * retryAttemptDelaySeconds: Sets the number of seconds to wait before retrying an failed operation.
567
568 Cache Extension
569 +++++++++++++++
570
571 CacheExtensions are a general purpose mechanism to allow generic extensions to a Cache.
572 CacheExtensions are tied into the Cache lifecycle.
573
574 CacheExtensions are created using the CacheExtensionFactory which has a
575 <code>createCacheCacheExtension()</code> method which takes as a parameter a
576 Cache and properties. It can thus call back into any public method on Cache, including, of
577 course, the load methods.
578
579 Extensions are added as per the following example:
580
581 <cacheExtensionFactory class="com.example.FileWatchingCacheRefresherExtensionFactory"
582 properties="refreshIntervalMillis=18000, loaderTimeout=3000,
583 flushPeriod=whatever, someOtherProperty=someValue ..."/>
584
585 Cache Decorator Factory
586 +++++++++++++++++++++++
587
588 Cache decorators can be configured directly in ehcache.xml. The decorators will be created and added to the CacheManager.
589 It accepts the name of a concrete class that extends net.sf.ehcache.constructs.CacheDecoratorFactory
590 The properties will be parsed according to the delimiter (default is comma ',') and passed to the concrete factory's
591 <code>createDecoratedEhcache(Ehcache cache, Properties properties)</code> method along with the reference to the owning cache.
592
593 It is configured as per the following example:
594
595 <cacheDecoratorFactory
596 class="com.company.DecoratedCacheFactory"
597 properties="property1=true ..." />
598
599 Distributed Caching with Terracotta
600 +++++++++++++++++++++++++++++++++++
601
602 Distributed Caches connect to a Terracotta Server Array. They are configured with the <terracotta> sub-element.
603
604 The <terracotta> sub-element has the following attributes:
605
606 * clustered=true|false - indicates whether this cache should be clustered (distributed) with Terracotta. By
607 default, if the <terracotta> element is included, clustered=true.
608
609 * valueMode=serialization|identity - the default is serialization
610
611 Indicates whether cache Elements are distributed with serialized copies or whether a single copy
612 in identity mode is distributed.
613
614 The implications of Identity mode should be clearly understood with reference to the Terracotta
615 documentation before use.
616
617 * copyOnRead=true|false - indicates whether cache values are deserialized on every read or if the
618 materialized cache value can be re-used between get() calls. This setting is useful if a cache
619 is being shared by callers with disparate classloaders or to prevent local drift if keys/values
620 are mutated locally without being put back in the cache.
621
622 The default is false.
623
624 Note: This setting is only relevant for caches with valueMode=serialization
625
626 * consistency=strong|eventual - Indicates whether this cache should have strong consistency or eventual
627 consistency. The default is eventual. See the documentation for the meaning of these terms.
628
629 * synchronousWrites=true|false
630
631 Synchronous writes (synchronousWrites="true") maximize data safety by blocking the client thread until
632 the write has been written to the Terracotta Server Array.
633
634 This option is only available with consistency=strong. The default is false.
635
636 * concurrency - the number of segments that will be used by the map underneath the Terracotta Store.
637 Its optional and has default value of 0, which means will use default values based on the internal
638 Map being used underneath the store.
639
640 This value cannot be changed programmatically once a cache is initialized.
641
642 The <terracotta> sub-element also has a <nonstop> sub-element to allow configuration of cache behaviour if a distributed
643 cache operation cannot be completed within a set time or in the event of a clusterOffline message. If this element does not appear, nonstop behavior is off.
644
645 <nonstop> has the following attributes:
646
647 * enabled="true" - defaults to true.
648
649 * timeoutMillis - An SLA setting, so that if a cache operation takes longer than the allowed ms, it will timeout.
650
651 * immediateTimeout="true|false" - What to do on receipt of a ClusterOffline event indicating that communications
652 with the Terracotta Server Array were interrupted.
653
654 <nonstop> has one sub-element, <timeoutBehavior> which has the following attribute:
655
656 * type="noop|exception|localReads" - What to do when a timeout has occurred. Exception is the default.
657
658 Simplest example to indicate clustering:
659 <terracotta/>
660
661 To indicate the cache should not be clustered (or remove the <terracotta> element altogether):
662 <terracotta clustered="false"/>
663
664 To indicate the cache should be clustered using identity mode:
665 <terracotta clustered="true" valueMode="identity"/>
666
667 To indicate the cache should be clustered using "eventual" consistency mode for better performance :
668 <terracotta clustered="true" consistency="eventual"/>
669
670 To indicate the cache should be clustered using synchronous-write locking level:
671 <terracotta clustered="true" synchronousWrites="true"/>
672 -->
673
674 <!--
675 Sample caches. Following are some example caches. Remove these before use.
676 -->
677
678 <!--
679 Sample cache named sampleCache1
680 This cache contains a maximum in memory of 10000 elements, and will expire
681 an element if it is idle for more than 5 minutes and lives for more than
682 10 minutes.
683
684 If there are more than 10000 elements it will overflow to the
685 disk cache, which in this configuration will go to wherever java.io.tmp is
686 defined on your system. On a standard Linux system this will be /tmp"
687
688 <cache name="sampleCache1"
689 maxEntriesLocalHeap="10000"
690 maxEntriesLocalDisk="1000"
691 eternal="false"
692 diskSpoolBufferSizeMB="20"
693 timeToIdleSeconds="300"
694 timeToLiveSeconds="600"
695 memoryStoreEvictionPolicy="LFU"
696 transactionalMode="off">
697 <persistence strategy="localTempSwap"/>
698 </cache>
699 -->
700
701
702 <!--
703 Sample cache named sampleCache2
704 This cache has a maximum of 1000 elements in memory. There is no overflow to disk, so 1000
705 is also the maximum cache size. Note that when a cache is eternal, timeToLive and
706 timeToIdle are not used and do not need to be specified.
707
708 <cache name="sampleCache2"
709 maxEntriesLocalHeap="1000"
710 eternal="true"
711 memoryStoreEvictionPolicy="FIFO"/>
712 -->
713
714 <!--
715 Sample Terracotta clustered cache named sampleTerracottaCache.
716 This cache uses Terracotta to cluster the contents of the cache.
717
718 <cache name="sampleTerracottaCache"
719 maxBytesLocalHeap="10m"
720 eternal="false"
721 timeToIdleSeconds="3600"
722 timeToLiveSeconds="1800">
723 <terracotta/>
724 </cache>
725 -->
726
727 <!--
728 Sample xa enabled cache named xaCache
729 <cache name="xaCache"
730 maxEntriesLocalHeap="500"
731 eternal="false"
732 timeToIdleSeconds="300"
733 timeToLiveSeconds="600"
734 diskExpiryThreadIntervalSeconds="1"
735 transactionalMode="xa_strict">
736 </cache>
737 -->
738
739 <!--
740 Sample copy on both read and write cache named copyCache
741 using the default (explicitly configured here as an example) ReadWriteSerializationCopyStrategy
742 class could be any implementation of net.sf.ehcache.store.compound.CopyStrategy
743 <cache name="copyCache"
744 maxEntriesLocalHeap="500"
745 eternal="false"
746 timeToIdleSeconds="300"
747 timeToLiveSeconds="600"
748 diskExpiryThreadIntervalSeconds="1"
749 copyOnRead="true"
750 copyOnWrite="true">
751 <copyStrategy class="net.sf.ehcache.store.compound.ReadWriteSerializationCopyStrategy" />
752 </cache>
753 -->
754
755 <!--
756 Default Cache configuration. These settings will be applied to caches
757 created programmatically using CacheManager.add(String cacheName).
758 This element is optional, and using CacheManager.add(String cacheName) when
759 its not present will throw CacheException
760
761 The defaultCache has an implicit name "default" which is a reserved cache name.
762 -->
763 <defaultCache
764 maxEntriesLocalHeap="0"
765 eternal="false"
766 timeToIdleSeconds="1200"
767 timeToLiveSeconds="1200">
768 </defaultCache>
769
770 <!--
771 Sample, for BigMemory and Enterprise Ehcache only, demonstrating a tiered cache with in-memory, off-heap and disk stores.
772 In this example the in-memory (on-heap) store is limited to 10,000 items ... which for example for 1k items would use 10MB of memory,
773 the off-heap store is limited to 4GB and the disk store is unlimited in size.
774 -->
775 <cache name="sampleBigMemory"
776 eternal="true"
777 maxBytesLocalHeap="100M"
778 maxBytesLocalOffHeap="2G"
779 </cache>
780
781 <!--
782 Sample, for BigMemory and Enterprise Ehcache only, demonstrating a restartable cache with in-memory and off-heap stores.
783 -->
784 <cache name="restartableBigMemory"
785 maxEntriesLocalHeap="10000"
786 eternal="true"
787 overflowToOffHeap="true"
788 maxBytesLocalOffHeap="4g"
789 <persistence strategy="localRestartable"/>
790 </cache>
791 </ehcache>