/cacheManagement/examples/config/cache.xml
XML | 502 lines | 43 code | 21 blank | 438 comment | 0 complexity | 482d94c8b2ce44187d68d32edf4386fe MD5 | raw file
1<?xml version="1.0" encoding="UTF-8"?> 2 3<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 4 xsi:noNamespaceSchemaLocation="ehcache.xsd" > 5 6 <!-- 7 CacheManager Configuration 8 ========================== 9 An ehcache.xml corresponds to a single CacheManager. 10 11 See instructions below or the ehcache schema (ehcache.xsd) on how to configure. 12 13 System property tokens can be specified in this file which are replaced when the configuration 14 is loaded. For example multicastGroupPort=${multicastGroupPort} can be replaced with the 15 System property either from an environment variable or a system property specified with a 16 command line switch such as -DmulticastGroupPort=4446. 17 18 DiskStore configuration 19 ======================= 20 21 The diskStore element is optional. To turn off disk store path creation, comment out the diskStore 22 element below. 23 24 Configure it if you have overflowToDisk or diskPersistent enabled for any cache. 25 26 If it is not configured, and a cache is created which requires a disk store, a warning will be 27 issued and java.io.tmpdir will automatically be used. 28 29 diskStore has only one attribute - "path". It is the path to the directory where 30 .data and .index files will be created. 31 32 If the path is one of the following Java System Property it is replaced by its value in the 33 running VM. For backward compatibility these are not specified without being enclosed in the ${token} 34 replacement syntax. 35 36 The following properties are translated: 37 * user.home - User's home directory 38 * user.dir - User's current working directory 39 * java.io.tmpdir - Default temp file path 40 * ehcache.disk.store.dir - A system property you would normally specify on the command line 41 e.g. java -Dehcache.disk.store.dir=/u01/myapp/diskdir ... 42 43 Subdirectories can be specified below the property e.g. java.io.tmpdir/one 44 45 --> 46 <diskStore path="java.io.tmpdir"/> 47 48 <!-- 49 CacheManagerEventListener 50 ========================= 51 Specifies a CacheManagerEventListenerFactory which is notified when Caches are added 52 or removed from the CacheManager. 53 54 The attributes of CacheManagerEventListenerFactory are: 55 * class - a fully qualified factory class name 56 * properties - comma separated properties having meaning only to the factory. 57 58 Sets the fully qualified class name to be registered as the CacheManager event listener. 59 60 The events include: 61 * adding a Cache 62 * removing a Cache 63 64 Callbacks to listener methods are synchronous and unsynchronized. It is the responsibility 65 of the implementer to safely handle the potential performance and thread safety issues 66 depending on what their listener is doing. 67 68 If no class is specified, no listener is created. There is no default. 69 --> 70 <cacheManagerEventListenerFactory class="" properties=""/> 71 72 73 <!-- 74 CacheManagerPeerProvider 75 ======================== 76 (For distributed operation) 77 78 Specifies a CacheManagerPeerProviderFactory which will be used to create a 79 CacheManagerPeerProvider, which discovers other CacheManagers in the cluster. 80 81 One or more providers can be configured. The first one in the ehcache.xml is the default, which is used 82 for replication and bootstrapping. 83 84 The attributes of cacheManagerPeerProviderFactory are: 85 * class - a fully qualified factory class name 86 * properties - comma separated properties having meaning only to the factory. 87 88 Providers are available for RMI, JGroups and JMS as shown following. 89 90 RMICacheManagerPeerProvider 91 +++++++++++++++++++++++++++ 92 93 Ehcache comes with a built-in RMI-based distribution system with two means of discovery of 94 CacheManager peers participating in the cluster: 95 * automatic, using a multicast group. This one automatically discovers peers and detects 96 changes such as peers entering and leaving the group 97 * manual, using manual rmiURL configuration. A hardcoded list of peers is provided at 98 configuration time. 99 100 Configuring Automatic Discovery: 101 Automatic discovery is configured as per the following example: 102 <cacheManagerPeerProviderFactory 103 class="net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory" 104 properties="peerDiscovery=automatic, multicastGroupAddress=230.0.0.1, 105 multicastGroupPort=4446, timeToLive=32"/> 106 107 Valid properties are: 108 * peerDiscovery (mandatory) - specify "automatic" 109 * multicastGroupAddress (mandatory) - specify a valid multicast group address 110 * multicastGroupPort (mandatory) - specify a dedicated port for the multicast heartbeat 111 traffic 112 * timeToLive - specify a value between 0 and 255 which determines how far the packets will 113 propagate. 114 115 By convention, the restrictions are: 116 0 - the same host 117 1 - the same subnet 118 32 - the same site 119 64 - the same region 120 128 - the same continent 121 255 - unrestricted 122 123 Configuring Manual Discovery: 124 Manual discovery is configured as per the following example: 125 <cacheManagerPeerProviderFactory class= 126 "net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory" 127 properties="peerDiscovery=manual, 128 rmiUrls=//server1:40000/sampleCache1|//server2:40000/sampleCache1 129 | //server1:40000/sampleCache2|//server2:40000/sampleCache2" 130 propertySeparator="," /> 131 132 Valid properties are: 133 * peerDiscovery (mandatory) - specify "manual" 134 * rmiUrls (mandatory) - specify a pipe separated list of rmiUrls, in the form 135 //hostname:port 136 137 The hostname is the hostname of the remote CacheManager peer. The port is the listening 138 port of the RMICacheManagerPeerListener of the remote CacheManager peer. 139 140 JGroupsCacheManagerPeerProvider 141 +++++++++++++++++++++++++++++++ 142 <cacheManagerPeerProviderFactory class="net.sf.ehcache.distribution.jgroups.JGroupsCacheManagerPeerProviderFactory" 143 properties="connect=UDP(mcast_addr=231.12.21.132;mcast_port=45566;ip_ttl=32; 144 mcast_send_buf_size=150000;mcast_recv_buf_size=80000): 145 PING(timeout=2000;num_initial_members=6): 146 MERGE2(min_interval=5000;max_interval=10000): 147 FD_SOCK:VERIFY_SUSPECT(timeout=1500): 148 pbcast.NAKACK(gc_lag=10;retransmit_timeout=3000): 149 UNICAST(timeout=5000): 150 pbcast.STABLE(desired_avg_gossip=20000): 151 FRAG: 152 pbcast.GMS(join_timeout=5000;join_retry_timeout=2000;shun=false;print_local_addr=false)" 153 propertySeparator="::" 154 /> 155 The only property necessary is the connect String used by jgroups to configure itself. Refer to the Jgroups documentation for explanation 156 of all the protocols. The example above uses UDP multicast. If the connect property is not specified the default JGroups connection will be 157 used. 158 159 160 JMSCacheManagerPeerProviderFactory 161 ++++++++++++++++++++++++++++++++++ 162 <cacheManagerPeerProviderFactory 163 class="net.sf.ehcache.distribution.jms.JMSCacheManagerPeerProviderFactory" 164 properties="..." 165 propertySeparator="," 166 /> 167 168 The JMS PeerProviderFactory uses JNDI to maintain message queue independence. Refer to the manual for full configuration 169 examples using ActiveMQ and Open Message Queue. 170 171 Valid properties are: 172 * initialContextFactoryName (mandatory) - the name of the factory used to create the message queue initial context. 173 * providerURL (mandatory) - the JNDI configuration information for the service provider to use. 174 * topicConnectionFactoryBindingName (mandatory) - the JNDI binding name for the TopicConnectionFactory 175 * topicBindingName (mandatory) - the JNDI binding name for the topic name 176 * getQueueBindingName (mandatory only if using jmsCacheLoader) - the JNDI binding name for the queue name 177 * securityPrincipalName - the JNDI java.naming.security.principal 178 * securityCredentials - the JNDI java.naming.security.credentials 179 * urlPkgPrefixes - the JNDI java.naming.factory.url.pkgs 180 * userName - the user name to use when creating the TopicConnection to the Message Queue 181 * password - the password to use when creating the TopicConnection to the Message Queue 182 * acknowledgementMode - the JMS Acknowledgement mode for both publisher and subscriber. The available choices are 183 AUTO_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE and SESSION_TRANSACTED. The default is AUTO_ACKNOWLEDGE. 184 --> 185 <cacheManagerPeerProviderFactory 186 class="net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory" 187 properties="peerDiscovery=automatic, 188 multicastGroupAddress=230.0.0.1, 189 multicastGroupPort=4446, timeToLive=1" 190 propertySeparator="," 191 /> 192 193 194 <!-- 195 CacheManagerPeerListener 196 ======================== 197 (Enable for distributed operation) 198 199 Specifies a CacheManagerPeerListenerFactory which will be used to create a 200 CacheManagerPeerListener, which 201 listens for messages from cache replicators participating in the cluster. 202 203 The attributes of cacheManagerPeerListenerFactory are: 204 class - a fully qualified factory class name 205 properties - comma separated properties having meaning only to the factory. 206 207 Ehcache comes with a built-in RMI-based distribution system. The listener component is 208 RMICacheManagerPeerListener which is configured using 209 RMICacheManagerPeerListenerFactory. It is configured as per the following example: 210 211 <cacheManagerPeerListenerFactory 212 class="net.sf.ehcache.distribution.RMICacheManagerPeerListenerFactory" 213 properties="hostName=fully_qualified_hostname_or_ip, 214 port=40001, 215 remoteObjectPort=40002, 216 socketTimeoutMillis=120000" 217 propertySeparator="," /> 218 219 All properties are optional. They are: 220 * hostName - the hostName of the host the listener is running on. Specify 221 where the host is multihomed and you want to control the interface over which cluster 222 messages are received. Defaults to the host name of the default interface if not 223 specified. 224 * port - the port the RMI Registry listener listens on. This defaults to a free port if not specified. 225 * remoteObjectPort - the port number on which the remote objects bound in the registry receive calls. 226 This defaults to a free port if not specified. 227 * socketTimeoutMillis - the number of ms client sockets will stay open when sending 228 messages to the listener. This should be long enough for the slowest message. 229 If not specified it defaults to 120000ms. 230 231 --> 232 <cacheManagerPeerListenerFactory 233 class="net.sf.ehcache.distribution.RMICacheManagerPeerListenerFactory"/> 234 235 236 <!-- 237 Cache configuration 238 =================== 239 240 The following attributes are required. 241 242 name: 243 Sets the name of the cache. This is used to identify the cache. It must be unique. 244 245 maxElementsInMemory: 246 Sets the maximum number of objects that will be created in memory 247 248 maxElementsOnDisk: 249 Sets the maximum number of objects that will be maintained in the DiskStore 250 The default value is zero, meaning unlimited. 251 252 eternal: 253 Sets whether elements are eternal. If eternal, timeouts are ignored and the 254 element is never expired. 255 256 overflowToDisk: 257 Sets whether elements can overflow to disk when the memory store 258 has reached the maxInMemory limit. 259 260 The following attributes and elements are optional. 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 diskPersistent: 277 Whether the disk store persists between restarts of the Virtual Machine. 278 The default value is false. 279 280 diskExpiryThreadIntervalSeconds: 281 The number of seconds between runs of the disk expiry thread. The default value 282 is 120 seconds. 283 284 diskSpoolBufferSizeMB: 285 This is the size to allocate the DiskStore for a spool buffer. Writes are made 286 to this area and then asynchronously written to disk. The default size is 30MB. 287 Each spool buffer is used only by its cache. If you get OutOfMemory errors consider 288 lowering this value. To improve DiskStore performance consider increasing it. Trace level 289 logging in the DiskStore will show if put back ups are occurring. 290 291 clearOnFlush: 292 whether the MemoryStore should be cleared when flush() is called on the cache. 293 By default, this is true i.e. the MemoryStore is cleared. 294 295 memoryStoreEvictionPolicy: 296 Policy would be enforced upon reaching the maxElementsInMemory limit. Default 297 policy is Least Recently Used (specified as LRU). Other policies available - 298 First In First Out (specified as FIFO) and Less Frequently Used 299 (specified as LFU) 300 301 Cache elements can also contain sub elements which take the same format of a factory class 302 and properties. Defined sub-elements are: 303 304 * cacheEventListenerFactory - Enables registration of listeners for cache events, such as 305 put, remove, update, and expire. 306 307 * bootstrapCacheLoaderFactory - Specifies a BootstrapCacheLoader, which is called by a 308 cache on initialisation to prepopulate itself. 309 310 * cacheExtensionFactory - Specifies a CacheExtension, a generic mechansim to tie a class 311 which holds a reference to a cache to the cache lifecycle. 312 313 * cacheExceptionHandlerFactory - Specifies a CacheExceptionHandler, which is called when 314 cache exceptions occur. 315 316 * cacheLoaderFactory - Specifies a CacheLoader, which can be used both asynchronously and 317 synchronously to load objects into a cache. More than one cacheLoaderFactory element 318 can be added, in which case the loaders form a chain which are executed in order. If a 319 loader returns null, the next in chain is called. 320 321 RMI Cache Replication 322 +++++++++++++++++++++ 323 324 Each cache that will be distributed needs to set a cache event listener which replicates 325 messages to the other CacheManager peers. For the built-in RMI implementation this is done 326 by adding a cacheEventListenerFactory element of type RMICacheReplicatorFactory to each 327 distributed cache's configuration as per the following example: 328 329 <cacheEventListenerFactory class="net.sf.ehcache.distribution.RMICacheReplicatorFactory" 330 properties="replicateAsynchronously=true, 331 replicatePuts=true, 332 replicatePutsViaCopy=false, 333 replicateUpdates=true, 334 replicateUpdatesViaCopy=true, 335 replicateRemovals=true 336 asynchronousReplicationIntervalMillis=<number of milliseconds" 337 propertySeparator="," /> 338 339 The RMICacheReplicatorFactory recognises the following properties: 340 341 * replicatePuts=true|false - whether new elements placed in a cache are 342 replicated to others. Defaults to true. 343 344 * replicatePutsViaCopy=true|false - whether the new elements are 345 copied to other caches (true), or whether a remove message is sent. Defaults to true. 346 347 * replicateUpdates=true|false - whether new elements which override an 348 element already existing with the same key are replicated. Defaults to true. 349 350 * replicateRemovals=true - whether element removals are replicated. Defaults to true. 351 352 * replicateAsynchronously=true | false - whether replications are 353 asynchronous (true) or synchronous (false). Defaults to true. 354 355 * replicateUpdatesViaCopy=true | false - whether the new elements are 356 copied to other caches (true), or whether a remove message is sent. Defaults to true. 357 358 * asynchronousReplicationIntervalMillis=<number of milliseconds> - The asynchronous 359 replicator runs at a set interval of milliseconds. The default is 1000. The minimum 360 is 10. This property is only applicable if replicateAsynchronously=true 361 362 363 JGroups Replication 364 +++++++++++++++++++ 365 366 For the Jgroups replication this is done with: 367 <cacheEventListenerFactory class="net.sf.ehcache.distribution.jgroups.JGroupsCacheReplicatorFactory" 368 properties="replicateAsynchronously=true, replicatePuts=true, 369 replicateUpdates=true, replicateUpdatesViaCopy=false, 370 replicateRemovals=true,asynchronousReplicationIntervalMillis=1000"/> 371 This listener supports the same properties as the RMICacheReplicationFactory. 372 373 374 JMS Replication 375 +++++++++++++++ 376 377 For JMS-based replication this is done with: 378 <cacheEventListenerFactory 379 class="net.sf.ehcache.distribution.jms.JMSCacheReplicatorFactory" 380 properties="replicateAsynchronously=true, 381 replicatePuts=true, 382 replicateUpdates=true, 383 replicateUpdatesViaCopy=true, 384 replicateRemovals=true, 385 asynchronousReplicationIntervalMillis=1000" 386 propertySeparator=","/> 387 388 This listener supports the same properties as the RMICacheReplicationFactory. 389 390 Cluster Bootstrapping 391 +++++++++++++++++++++ 392 (RMI clusters only) 393 394 The RMIBootstrapCacheLoader bootstraps caches in clusters where RMICacheReplicators are 395 used. It is configured as per the following example: 396 397 <bootstrapCacheLoaderFactory 398 class="net.sf.ehcache.distribution.RMIBootstrapCacheLoaderFactory" 399 properties="bootstrapAsynchronously=true, maximumChunkSizeBytes=5000000" 400 propertySeparator="," /> 401 402 The RMIBootstrapCacheLoaderFactory recognises the following optional properties: 403 404 * bootstrapAsynchronously=true|false - whether the bootstrap happens in the background 405 after the cache has started. If false, bootstrapping must complete before the cache is 406 made available. The default value is true. 407 408 * maximumChunkSizeBytes=<integer> - Caches can potentially be very large, larger than the 409 memory limits of the VM. This property allows the bootstraper to fetched elements in 410 chunks. The default chunk size is 5000000 (5MB). 411 412 413 Cache Exception Handling 414 415 By default, most cache operations will propagate a runtime CacheException on failure. An 416 interceptor, using a dynamic proxy, may be configured so that a CacheExceptionHandler can 417 be configured to intercept Exceptions. Errors are not intercepted. 418 419 It is configured as per the following example: 420 421 <cacheExceptionHandlerFactory class="com.example.ExampleExceptionHandlerFactory" 422 properties="logLevel=FINE"/> 423 424 Caches with ExceptionHandling configured are not of type Cache, but are of type Ehcache only, 425 and are not available using CacheManager.getCache(), but using CacheManager.getEhcache(). 426 427 428 Cache Loader 429 430 A default CacheLoader may be set which loads objects into the cache through asynchronous and 431 synchronous methods on Cache. This is different to the bootstrap cache loader, which is used 432 only in distributed caching. 433 434 It is configured as per the following example: 435 436 <cacheLoaderFactory class="com.example.ExampleCacheLoaderFactory" 437 properties="type=int,startCounter=10"/> 438 439 Cache Extension 440 441 CacheExtensions are a general purpose mechanism to allow generic extensions to a Cache. 442 CacheExtensions are tied into the Cache lifecycle. 443 444 CacheExtensions are created using the CacheExtensionFactory which has a 445 <code>createCacheCacheExtension()</code> method which takes as a parameter a 446 Cache and properties. It can thus call back into any public method on Cache, including, of 447 course, the load methods. 448 449 Extensions are added as per the following example: 450 451 <cacheExtensionFactory class="com.example.FileWatchingCacheRefresherExtensionFactory" 452 properties="refreshIntervalMillis=18000, loaderTimeout=3000, 453 flushPeriod=whatever, someOtherProperty=someValue ..."/> 454 455 --> 456 457 458 <!-- 459 Mandatory Default Cache configuration. These settings will be applied to caches 460 created programmtically using CacheManager.add(String cacheName). 461 462 The defaultCache has an implicit name "default" which is a reserved cache name. 463 --> 464 <terracottaConfig url="192.168.230.130:9510"/> 465 466 467 468 <defaultCache 469 maxElementsInMemory="10000" 470 eternal="false" 471 timeToIdleSeconds="86400" 472 timeToLiveSeconds="86400" 473 overflowToDisk="false" 474 diskSpoolBufferSizeMB="30" 475 maxElementsOnDisk="10000000" 476 diskPersistent="false" 477 diskExpiryThreadIntervalSeconds="3600" 478 memoryStoreEvictionPolicy="LRU" 479 clearOnFlush="true" 480 > 481 482 <terracotta clustered="true" /> 483 484 485 </defaultCache> 486 487 <cache name="Computer" 488 maxElementsInMemory="200" 489 eternal="false" 490 overflowToDisk="false" 491 timeToIdleSeconds="120" 492 timeToLiveSeconds="120" 493 diskPersistent="false" 494 diskExpiryThreadIntervalSeconds="20" 495 memoryStoreEvictionPolicy="LRU" 496 > 497 498 <terracotta clustered="true" /> 499 500 </cache> 501 502</ehcache>