From jbosscache-commits at lists.jboss.org Tue Jan 6 06:08:42 2009 Content-Type: multipart/mixed; boundary="===============2007098541721027437==" MIME-Version: 1.0 From: jbosscache-commits at lists.jboss.org To: jbosscache-commits at lists.jboss.org Subject: [jbosscache-commits] JBoss Cache SVN: r7381 - in core/trunk/src: main/resources/config-samples and 1 other directories. Date: Tue, 06 Jan 2009 06:08:42 -0500 Message-ID: --===============2007098541721027437== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: manik.surtani(a)jboss.com Date: 2009-01-06 06:08:41 -0500 (Tue, 06 Jan 2009) New Revision: 7381 Modified: core/trunk/src/main/docbook/userguide/en/modules/cache_loaders.xml core/trunk/src/main/resources/config-samples/all.xml core/trunk/src/main/resources/config-samples/cacheloader-enabled.xml core/trunk/src/test/java/org/jboss/cache/config/parsing/SampleConfigFile= sCorrectnessTest.java Log: Fixed broken test and updated docs Modified: core/trunk/src/main/docbook/userguide/en/modules/cache_loaders.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- core/trunk/src/main/docbook/userguide/en/modules/cache_loaders.xml 2009= -01-05 17:54:59 UTC (rev 7380) +++ core/trunk/src/main/docbook/userguide/en/modules/cache_loaders.xml 2009= -01-06 11:08:41 UTC (rev 7381) @@ -1,152 +1,152 @@ - Cache Loaders - JBoss Cache can use a - CacheLoader - to back up the in-memory cache to a backend datastore. - If JBoss Cache is configured with a cache loader, then the following= features are provided: - - Whenever a cache element is accessed, and that element = is not in - the cache (e.g. due to eviction or due to server restart), the= n the cache loader transparently - loads the element into the cache if found in the backend - store. - + Cache Loaders + JBoss Cache can use a + CacheLoader + to back up the in-memory cache to a backend datastore. + If JBoss Cache is configured with a cache loader, then the followi= ng features are provided: + + Whenever a cache element is accessed, and that eleme= nt is not in + the cache (e.g. due to eviction or due to server restart),= then the cache loader transparently + loads the element into the cache if found in the backend + store. + = - Whenever an element is modified, added or removed, then= that - modification is persisted in the backend store via the cache l= oader. If - transactions are used, all modifications created within a tran= saction - are persisted. To this end, the - CacheLoader - takes part in the two - phase commit protocol run by the transaction manager, although= it does not do so explicitly. - - - + Whenever an element is modified, added or removed, t= hen that + modification is persisted in the backend store via the cac= he loader. If + transactions are used, all modifications created within a = transaction + are persisted. To this end, the + CacheLoader + takes part in the two + phase commit protocol run by the transaction manager, alth= ough it does not do so explicitly. + + + = -
- The CacheLoader Interface and Lifecycle +
+ The CacheLoader Interface and Lifecycle = -
- The CacheLoader interface +
+ The CacheLoader interface = - - - - - -
+ + + + + +
= - The interaction between JBoss Cache and a - CacheLoader - implementation is as follows. When - CacheLoaderConfiguration - (see below) is non-null, an - instance of each configured - CacheLoader - is created when the cache is created, and started when the cache = is started. - + The interaction between JBoss Cache and a + CacheLoader + implementation is as follows. When + CacheLoaderConfiguration + (see below) is non-null, an + instance of each configured + CacheLoader + is created when the cache is created, and started when the cac= he is started. + = - - CacheLoader.create() - and - CacheLoader.start() - are called when the cache is - started. Correspondingly, - stop() - and - destroy() - are called when the cache is - stopped. - + + CacheLoader.create() + and + CacheLoader.start() + are called when the cache is + started. Correspondingly, + stop() + and + destroy() + are called when the cache is + stopped. + = - Next, - setConfig() - and - setCache() - are called. The latter can be used to - store a reference to the cache, the former is used to configure t= his - instance of the - CacheLoader - . For example, here a database cache loader - could establish a connection to the database. - + Next, + setConfig() + and + setCache() + are called. The latter can be used to + store a reference to the cache, the former is used to configur= e this + instance of the + CacheLoader + . For example, here a database cache loader + could establish a connection to the database. + = - The - CacheLoader - interface has a set of methods that are called - when no transactions are used: - get() - , - put() - , - remove() - and - removeData() - : they get/set/remove the value - immediately. These methods are described as javadoc comments in t= he - interface. - + The + CacheLoader + interface has a set of methods that are called + when no transactions are used: + get() + , + put() + , + remove() + and + removeData() + : they get/set/remove the value + immediately. These methods are described as javadoc comments i= n the + interface. + = - Then there are three methods that are used with transactions: - prepare() - , - commit() - and - rollback() - . The - prepare() - method - is called when a transaction is to be committed. It has a transac= tion - object and a list of modfications as argument. The transaction ob= ject - can be used as a key into a hashmap of transactions, where the va= lues - are the lists of modifications. Each modification list has a numb= er of - Modification - elements, which represent the changes - made to a cache for a given transaction. When - prepare() - returns successfully, then the cache loader - must - be able to commit (or rollback) the - transaction successfully. - + Then there are three methods that are used with transactions: + prepare() + , + commit() + and + rollback() + . The + prepare() + method + is called when a transaction is to be committed. It has a tran= saction + object and a list of modfications as argument. The transaction= object + can be used as a key into a hashmap of transactions, where the= values + are the lists of modifications. Each modification list has a n= umber of + Modification + elements, which represent the changes + made to a cache for a given transaction. When + prepare() + returns successfully, then the cache loader + must + be able to commit (or rollback) the + transaction successfully. + = - - JBoss Cache takes care of calling prepare(), commit() - and rollback() on the cache loaders at the right time. - + + JBoss Cache takes care of calling prepare(), commit() + and rollback() on the cache loaders at the right time. + = - The - commit() - method tells the cache loader to - commit the transaction, and the - rollback() - method - tells the cache loader to discard the changes associated with that - transaction. - + The + commit() + method tells the cache loader to + commit the transaction, and the + rollback() + method + tells the cache loader to discard the changes associated with = that + transaction. + = - See the javadocs on this interface for a detailed explanation = on each method and the contract - implementations would need to fulfill. - + See the javadocs on this interface for a detailed explanatio= n on each method and the contract + implementations would need to fulfill. + = -
+
= -
- Configuration +
+ Configuration = - Cache loaders are configured as follows in the JBoss Cache XML - file. Note that you can define several cache loaders, in - a chain. The impact is that the cache will look at all of the cac= he - loaders in the order they've been configured, until it finds a va= lid, - non-null element of data. When performing writes, all cache loade= rs are - written to (except if the - ignoreModifications - element has been set to - true - for a specific cache loader. See the configuration section below = for - details. - + Cache loaders are configured as follows in the JBoss Cache X= ML + file. Note that you can define several cache loaders, in + a chain. The impact is that the cache will look at all of the = cache + loaders in the order they've been configured, until it finds a= valid, + non-null element of data. When performing writes, all cache lo= aders are + written to (except if the + ignoreModifications + element has been set to + true + for a specific cache loader. See the configuration section bel= ow for + details. + = - @@ -170,138 +170,139 @@ ]]> = - The - class - element defines the - class of the cache loader implementation. (Note that, because of = a bug in - the properties editor in JBoss AS, backslashes in variables for W= indows - filenames might not get expanded correctly, so replace=3D"false" = may be - necessary). Note that an implementation of cache loader has to ha= ve an empty - constructor. - + The + class + element defines the + class of the cache loader implementation. (Note that, because = of a bug in + the properties editor in JBoss AS, backslashes in variables fo= r Windows + filenames might not get expanded correctly, so replace=3D"fals= e" may be + necessary). Note that an implementation of cache loader has to= have an empty + constructor. + = - The - properties - element defines a configuration - specific to the given implementation. The filesystem-based - implementation for example defines the root directory to be used, - whereas a database implementation might define the database URL, = name - and password to establish a database connection. This configurati= on is - passed to the cache loader implementation via - CacheLoader.setConfig(Properties) - . Note that - backspaces may have to be escaped. - + The + properties + element defines a configuration + specific to the given implementation. The filesystem-based + implementation for example defines the root directory to be us= ed, + whereas a database implementation might define the database UR= L, name + and password to establish a database connection. This configur= ation is + passed to the cache loader implementation via + CacheLoader.setConfig(Properties) + . Note that + backspaces may have to be escaped. + = - - preload - allows us to define a list of nodes, or - even entire subtrees, that are visited by the cache on startup, i= n order - to preload the data associated with those nodes. The default ("/"= ) loads - the entire data available in the backend store into the cache, wh= ich is - probably not a good idea given that the data in the backend store= might - be large. As an example, - /a, - /product/catalogue - - loads the subtrees - /a - and - /product/catalogue - into the cache, but nothing - else. Anything else is loaded lazily when accessed. Preloading ma= kes - sense when one anticipates using elements under a given subtree - frequently. - . - + + preload + allows us to define a list of nodes, or + even entire subtrees, that are visited by the cache on startup= , in order + to preload the data associated with those nodes. The default (= "/") loads + the entire data available in the backend store into the cache,= which is + probably not a good idea given that the data in the backend st= ore might + be large. As an example, + /a, + /product/catalogue + + loads the subtrees + /a + and + /product/catalogue + into the cache, but nothing + else. Anything else is loaded lazily when accessed. Preloading= makes + sense when one anticipates using elements under a given subtree + frequently. + . + = - - fetchPersistentState - determines whether or not - to fetch the persistent state of a cache when joining a cluster. = Only - one configured cache loader may set this property to true; if mor= e than - one cache loader does so, a configuration exception will be throw= n when - starting your cache service. - + + fetchPersistentState + determines whether or not + to fetch the persistent state of a cache when joining a cluste= r. Only + one configured cache loader may set this property to true; if = more than + one cache loader does so, a configuration exception will be th= rown when + starting your cache service. + = - - async - determines whether writes to the cache - loader block until completed, or are run on a separate thread so = writes - return immediately. If this is set to true, an instance of - org.jboss.cache.loader.AsyncCacheLoader - is - constructed with an instance of the actual cache loader to be use= d. The - AsyncCacheLoader - then delegates all requests to the - underlying cache loader, using a separate thread if necessary. Se= e the - Javadocs on - AsyncCacheLoader - for more details. If unspecified, the - async - element - defaults to - false - . - + + async + determines whether writes to the cache + loader block until completed, or are run on a separate thread = so writes + return immediately. If this is set to true, an instance of + org.jboss.cache.loader.AsyncCacheLoader + is + constructed with an instance of the actual cache loader to be = used. The + AsyncCacheLoader + then delegates all requests to the + underlying cache loader, using a separate thread if necessary.= See the + Javadocs on + AsyncCacheLoader + for more details. If unspecified, the + async + element + defaults to + false + . + = - - Note on using the + + Note on using the + async + element: + + there is always the possibility of dirty reads since + all writes are performed asynchronously, and it is thus imposs= ible to + guarantee when (and even if) a write succeeds. This needs to b= e kept in + mind when setting the async - element: - - there is always the possibility of dirty reads since - all writes are performed asynchronously, and it is thus impossibl= e to - guarantee when (and even if) a write succeeds. This needs to be k= ept in - mind when setting the - async - element to true. - + element to true. + = - - ignoreModifications - determines whether write - methods are pushed down to the specific cache loader. Situations = may - arise where transient application data should only reside in a fi= le - based cache loader on the same server as the in-memory cache, for - example, with a further shared - JDBCCacheLoader - used by all servers in - the network. This feature allows you to write to the 'local' file= cache - loader but not the shared - JDBCCacheLoader - . This property defaults to - false - , so writes are propagated to all cache loaders - configured. - + + ignoreModifications + determines whether write + methods are pushed down to the specific cache loader. Situatio= ns may + arise where transient application data should only reside in a= file + based cache loader on the same server as the in-memory cache, = for + example, with a further shared + JDBCCacheLoader + used by all servers in + the network. This feature allows you to write to the 'local' f= ile cache + loader but not the shared + JDBCCacheLoader + . This property defaults to + false + , so writes are propagated to all cache loaders + configured. + = - - purgeOnStatup - empties the specified cache loader - (if - ignoreModifications - is - false - ) - when the cache loader starts up. - + + purgeOnStatup + empties the specified cache loader + (if + ignoreModifications + is + false + ) + when the cache loader starts up. + = - - shared - indicates that the cache loader is shared among different cache i= nstances, for example where all instances in a - cluster use the same JDBC settings t talk to the same remote, sha= red database. Setting this to - true - prevents repeated and unnecessary writes of the same data to the = cache loader by different cache instances. - Default value is - false - . - + + shared + indicates that the cache loader is shared among different cach= e instances, for example where all instances + in a + cluster use the same JDBC settings t talk to the same remote, = shared database. Setting this to + true + prevents repeated and unnecessary writes of the same data to t= he cache loader by different cache instances. + Default value is + false + . + = -
- Singleton Store Configuration +
+ Singleton Store Configuration = - @@ -322,458 +323,468 @@ - ]]> = - - singletonStore - element enables modifications to be stored by only one node in= the cluster, - the coordinator. Essentially, whenever any data comes in to so= me node - it is always replicated so as to keep the caches' in-memory st= ates in - sync; the coordinator, though, has the sole responsibility of = pushing - that state to disk. This functionality can be activated settin= g the - enabled - subelement to true in all nodes, but - again only the coordinator of the cluster will store the modif= ications - in the underlying cache loader as defined in - loader - element. You cannot define a cache loader as - shared - and with - singletonStore - enabled at the same time. - Default value for - enabled - is - false - . - + ]]> + + singletonStore + element enables modifications to be stored by only one nod= e in the cluster, + the coordinator. Essentially, whenever any data comes in t= o some node + it is always replicated so as to keep the caches' in-memor= y states in + sync; the coordinator, though, has the sole responsibility= of pushing + that state to disk. This functionality can be activated se= tting the + enabled + subelement to true in all nodes, but + again only the coordinator of the cluster will store the m= odifications + in the underlying cache loader as defined in + loader + element. You cannot define a cache loader as + shared + and with + singletonStore + enabled at the same time. + Default value for + enabled + is + false + . + = - - Optionally, within the - singletonStore - element, you can define a - class - element that specifies the implementation class that provides = the - singleton store functionality. This class must extend - org.jboss.cache.loader.AbstractDelegatingCacheLoader<= /literal> - , and if absent, it defaults to - org.jboss.cache.loader.SingletonStoreCacheLoader - . - + + Optionally, within the + singletonStore + element, you can define a + class + element that specifies the implementation class that provi= des the + singleton store functionality. This class must extend + org.jboss.cache.loader.AbstractDelegatingCacheLoa= der + , and if absent, it defaults to + org.jboss.cache.loader.SingletonStoreCacheLoader<= /literal> + . + = - - The - properties - subelement defines properties that allow changing the behavior= of the - class providing the singleton store functionality. By default, - pushStateWhenCoordinator - and - pushStateWhenCoordinatorTimeout - properties have been defined, but more could be added as - required by the user-defined class providing singleton store - functionality. - + + The + properties + subelement defines properties that allow changing the beha= vior of the + class providing the singleton store functionality. By defa= ult, + pushStateWhenCoordinator + and + pushStateWhenCoordinatorTimeout + properties have been defined, but more could be added as + required by the user-defined class providing singleton sto= re + functionality. + = - - pushStateWhenCoordinator - allows the in-memory - state to be pushed to the cache store when a node becomes the - coordinator, as a result of the new election of coordinator du= e to a - cluster topology change. This can be very useful in situations= where the - coordinator crashes and there's a gap in time until the new co= ordinator - is elected. During this time, if this property was set to - false - and the - cache was updated, these changes would never be persisted. Set= ting this - property to - true - would ensure that any changes during this process also - get stored in the cache loader. You would also want to set thi= s property - to - true - if each node's cache loader is configured with a different - location. Default value is - true - . - + + pushStateWhenCoordinator + allows the in-memory + state to be pushed to the cache store when a node becomes = the + coordinator, as a result of the new election of coordinato= r due to a + cluster topology change. This can be very useful in situat= ions where the + coordinator crashes and there's a gap in time until the ne= w coordinator + is elected. During this time, if this property was set to + false + and the + cache was updated, these changes would never be persisted.= Setting this + property to + true + would ensure that any changes during this process also + get stored in the cache loader. You would also want to set= this property + to + true + if each node's cache loader is configured with a different + location. Default value is + true + . + = - - pushStateWhenCoordinatorTimeout - is only relevant if - pushStateWhenCoordinator - is - true - in which case, sets the maximum number of milliseconds that th= e process - of pushing the in-memory state to the underlying cache loader = should take, - reporting a - PushStateException - if exceeded. Default value is 20000. - + + pushStateWhenCoordinatorTimeout + is only relevant if + pushStateWhenCoordinator + is + true + in which case, sets the maximum number of milliseconds tha= t the process + of pushing the in-memory state to the underlying cache loa= der should take, + reporting a + PushStateException + if exceeded. Default value is 20000. + = - - Note on using the - singletonStore - element: - - setting - up a cache loader as a singleton and using cache passivation (= via - evictions) can lead to undesired effects. If a node is to be p= assivated - as a result of an eviction, while the cluster is in the proces= s of - electing a new coordinator, the data will be lost. This is bec= ause no - coordinator is active at that time and therefore, none of the = nodes in - the cluster will store the passivated node. A new coordinator = is elected - in the cluster when either, the coordinator leaves the cluster= , the - coordinator crashes or stops responding. - -
+ + Note on using the + singletonStore + element: + + setting + up a cache loader as a singleton and using cache passivati= on (via + evictions) can lead to undesired effects. If a node is to = be passivated + as a result of an eviction, while the cluster is in the pr= ocess of + electing a new coordinator, the data will be lost. This is= because no + coordinator is active at that time and therefore, none of = the nodes in + the cluster will store the passivated node. A new coordina= tor is elected + in the cluster when either, the coordinator leaves the clu= ster, the + coordinator crashes or stops responding. + +
= -
+
= -
+
= - Shipped Implementations + Shipped Implementations = - The currently available implementations shipped with JBoss Cac= he are as follows. + The currently available implementations shipped with JBoss C= ache are as follows. = -
- File system based cache loaders - - JBoss Cache ships with several cache loaders that utilize the = file system as a data store. They all require - that the - ]]> - configuration element - contains a - location - property, which maps to a directory to be used as a persistent= store. - (e.g., - location=3D/tmp/myDataStore - ). Used mainly for testing and not recommended for production = use. - - - - - FileCacheLoader - , which is a simple filesystem-based implementation. By = default, this cache - loader checks for any potential character portability is= sues in the - location or tree node names, for example invalid charact= ers, producing - warning messages. These checks can be disabled adding - check.character.portability - property to the - ]]> - element and setting it to - false - (e.g., - check.character.portability=3Dfalse - ). - - - The FileCacheLoader has some severe limitations which re= strict its use in a production - environment, or if used in such an environment, it shoul= d be used with due care and sufficient - understanding of these limitations. - - Due to the way the FileCacheLoader represen= ts a tree structure on disk (directories and - files) traversal is inefficient for deep trees. - - Usage on shared filesystems like NFS, Windo= ws shares, etc. should be avoided as these do - not implement proper file locking and can cause da= ta corruption. - - Usage with an isolation level of NONE can c= ause corrupt writes as multiple threads - attempt to write to the same file. - - File systems are inherently not transaction= al, so when attempting to use your cache in a - transactional context, failures when writing to th= e file (which happens during the commit phase) - cannot be recovered. - - +
+ File system based cache loaders + + JBoss Cache ships with several cache loaders that utilize = the file system as a data store. They all + require + that the + ]]> + configuration element + contains a + location + property, which maps to a directory to be used as a persis= tent store. + (e.g., + location=3D/tmp/myDataStore + ). Used mainly for testing and not recommended for product= ion use. + + + + + FileCacheLoader + , which is a simple filesystem-based implementatio= n. By default, this cache + loader checks for any potential character portabil= ity issues in the + location or tree node names, for example invalid c= haracters, producing + warning messages. These checks can be disabled add= ing + check.character.portability + property to the + ]]> + element and setting it to + false + (e.g., + check.character.portability=3Dfalse + ). + + + The FileCacheLoader has some severe limitations wh= ich restrict its use in a production + environment, or if used in such an environment, it= should be used with due care and sufficient + understanding of these limitations. + + Due to the way the FileCacheLoader r= epresents a tree structure on disk + (directories and + files) traversal is inefficient for deep t= rees. + + Usage on shared filesystems like NFS= , Windows shares, etc. should be avoided as + these do + not implement proper file locking and can = cause data corruption. + + Usage with an isolation level of NON= E can cause corrupt writes as multiple threads + attempt to write to the same file. + + File systems are inherently not tran= sactional, so when attempting to use your + cache in a + transactional context, failures when writi= ng to the file (which happens during the + commit phase) + cannot be recovered. + + = - As a rule of thumb, it is recommended that the FileCache= Loader not be used in a highly concurrent, - transactional or stressful environment, and its use is r= estricted to testing. - - + As a rule of thumb, it is recommended that the Fil= eCacheLoader not be used in a highly + concurrent, + transactional or stressful environment, and its us= e is restricted to testing. + + = - - - BdbjeCacheLoader - , which is a cache loader implementation based on the Or= acle/Sleepycat's - BerkeleyDB Java Edition - . - - + + + BdbjeCacheLoader + , which is a cache loader implementation based on = the Oracle/Sleepycat's + BerkeleyDB Java Edition + + . + + = - - - JdbmCacheLoader - , which is a cache loader - implementation based on the - JDBM engine<= /ulink> - , a fast and free alternative to - BerkeleyDB. - - - + + + JdbmCacheLoader + , which is a cache loader + implementation based on the + JDBM e= ngine + , a fast and free alternative to + BerkeleyDB. + + + = - Note that the BerkeleyDB implementation is much more effici= ent than - the filesystem-based implementation, and provides transactional - guarantees, but requires a commercial license if distributed w= ith an - application (see http://www.oracle.com/database/berkeley-db/in= dex.html for - details). - + Note that the BerkeleyDB implementation is much more eff= icient than + the filesystem-based implementation, and provides transact= ional + guarantees, but requires a commercial license if distribut= ed with an + application (see http://www.oracle.com/database/berkeley-d= b/index.html for + details). + = -
+
= -
- Cache loaders that delegate to other caches - - - - LocalDelegatingCacheLoader - , which enables - loading from and storing to another local (same JVM) cac= he. - - - - - ClusteredCacheLoader - , which allows querying - of other caches in the same cluster for in-memory data v= ia the same - clustering protocols used to replicate data. Writes are - not - 'stored' though, as replication would - take care of any updates needed. You need to specify a p= roperty - called - timeout - , a long value telling the cache - loader how many milliseconds to wait for responses from = the cluster - before assuming a null value. For example, - timeout =3D 3000 - would use a timeout value of 3 seconds. - - - -
+
+ Cache loaders that delegate to other caches + + + + LocalDelegatingCacheLoader + , which enables + loading from and storing to another local (same JV= M) cache. + + + + + ClusteredCacheLoader + , which allows querying + of other caches in the same cluster for in-memory = data via the same + clustering protocols used to replicate data. Write= s are + not + 'stored' though, as replication would + take care of any updates needed. You need to speci= fy a property + called + timeout + , a long value telling the cache + loader how many milliseconds to wait for responses= from the cluster + before assuming a null value. For example, + timeout =3D 3000 + would use a timeout value of 3 seconds. + + + +
= = -
- JDBCCacheLoader +
+ JDBCCacheLoader = - JBossCache is distributed with a JDBC-based cache loader - implementation that stores/loads nodes' state into a relationa= l database. - The implementing class is - org.jboss.cache.loader.JDBCCacheLoader - . - + JBossCache is distributed with a JDBC-based cache loader + implementation that stores/loads nodes' state into a relat= ional database. + The implementing class is + org.jboss.cache.loader.JDBCCacheLoader + . + = - The current implementation uses just one table. Each row in= the table - represents one node and contains three columns: - - column for - Fqn - (which is also a primary key - column) - + The current implementation uses just one table. Each row= in the table + represents one node and contains three columns: + + column for + Fqn + (which is also a primary key + column) + = - column for node contents (attribute/value - pairs) - + column for node contents (attribute/value + pairs) + = - column for parent - Fqn - - - + column for parent + Fqn + + + = - - Fqns are stored as strings. Node content is= stored - as a BLOB. - WARNING: - JBoss Cache does not impose any - limitations on the types of objects used in - Fqn - but this implementation of - cache loader requires - Fqn - to contain only objects of type - java.lang.String - . Another limitation for - Fqn - is its - length. Since - Fqn - is a primary key, its default column type is - VARCHAR - which can store text values up to some - maximum length determined by the database in use. - + + Fqns are stored as strings. Node conten= t is stored + as a BLOB. + WARNING: + JBoss Cache does not impose any + limitations on the types of objects used in + Fqn + but this implementation of + cache loader requires + Fqn + to contain only objects of type + java.lang.String + . Another limitation for + Fqn + is its + length. Since + Fqn + is a primary key, its default column type is + VARCHAR + which can store text values up to some + maximum length determined by the database in use. + = - See - t= his wiki page - for configuration tips with specific database systems. - + See + this wiki page + for configuration tips with specific database systems. + = -
- JDBCCacheLoader configuration -
- Table configuration + JDBCCacheLoader configuration = - Table and column names as well as column types are - configurable with the following properties. - - - cache.jdbc.table.name - - the name - of the table. Can be prepended with schema name fo= r the given table: - {schema_name}.{table_name}. - The default value is 'jbosscache'. - +
+ Table configuration = - - cache.jdbc.table.primarykey - - the - name of the primary key for the table. The default= value is - 'jbosscache_pk'. - + Table and column names as well as column types a= re + configurable with the following properties. + + + cache.jdbc.table.name + - the name + of the table. Can be prepended with schema= name for the given table: + {schema_name}.{table_name}. + The default value is 'jbosscache'. + = - - cache.jdbc.table.create - - can be - true or false. Indicates whether to create the tab= le during startup. - If true, the table is created if it doesn't alread= y exist. The - default value is true. - + + cache.jdbc.table.primarykey + - the + name of the primary key for the table. The= default value is + 'jbosscache_pk'. + = - - cache.jdbc.table.drop - - can be - true or false. Indicates whether to drop the table= during shutdown. The - default value is true. - + + cache.jdbc.table.create + - can be + true or false. Indicates whether to create= the table during startup. + If true, the table is created if it doesn'= t already exist. The + default value is true. + = - - cache.jdbc.fqn.column - - FQN - column name. The default value is 'fqn'. - + + cache.jdbc.table.drop + - can be + true or false. Indicates whether to drop t= he table during shutdown. The + default value is true. + = - - cache.jdbc.fqn.type - - FQN column - type. The default value is 'varchar(255)'. - + + cache.jdbc.fqn.column + - FQN + column name. The default value is 'fqn'. + = - - cache.jdbc.node.column - - node - contents column name. The default value is 'node'. - + + cache.jdbc.fqn.type + - FQN column + type. The default value is 'varchar(255)'. + = - - cache.jdbc.node.type - - node - contents column type. The default value is 'blob'.= This type must specify - a valid binary data type for the database being us= ed. - - - -
+ + cache.jdbc.node.column + - node + contents column name. The default value is= 'node'. + = -
- DataSource + + cache.jdbc.node.type + - node + contents column type. The default value is= 'blob'. This type must specify + a valid binary data type for the database = being used. + + + +
= - If you are using JBossCache in a managed environment = (e.g., an - application server) you can specify the JNDI name of the= DataSource - you want to use. - - - cache.jdbc.datasource - - JNDI name - of the DataSource. The default value is - java:/DefaultDS - . - - - -
+
+ DataSource = -
- JDBC driver + If you are using JBossCache in a managed environ= ment (e.g., an + application server) you can specify the JNDI name = of the DataSource + you want to use. + + + cache.jdbc.datasource + - JNDI name + of the DataSource. The default value is + java:/DefaultDS + . + + + +
= - If you are - not - using DataSource you have - the following properties to configure database access us= ing a JDBC - driver. - - - cache.jdbc.driver - - fully - qualified JDBC driver name. - +
+ JDBC driver = - - cache.jdbc.url - - URL to connect - to the database. - + If you are + not + using DataSource you have + the following properties to configure database acc= ess using a JDBC + driver. + + + cache.jdbc.driver + - fully + qualified JDBC driver name. + = - - cache.jdbc.user - - user name to - connect to the database. - + + cache.jdbc.url + - URL to connect + to the database. + = - - cache.jdbc.password - - password to - connect to the database. - - - -
+ + cache.jdbc.user + - user name to + connect to the database. + = -
- c3p0 connection pooling + + cache.jdbc.password + - password to + connect to the database. + + + +
= - JBoss Cache implements JDBC connection pooling when r= unning outside of an application server - standalone using - the c3p0:JDBC DataSources/Resource Pools library. In ord= er to enable it, just edit the following - property: - - - cache.jdbc.connection.factory - - Connection factory class name. - If not set, it defaults to standard non-pooled imp= lementation. To enable c3p0 pooling, just set - the - connection factory class for c3p0. See example bel= ow. - - - +
+ c3p0 connection pooling = - You can also set any c3p0 parameters in the same cach= e loader properties section but don't forget - to - start the property name with 'c3p0.'. To find a list of = available properties, please check the - c3p0 documentation for the c3p0 library version distribu= ted in - c3p0= :JDBC DataSources/Resource Pools - . - Also, in order to provide quick and easy way to try out = different pooling - parameters, any of these properties can be set via a Sys= tem property overriding any values these - properties might have in the JBoss Cache XML configurati= on file, for example: - -Dc3p0.maxPoolSize=3D20 - . - If a c3p0 property is not defined in either the configur= ation file or as a System property, default - value, as indicated in the c3p0 documentation, will appl= y. - -
+ JBoss Cache implements JDBC connection pooling w= hen running outside of an application server + standalone using + the c3p0:JDBC DataSources/Resource Pools library. = In order to enable it, just edit the following + property: + + + cache.jdbc.connection.factory + - Connection factory class name. + If not set, it defaults to standard non-po= oled implementation. To enable c3p0 pooling, + just set + the + connection factory class for c3p0. See exa= mple below. + + + = -
- Configuration example + You can also set any c3p0 parameters in the same= cache loader properties section but don't + forget + to + start the property name with 'c3p0.'. To find a li= st of available properties, please check the + c3p0 documentation for the c3p0 library version di= stributed in + c3p0:JDBC DataSources/Resource Pools + . + Also, in order to provide quick and easy way to tr= y out different pooling + parameters, any of these properties can be set via= a System property overriding any values these + properties might have in the JBoss Cache XML confi= guration file, for example: + -Dc3p0.maxPoolSize=3D20 + . + If a c3p0 property is not defined in either the co= nfiguration file or as a System property, + default + value, as indicated in the c3p0 documentation, wil= l apply. + +
= - Below is an example of a JDBCCacheLoader using Oracle= as - database. The CacheLoaderConfiguration XML element conta= ins an - arbitrary set of properties which define the database-re= lated - configuration. - +
+ Configuration example = - Below is an example of a JDBCCacheLoader using O= racle as + database. The CacheLoaderConfiguration XML element= contains an + arbitrary set of properties which define the datab= ase-related + configuration. + + + @@ -787,9 +798,9 @@ cache.jdbc.table.drop=3Dtrue cache.jdbc.table.primarykey=3Djbosscache_pk cache.jdbc.fqn.column=3Dfqn - cache.jdbc.fqn.type=3Dvarchar(255) + cache.jdbc.fqn.type=3DVARCHAR(255) cache.jdbc.node.column=3Dnode - cache.jdbc.node.type=3Dblob + cache.jdbc.node.type=3DBLOB cache.jdbc.parent.column=3Dparent cache.jdbc.driver=3Doracle.jdbc.OracleDriver cache.jdbc.url=3Djdbc:oracle:thin:@localhost:1521:JBOSSDB @@ -801,11 +812,11 @@ ]]> = - As an alternative to configuring the entire JDBC conn= ection, - the name of an existing data source can be given: - + As an alternative to configuring the entire JDBC= connection, + the name of an existing data source can be given: + = - @@ -820,9 +831,9 @@ ]]> = - Cconfiguration example for a cache loader using c3p0 = JDBC connection pooling: + Cconfiguration example for a cache loader using = c3p0 JDBC connection pooling: = - @@ -836,9 +847,9 @@ cache.jdbc.table.drop=3Dtrue cache.jdbc.table.primarykey=3Djbosscache_pk cache.jdbc.fqn.column=3Dfqn - cache.jdbc.fqn.type=3Dvarchar(255) + cache.jdbc.fqn.type=3DVARCHAR(255) cache.jdbc.node.column=3Dnode - cache.jdbc.node.type=3Dblob + cache.jdbc.node.type=3DBLOB cache.jdbc.parent.column=3Dparent cache.jdbc.driver=3Doracle.jdbc.OracleDriver cache.jdbc.url=3Djdbc:oracle:thin:@localhost:1521:JBOSSDB @@ -853,79 +864,79 @@ ]]> = +
-
-
+
= -
- S3CacheLoader +
+ S3CacheLoader = - The - S3CacheLoader - uses the - Amazon S3 - (Simple Storage Solution) - for storing cache data. - Since Amazon S3 is remote network storage and has fairly high = latency, - it is really best for caches that store large pieces of data, = such as media - or files. - But consider this cache loader over the JDBC or - file system based cache loaders if you want remotely managed, = highly reliable - storage. Or, use it for applications running on Amazon's EC2 (= Elastic Compute Cloud). - + The + S3CacheLoader + uses the + Amazon S3 + (Simple Storage Solution) + for storing cache data. + Since Amazon S3 is remote network storage and has fairly h= igh latency, + it is really best for caches that store large pieces of da= ta, such as media + or files. + But consider this cache loader over the JDBC or + file system based cache loaders if you want remotely manag= ed, highly reliable + storage. Or, use it for applications running on Amazon's E= C2 (Elastic Compute Cloud). + = - - If you're planning to use Amazon S3 for storage, consider usin= g it with JBoss Cache. - JBoss Cache itself provides in-memory caching for your data to= minimize the amount of - remote access calls, thus reducing the latency and cost of fet= ching your Amazon S3 data. - With cache replication, you are also able to load data from yo= ur local cluster - without having to remotely access it every time. - + + If you're planning to use Amazon S3 for storage, consider = using it with JBoss Cache. + JBoss Cache itself provides in-memory caching for your dat= a to minimize the amount of + remote access calls, thus reducing the latency and cost of= fetching your Amazon S3 data. + With cache replication, you are also able to load data fro= m your local cluster + without having to remotely access it every time. + = - - Note that Amazon S3 does not support transactions. If transact= ions - are used in your application then there is some possibility of= state - inconsistency when using this cache loader. However, writes ar= e atomic, in - that if a write fails nothing is considered written and data i= s never - corrupted. - + + Note that Amazon S3 does not support transactions. If tran= sactions + are used in your application then there is some possibilit= y of state + inconsistency when using this cache loader. However, write= s are atomic, in + that if a write fails nothing is considered written and da= ta is never + corrupted. + = - - Data is stored in keys based on the Fqn of the Node and Node d= ata is - serialized as a java.util.Map using the - CacheSPI.getMarshaller() - instance. - Read the javadoc on how data is structured and stored. - Data is stored using Java serialization. - Be aware this means data is not readily accessible over HTTP to - non-JBoss Cache clients. Your feedback and help would be appre= ciated - to extend this cache loader for that purpose. - + + Data is stored in keys based on the Fqn of the Node and No= de data is + serialized as a java.util.Map using the + CacheSPI.getMarshaller() + instance. + Read the javadoc on how data is structured and stored. + Data is stored using Java serialization. + Be aware this means data is not readily accessible over HT= TP to + non-JBoss Cache clients. Your feedback and help would be a= ppreciated + to extend this cache loader for that purpose. + = - - With this cache loader, single-key operations such as - Node.remove(Object) - and - Node.put(Object, Object) - are the slowest as data is stored in a single Map instance. - Use bulk operations such as - Node.replaceAll(Map) - and - Node.clearData() - for more efficiency. - Try the - cache.s3.optimize - option as well. - + + With this cache loader, single-key operations such as + Node.remove(Object) + and + Node.put(Object, Object) + are the slowest as data is stored in a single Map instance. + Use bulk operations such as + Node.replaceAll(Map) + and + Node.clearData() + for more efficiency. + Try the + cache.s3.optimize + option as well. + = -
- Amazon S3 Library - The S3 cache loader is provided with the default - distribution but requires a library to access the service - at runtime. This runtime library may be obtained through a = Sourceforge Maven - Repository. Include the following sections in your pom.xml = file: - - + Amazon S3 Library + The S3 cache loader is provided with the default + distribution but requires a library to access the serv= ice + at runtime. This runtime library may be obtained throu= gh a Sourceforge Maven + Repository. Include the following sections in your pom= .xml file: + + e-xml.sourceforge.net http://e-xml.sourceforge.net/maven2/repository @@ -938,158 +949,163 @@ runtime ]]> - - If you do not use Maven, you can still download the - amazon-s3 library by navigating the repository or through - this URL. -
+ + If you do not use Maven, you can still download the + amazon-s3 library by navigating the repository or through + + this URL. +
= -
- Configuration - At a minimum, you must configure your Amazon S3 access k= ey and - secret access key. The following configuration keys are lis= ted in general - order of utility. - +
+ Configuration + At a minimum, you must configure your Amazon S3 acce= ss key and + secret access key. The following configuration keys ar= e listed in general + order of utility. + = - - - - cache.s3.accessKeyId - - - Amazon S3 Access Key, available from your account pro= file. - + + + + cache.s3.accessKeyId + - + Amazon S3 Access Key, available from your acco= unt profile. + = - - cache.s3.secretAccessKey - - - Amazon S3 Secret Access Key, available from your acco= unt profile. - As this is a password, be careful not to distribute i= t or include - this secret key in built software. - + + cache.s3.secretAccessKey + - + Amazon S3 Secret Access Key, available from yo= ur account profile. + As this is a password, be careful not to distr= ibute it or include + this secret key in built software. + = - - cache.s3.secure - - - The default isfalse: - Traffic is sent unencrypted over the public Internet. - Set to - true - to use HTTPS. - Note that unencrypted uploads and downloads use less = CPU. - + + cache.s3.secure + - + The default isfalse: + Traffic is sent unencrypted over the public In= ternet. + Set to + true + to use HTTPS. + Note that unencrypted uploads and downloads us= e less CPU. + = - - cache.s3.bucket - - - Name of the bucket to store data. - For different caches using the same access key, use a= different bucket name. - Read the S3 documentation on the definition of a buck= et. - The default value is jboss-cache. - + + cache.s3.bucket + - + Name of the bucket to store data. + For different caches using the same access key= , use a different bucket name. + Read the S3 documentation on the definition of= a bucket. + The default value isjboss-cache. + = - - cache.s3.callingFormat - - - One of PATH, SUBDOMAIN, or - VANITY. - Read the S3 documentation on the use of calling domai= ns. - The default value is SUBDOMAIN. - + + cache.s3.callingFormat + - + One ofPATH,SUBDOMA= IN, or + VANITY. + Read the S3 documentation on the use of callin= g domains. + The default value isSUBDOMAIN. + = - - cache.s3.optimize - - - The default is false. - If true, - put(Map) - operations - replace the data stored at an Fqn rather than attempt - to fetch and merge. (This option is fairly experiment= al - at the moment.) - + + cache.s3.optimize + - + The default isfalse. + If true, + put(Map) + operations + replace the data stored at an Fqn rather than = attempt + to fetch and merge. (This option is fairly exp= erimental + at the moment.) + = - - cache.s3.parentCache - - - The default is true. - Set this value to - false - if you are using multiple caches - sharing the same S3 bucket, that remove parent nodes = of nodes being created - in other caches. (This is not a common use case.) - - JBoss Cache stores nodes in a tree format and auto= matically - creates intermediate parent nodes as necessary. - The S3 cache loader must also create these parent = nodes as well - to allow for operations such as - getChildrenNames - to work - properly. Checking if all parent nodes exists for = every - put - operation is fairly expensive, so by default the c= ache loader caches - the existence of these parent nodes. - - + + cache.s3.parentCache + - + The default istrue. + Set this value to + false + if you are using multiple caches + sharing the same S3 bucket, that remove parent= nodes of nodes being created + in other caches. (This is not a common use cas= e.) + + JBoss Cache stores nodes in a tree format = and automatically + creates intermediate parent nodes as neces= sary. + The S3 cache loader must also create these= parent nodes as well + to allow for operations such as + getChildrenNames + to work + properly. Checking if all parent nodes exi= sts for every + put + operation is fairly expensive, so by defau= lt the cache loader caches + the existence of these parent nodes. + + = - - cache.s3.location - - - This choses a primary storage location for your data - to reduce loading and retrieval latency. - Set to EU - to store data in Europe. - The default is null, to store data= in - the United States. - - - -
+ + cache.s3.location + - + This choses a primary storage location for you= r data + to reduce loading and retrieval latency. + Set to + EU + to store data in Europe. + The default isnull, to stor= e data in + the United States. + + + +
= -
+
= -
- TcpDelegatingCacheLoader +
+ TcpDelegatingCacheLoader = - This cache loader allows to delegate loads and stores to an= other - instance of JBoss Cache, which could reside (a) in the same ad= dress - space, (b) in a different process on the same host, or (c) in a - different process on a different host. - + This cache loader allows to delegate loads and stores to= another + instance of JBoss Cache, which could reside (a) in the sam= e address + space, (b) in a different process on the same host, or (c)= in a + different process on a different host. + = - A TcpDelegatingCacheLoader talks to a remote - org.jboss.cache.loader.tcp.TcpCacheServer - , - which can be a standalone process started on the command line,= or embedded as an MBean inside - JBoss AS. The - TcpCacheServer - has a reference to another JBoss Cache instance, which - it can create itself, or which is given to it (e.g. by JBoss, = using - dependency injection). - + A TcpDelegatingCacheLoader talks to a remote + org.jboss.cache.loader.tcp.TcpCacheServer + , + which can be a standalone process started on the command l= ine, or embedded as an MBean inside + JBoss AS. The + TcpCacheServer + has a reference to another JBoss Cache instance, which + it can create itself, or which is given to it (e.g. by JBo= ss, using + dependency injection). + = - - As of JBoss Cache 2.1.0, the TcpDelegatingCacheLoader= transparently handles reconnects if the connection - to the TcpCacheServer is lost. - + + As of JBoss Cache 2.1.0, the + TcpDelegatingCacheLoader + transparently handles reconnects if the connection + to the TcpCacheServer is lost. + = - The TcpDelegatingCacheLoader is configured with the host an= d port of the remote TcpCacheServer, and uses - this to communicate to - it. In addition, 2 new optional parameters are used to control= transparent reconnecting to the - TcpCacheServer. - The - timeout - property (defaults to 5000) specifies the length of time the c= ache loader must continue - retrying to connect to the TcpCacheServer before giving up and= throwing an exception. The - reconnectWaitTime - (defaults to 500) is how long the cache loader should wait bef= ore attempting a reconnect if it detects a - communication failure. - The last two parameters can be used to add a level of fault to= lerance to the cache loader, do deal with - TcpCacheServer restarts. - + The TcpDelegatingCacheLoader is configured with the host= and port of the remote TcpCacheServer, and + uses + this to communicate to + it. In addition, 2 new optional parameters are used to con= trol transparent reconnecting to the + TcpCacheServer. + The + timeout + property (defaults to 5000) specifies the length of time t= he cache loader must continue + retrying to connect to the TcpCacheServer before giving up= and throwing an exception. The + reconnectWaitTime + (defaults to 500) is how long the cache loader should wait= before attempting a reconnect if it detects a + communication failure. + The last two parameters can be used to add a level of faul= t tolerance to the cache loader, do deal with + TcpCacheServer restarts. + = - The configuration looks as follows: + The configuration looks as follows: = - @@ -1106,434 +1122,438 @@ ]]> = - This means this instance of JBoss Cache will delegate all l= oad - and store requests to the remote TcpCacheServer running on - myRemoteServer:7500 - . - + This means this instance of JBoss Cache will delegate al= l load + and store requests to the remote TcpCacheServer running on + myRemoteServer:7500 + . + = - A typical use case could be multiple replicated instances of - JBoss Cache in the same cluster, all delegating to the same - TcpCacheServer instance. The TcpCacheServer might itself deleg= ate to a - database via JDBCCacheLoader, but the point here is that - if = we have - 5 nodes all accessing the same dataset - they will load the da= ta from - the TcpCacheServer, which has do execute one SQL statement per - unloaded data set. If the nodes went directly to the database,= then - we'd have the same SQL executed multiple times. So TcpCacheSer= ver - serves as a natural cache in front of the DB (assuming that a = network - round trip is faster than a DB access (which usually also incl= ude a - network round trip)). - + A typical use case could be multiple replicated instance= s of + JBoss Cache in the same cluster, all delegating to the same + TcpCacheServer instance. The TcpCacheServer might itself d= elegate to a + database via JDBCCacheLoader, but the point here is that -= if we have + 5 nodes all accessing the same dataset - they will load th= e data from + the TcpCacheServer, which has do execute one SQL statement= per + unloaded data set. If the nodes went directly to the datab= ase, then + we'd have the same SQL executed multiple times. So TcpCach= eServer + serves as a natural cache in front of the DB (assuming tha= t a network + round trip is faster than a DB access (which usually also = include a + network round trip)). + = - To alleviate single point of failure, we could configure se= veral cache loaders. - The first cache loader is a ClusteredCacheLoader, the second a= TcpDelegatingCacheLoader, and the - last a JDBCacheLoader, effectively defining our cost of access= to a - cache in increasing order. - + To alleviate single point of failure, we could configure= several cache loaders. + The first cache loader is a ClusteredCacheLoader, the seco= nd a TcpDelegatingCacheLoader, and the + last a JDBCacheLoader, effectively defining our cost of ac= cess to a + cache in increasing order. + = -
+
= -
- Transforming Cache Loaders +
+ Transforming Cache Loaders = - The way cached data is written to - FileCacheLoader - and - JDBCCacheLoader - based cache stores has changed in JBoss Cache 2.0 in such way = that - these cache loaders now write and read data using the same mar= halling framework used to replicate data - across the network. Such change is trivial for replication pur= poses as it just requires the rest of the - nodes to understand this format. However, changing the format = of the data in cache stores brings up a new - problem: how do users, which have their data stored in JBoss C= ache 1.x.x format, migrate their stores to - JBoss Cache 2.0 format? - + The way cached data is written to + FileCacheLoader + and + JDBCCacheLoader + based cache stores has changed in JBoss Cache 2.0 in such = way that + these cache loaders now write and read data using the same= marhalling framework used to replicate data + across the network. Such change is trivial for replication= purposes as it just requires the rest of the + nodes to understand this format. However, changing the for= mat of the data in cache stores brings up a + new + problem: how do users, which have their data stored in JBo= ss Cache 1.x.x format, migrate their stores to + JBoss Cache 2.0 format? + = - With this in mind, JBoss Cache 2.0 comes with two cache loa= der implementations called - org.jboss.cache.loader.TransformingFileCacheLoader - and - org.jboss.cache.loader.TransformingJDBCCacheLoader - located within the optional - jbosscache-cacheloader-migration.jar file. These are one-off c= ache loaders that read data from the - cache store in JBoss Cache 1.x.x format and write data to cach= e stores in JBoss Cache 2.0 format. - + With this in mind, JBoss Cache 2.0 comes with two cache = loader implementations called + org.jboss.cache.loader.TransformingFileCacheLoade= r + and + org.jboss.cache.loader.TransformingJDBCCacheLoade= r + located within the optional + jbosscache-cacheloader-migration.jar file. These are one-o= ff cache loaders that read data from the + cache store in JBoss Cache 1.x.x format and write data to = cache stores in JBoss Cache 2.0 format. + = - The idea is for users to modify their existing cache config= uration file(s) momentarily to use these - cache loaders and for them to create a small Java application = that creates an instance of this cache, - recursively reads the entire cache and writes the data read ba= ck into the cache. Once the data is - transformed, users can revert back to their original cache con= figuration file(s). In order to help the users - with this task, a cache loader migration example has been cons= tructed which can be located under the - examples/cacheloader-migration - directory within the JBoss Cache distribution. This - example, called - examples.TransformStore - , is independent of the actual data stored in - the cache as it writes back whatever it was read recursively. = It is highly recommended that anyone - interested in porting their data run this example first, which= contains a - readme.txt - file with detailed information about the example itself, and a= lso use it as base for their own application. - + The idea is for users to modify their existing cache con= figuration file(s) momentarily to use these + cache loaders and for them to create a small Java applicat= ion that creates an instance of this cache, + recursively reads the entire cache and writes the data rea= d back into the cache. Once the data is + transformed, users can revert back to their original cache= configuration file(s). In order to help the + users + with this task, a cache loader migration example has been = constructed which can be located under the + examples/cacheloader-migration + directory within the JBoss Cache distribution. This + example, called + examples.TransformStore + , is independent of the actual data stored in + the cache as it writes back whatever it was read recursive= ly. It is highly recommended that anyone + interested in porting their data run this example first, w= hich contains a + readme.txt + file with detailed information about the example itself, a= nd also use it as base for their own + application. + = -
+
= -
+ = = -
- Cache Passivation +
+ Cache Passivation = - A cache loader can be used to enforce node passivation and - activation on eviction in a cache. - + A cache loader can be used to enforce node passivation and + activation on eviction in a cache. + = - - Cache Passivation - is the process of removing - an object from in-memory cache and writing it to a secondary data= store - (e.g., file system, database) on eviction. - Cache - Activation - - is the process of restoring an object from the - data store into the in-memory cache when it's needed to be used. = In both - cases, the configured cache loader will be used to read from the = data - store and write to the data store. - + + Cache Passivation + is the process of removing + an object from in-memory cache and writing it to a secondary d= ata store + (e.g., file system, database) on eviction. + Cache + Activation + + is the process of restoring an object from the + data store into the in-memory cache when it's needed to be use= d. In both + cases, the configured cache loader will be used to read from t= he data + store and write to the data store. + = - When an eviction policy in effect evicts a node - from the cache, if passivation is enabled, a notification that th= e node - is being passivated will be emitted to the cache listeners and the - node and its children will be stored in the cache loader store. W= hen a - user attempts to retrieve a node that was evicted earlier, the no= de is loaded - (lazy loaded) from the cache loader store into memory. When - the node and its children have been loaded, they're removed from = the - cache loader and a notification is emitted to the cache listeners - that the node has been activated. - + When an eviction policy in effect evicts a node + from the cache, if passivation is enabled, a notification that= the node + is being passivated will be emitted to the cache listeners and= the + node and its children will be stored in the cache loader store= . When a + user attempts to retrieve a node that was evicted earlier, the= node is loaded + (lazy loaded) from the cache loader store into memory. When + the node and its children have been loaded, they're removed fr= om the + cache loader and a notification is emitted to the cache listen= ers + that the node has been activated. + = - To enable cache passivation/activation, you can set - passivation - to true. The default is - false - . - When passivation is used, only the first cache loader configured = is - used and all others are ignored. - + To enable cache passivation/activation, you can set + passivation + to true. The default is + false + . + When passivation is used, only the first cache loader configur= ed is + used and all others are ignored. + = -
- Cache Loader Behavior with Passivation Disabled vs. Enable= d +
+ Cache Loader Behavior with Passivation Disabled vs. Ena= bled = - - When passivation is disabled, whenever an element is modified,= added or - removed, then that modification is persisted in the backend st= ore via - the cache loader. There is no direct relationship between evic= tion and - cache loading. If you don't use eviction, what's in the persis= tent store - is basically a copy of what's in memory. If you do use evictio= n, what's - in the persistent store is basically a superset of what's in m= emory - (i.e. it includes nodes that have been evicted from memory). - + + When passivation is disabled, whenever an element is modif= ied, added or + removed, then that modification is persisted in the backen= d store via + the cache loader. There is no direct relationship between = eviction and + cache loading. If you don't use eviction, what's in the pe= rsistent store + is basically a copy of what's in memory. If you do use evi= ction, what's + in the persistent store is basically a superset of what's = in memory + (i.e. it includes nodes that have been evicted from memory= ). + = - - When passivation is enabled, there is a direct relationship be= tween - eviction and the cache loader. Writes to the persistent store = via the - cache loader only occur as part of the eviction process. Data = is deleted - from the persistent store when the application reads it back i= nto - memory. In this case, what's in memory and what's in the persi= stent - store are two subsets of the total information set, with no in= tersection between the subsets. - + + When passivation is enabled, there is a direct relationshi= p between + eviction and the cache loader. Writes to the persistent st= ore via the + cache loader only occur as part of the eviction process. D= ata is deleted + from the persistent store when the application reads it ba= ck into + memory. In this case, what's in memory and what's in the p= ersistent + store are two subsets of the total information set, with n= o intersection between the subsets. + = - - Following is a simple example, showing what state is in RAM an= d in the - persistent store after each step of a 6 step process: - + + Following is a simple example, showing what state is in RA= M and in the + persistent store after each step of a 6 step process: + = - - Insert /A - Insert /B - Eviction thread runs, evicts /A - Read /A - Eviction thread runs, evicts /B - Remove /B - + + Insert /A + Insert /B + Eviction thread runs, evicts /A + Read /A + Eviction thread runs, evicts /B + Remove /B + = - When passivation is disabled: - - 1) Memory: /A Disk: /A - 2) Memory: /A, /B Disk: /A, /B - 3) Memory: /B Disk: /A, /B - 4) Memory: /A, /B Disk: /A, /B - 5) Memory: /A Disk: /A, /B - 6) Memory: /A Disk: /A - + When passivation is disabled: + + 1) Memory: /A Disk: /A + 2) Memory: /A, /B Disk: /A, /B + 3) Memory: /B Disk: /A, /B + 4) Memory: /A, /B Disk: /A, /B + 5) Memory: /A Disk: /A, /B + 6) Memory: /A Disk: /A + = - When passivation is enabled: - - 1) Memory: /A Disk: - 2) Memory: /A, /B Disk: - 3) Memory: /B Disk: /A - 4) Memory: /A, /B Disk: - 5) Memory: /A Disk: /B - 6) Memory: /A Disk: - -
+ When passivation is enabled: + + 1) Memory: /A Disk: + 2) Memory: /A, /B Disk: + 3) Memory: /B Disk: /A + 4) Memory: /A, /B Disk: + 5) Memory: /A Disk: /B + 6) Memory: /A Disk: + +
= -
+
= -
- Strategies - - This section discusses different patterns of combining different = cache loader types and configuration - options to achieve specific outcomes. - +
+ Strategies + + This section discusses different patterns of combining differe= nt cache loader types and configuration + options to achieve specific outcomes. + = -
- Local Cache With Store +
+ Local Cache With Store = - This is the simplest case. We have a JBoss Cache instance, = whose - cache mode is - LOCAL - , therefore no replication is going - on. The cache loader simply loads non-existing elements from t= he store - and stores modifications back to the store. When the cache is = started, - depending on the - preload - element, certain data can - be preloaded, so that the cache is partly warmed up. - -
+ This is the simplest case. We have a JBoss Cache instanc= e, whose + cache mode is + LOCAL + , therefore no replication is going + on. The cache loader simply loads non-existing elements fr= om the store + and stores modifications back to the store. When the cache= is started, + depending on the + preload + element, certain data can + be preloaded, so that the cache is partly warmed up. + +
= -
- Replicated Caches With All Caches Sharing The Same Store</= title> + <section> + <title>Replicated Caches With All Caches Sharing The Same Stor= e = - The following figure shows 2 JBoss Cache instances sharing = the same - backend store: - + The following figure shows 2 JBoss Cache instances shari= ng the same + backend store: + = -
- 2 nodes sharing a backend store +
+ 2 nodes sharing a backend store = - - - - - -
+ + + + + +
= - Both nodes have a cache loader that accesses a common shared - backend store. This could for example be a shared filesystem (= using - the FileCacheLoader), or a shared database. Because both nodes= access - the same store, they don't necessarily need state transfer on - startup. - - Of course they can enable state transfer, if they wan= t to - have a warm or hot cache after startup. - - - Rather, the - FetchInMemoryState - attribute could be set to false, resulting in a 'cold' cache, = that - gradually warms up as elements are accessed and loaded for the= first - time. This would mean that individual caches in a cluster migh= t have - different in-memory state at any given time (largely depending= on - their preloading and eviction strategies). - + Both nodes have a cache loader that accesses a common sh= ared + backend store. This could for example be a shared filesyst= em (using + the FileCacheLoader), or a shared database. Because both n= odes access + the same store, they don't necessarily need state transfer= on + startup. + + Of course they can enable state transfer, if the= y want to + have a warm or hot cache after startup. + + + Rather, the + FetchInMemoryState + attribute could be set to false, resulting in a 'cold' cac= he, that + gradually warms up as elements are accessed and loaded for= the first + time. This would mean that individual caches in a cluster = might have + different in-memory state at any given time (largely depen= ding on + their preloading and eviction strategies). + = - When storing a value, the writer takes care of storing the - change in the backend store. For example, if node1 made change= C1 and - node2 C2, then node1 would tell its cache loader to store C1, = and node2 - would tell its cache loader to store C2. - -
+ When storing a value, the writer takes care of storing t= he + change in the backend store. For example, if node1 made ch= ange C1 and + node2 C2, then node1 would tell its cache loader to store = C1, and node2 + would tell its cache loader to store C2. + +
= -
- Replicated Caches With Only One Cache Having A Store</titl= e> + <section> + <title>Replicated Caches With Only One Cache Having A Store</t= itle> = - <figure> - <title>2 nodes but only one accesses the backend store +
+ 2 nodes but only one accesses the backend store</ti= tle> = - <mediaobject> - <imageobject> - <imagedata fileref=3D"OnlyOneCacheLoader.png"/> - </imageobject> - </mediaobject> - </figure> + <mediaobject> + <imageobject> + <imagedata fileref=3D"OnlyOneCacheLoader.png"/> + </imageobject> + </mediaobject> + </figure> = - <para>This is a similar case to the previous one, but here only o= ne - node in the cluster interacts with a backend store via its - cache loader. All other nodes perform in-memory replication. T= he idea - here is all application state is kept in memory in each node, = with - the existence of multiple caches making the data highly availa= ble. - (This assumes that a client that needs the data is able to som= ehow - fail over from one cache to another.) The single persistent ba= ckend - store then provides a backup copy of the data in case all cach= es in - the cluster fail or need to be restarted. - </para> - <para> - Note that here it may make sense for the cache loader to store - changes asynchronously, that is - <emphasis>not</emphasis> - on the caller's thread, in order not to slow - down the cluster by accessing (for example) a database. This i= s a - non-issue when using asynchronous replication. - </para> - <para> - A weakness with this architecture is that the cache with access - to the cache loader becomes a single point of failure. Further= more, - if the cluster is restarted, the cache with the cache loader m= ust - be started first (easy to forget). A solution to the first pro= blem - is to configure a cache loader on each node, but set the - <literal>singletonStore</literal> - configuration to - <literal>true</literal>. With this kind of setup, one but only= one - node will always be writing to a persistent store. However, th= is - complicates the restart problem, as before restarting you need - to determine which cache was writing before the shutdown/failu= re - and then start that cache first. - </para> - </section> + <para>This is a similar case to the previous one, but here onl= y one + node in the cluster interacts with a backend store via its + cache loader. All other nodes perform in-memory replicatio= n. The idea + here is all application state is kept in memory in each no= de, with + the existence of multiple caches making the data highly av= ailable. + (This assumes that a client that needs the data is able to= somehow + fail over from one cache to another.) The single persisten= t backend + store then provides a backup copy of the data in case all = caches in + the cluster fail or need to be restarted. + </para> + <para> + Note that here it may make sense for the cache loader to s= tore + changes asynchronously, that is + <emphasis>not</emphasis> + on the caller's thread, in order not to slow + down the cluster by accessing (for example) a database. Th= is is a + non-issue when using asynchronous replication. + </para> + <para> + A weakness with this architecture is that the cache with a= ccess + to the cache loader becomes a single point of failure. Fur= thermore, + if the cluster is restarted, the cache with the cache load= er must + be started first (easy to forget). A solution to the first= problem + is to configure a cache loader on each node, but set the + <literal>singletonStore</literal> + configuration to + <literal>true</literal>. With this kind of setup, one but = only one + node will always be writing to a persistent store. However= , this + complicates the restart problem, as before restarting you = need + to determine which cache was writing before the shutdown/f= ailure + and then start that cache first. + </para> + </section> = - <section> - <title>Replicated Caches With Each Cache Having Its Own Store</ti= tle> + <section> + <title>Replicated Caches With Each Cache Having Its Own Store<= /title> = - <figure> - <title>2 nodes each having its own backend store +
+ 2 nodes each having its own backend store = - - - - - -
+ + + + + +
= - Here, each node has its own datastore. Modifications to the - cache are (a) replicated across the cluster and (b) persisted = using - the cache loader. This means that all datastores have exactly = the same - state. When replicating changes synchronously and in a transac= tion, - the two phase commit protocol takes care that all modification= s are - replicated and persisted in each datastore, or none is replica= ted and - persisted (atomic updates). - + Here, each node has its own datastore. Modifications to = the + cache are (a) replicated across the cluster and (b) persis= ted using + the cache loader. This means that all datastores have exac= tly the same + state. When replicating changes synchronously and in a tra= nsaction, + the two phase commit protocol takes care that all modifica= tions are + replicated and persisted in each datastore, or none is rep= licated and + persisted (atomic updates). + = - Note that JBoss Cache is - not - an - XA Resource, that means it doesn't implement recovery. When us= ed with a - transaction manager that supports recovery, this functionality= is not - available. - + Note that JBoss Cache is + not + an + XA Resource, that means it doesn't implement recovery. Whe= n used with a + transaction manager that supports recovery, this functiona= lity is not + available. + = - The challenge here is state transfer: when a new node start= s it - needs to do the following: - + The challenge here is state transfer: when a new node st= arts it + needs to do the following: + = - - - Tell the coordinator (oldest node in a cluster) to se= nd it - the state. This is always a full state transfer, overwri= ting - any state that may already be present. - - + + + Tell the coordinator (oldest node in a cluster) = to send it + the state. This is always a full state transfer, o= verwriting + any state that may already be present. + + = - - The coordinator then needs to wait until all in-flight - transactions have completed. During this time, it will n= ot allow - for new transactions to be started. - - + + The coordinator then needs to wait until all in-= flight + transactions have completed. During this time, it = will not allow + for new transactions to be started. + + = - - Then the coordinator asks its cache loader for the en= tire - state using - loadEntireState() - . It then sends - back that state to the new node. - - + + Then the coordinator asks its cache loader for t= he entire + state using + loadEntireState() + . It then sends + back that state to the new node. + + = - - The new node then tells its cache loader to store tha= t state - in its store, overwriting the old state. This is the - CacheLoader.storeEntireState() - method - - + + The new node then tells its cache loader to stor= e that state + in its store, overwriting the old state. This is t= he + CacheLoader.storeEntireState() + method + + = - - As an option, the transient (in-memory) state can be - transferred as well during the state transfer. - - + + As an option, the transient (in-memory) state ca= n be + transferred as well during the state transfer. + + = - - The new node now has the same state in its backend st= ore as - everyone else in the cluster, and modifications received= from - other nodes will now be persisted using the local - cache loader. - - - + + The new node now has the same state in its backe= nd store as + everyone else in the cluster, and modifications re= ceived from + other nodes will now be persisted using the local + cache loader. + + + = = -
+
= -
- Hierarchical Caches +
+ Hierarchical Caches = - If you need to set up a hierarchy within a single JVM, you = can - use the - LocalDelegatingCacheLoader - . This type of - hierarchy can currently only be set up programmatically. - + If you need to set up a hierarchy within a single JVM, y= ou can + use the + LocalDelegatingCacheLoader + . This type of + hierarchy can currently only be set up programmatically. + = - - Hierarchical caches could also be set up spanning more than on= e JVM or server, using the - TcpDelegatingCacheLoader - . -
- TCP delegating cache loader + + Hierarchical caches could also be set up spanning more tha= n one JVM or server, using the + TcpDelegatingCacheLoader + . +
+ TCP delegating cache loader = - - - - - -
+ + + + + +
= - + = -
+
= = -
- Multiple Cache Loaders +
+ Multiple Cache Loaders = - - You can set up more than one cache loader in a chain. Internal= ly, a delegating - ChainingCacheLoader - is used, with references to each - cache loader you have configured. Use cases vary depending on = the type of cache loaders used in the chain. - One example is - using a filesystem based cache loader, co-located on the same = host as the JVM, used as an overflow for - memory. This ensures - data is available relatively easily and with low cost. An addi= tional remote cache loader, such as a - TcpDelegatingCacheLoader - provides resilience between server restarts. - + + You can set up more than one cache loader in a chain. Inte= rnally, a delegating + ChainingCacheLoader + is used, with references to each + cache loader you have configured. Use cases vary depending= on the type of cache loaders used in the + chain. + One example is + using a filesystem based cache loader, co-located on the s= ame host as the JVM, used as an overflow for + memory. This ensures + data is available relatively easily and with low cost. An = additional remote cache loader, such as a + TcpDelegatingCacheLoader + provides resilience between server restarts. + = -
- Multiple cache loaders in a chain +
+ Multiple cache loaders in a chain = - - - - - -
+ + + + + +
= -
+
= = - + = = Modified: core/trunk/src/main/resources/config-samples/all.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- core/trunk/src/main/resources/config-samples/all.xml 2009-01-05 17:54:5= 9 UTC (rev 7380) +++ core/trunk/src/main/resources/config-samples/all.xml 2009-01-06 11:08:4= 1 UTC (rev 7381) @@ -181,9 +181,9 @@ cache.jdbc.table.drop=3Dtrue cache.jdbc.table.primarykey=3Djbosscache_pk cache.jdbc.fqn.column=3Dfqn - cache.jdbc.fqn.type=3Dvarchar(255) + cache.jdbc.fqn.type=3DVARCHAR(255) cache.jdbc.node.column=3Dnode - cache.jdbc.node.type=3Dblob + cache.jdbc.node.type=3DBINARY cache.jdbc.parent.column=3Dparent cache.jdbc.driver=3Dorg.hsqldb.jdbcDriver cache.jdbc.url=3Djdbc:hsqldb:mem:jbosscache Modified: core/trunk/src/main/resources/config-samples/cacheloader-enabled.= xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- core/trunk/src/main/resources/config-samples/cacheloader-enabled.xml 20= 09-01-05 17:54:59 UTC (rev 7380) +++ core/trunk/src/main/resources/config-samples/cacheloader-enabled.xml 20= 09-01-06 11:08:41 UTC (rev 7381) @@ -39,9 +39,9 @@ cache.jdbc.table.drop=3Dtrue cache.jdbc.table.primarykey=3Djbosscache_pk cache.jdbc.fqn.column=3Dfqn - cache.jdbc.fqn.type=3Dvarchar(255) + cache.jdbc.fqn.type=3DVARCHAR(255) cache.jdbc.node.column=3Dnode - cache.jdbc.node.type=3Dblob + cache.jdbc.node.type=3DBINARY cache.jdbc.parent.column=3Dparent cache.jdbc.driver=3Dorg.hsqldb.jdbcDriver cache.jdbc.url=3Djdbc:hsqldb:mem:jbosscache Modified: core/trunk/src/test/java/org/jboss/cache/config/parsing/SampleCon= figFilesCorrectnessTest.java =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- core/trunk/src/test/java/org/jboss/cache/config/parsing/SampleConfigFil= esCorrectnessTest.java 2009-01-05 17:54:59 UTC (rev 7380) +++ core/trunk/src/test/java/org/jboss/cache/config/parsing/SampleConfigFil= esCorrectnessTest.java 2009-01-06 11:08:41 UTC (rev 7381) @@ -21,6 +21,8 @@ */ package org.jboss.cache.config.parsing; = +import org.apache.commons.logging.Log; +import org.apache.commons.logging.LogFactory; import org.apache.log4j.AppenderSkeleton; import org.apache.log4j.Level; import org.apache.log4j.Logger; @@ -50,6 +52,7 @@ = private InMemoryAppender appender; private Level oldLevel; + private Log log =3D LogFactory.getLog(SampleConfigFilesCorrectnessTest.= class); = @BeforeMethod public void setUpTest() @@ -112,13 +115,14 @@ = private static class InMemoryAppender extends AppenderSkeleton { - String[] TOLERABLE_WARNINGS =3D {"Falling back to DummyTransactionMa= nager"}; + String[] TOLERABLE_WARNINGS =3D {"DummyTransactionManager"}; boolean foundUnknownWarning =3D false; = /** * As this test runs in parallel with other tests tha also log infor= mation, we should disregard * other possible warnings from other threads and only consider warn= ings issues within this test class's test. - * @see #isExpectedThread() = + * + * @see #isExpectedThread() */ private Thread loggerThread =3D Thread.currentThread(); = @@ -136,6 +140,8 @@ foundUnknownWarning =3D false; } } + + if (!skipPrinting) System.out.println("****** " + event.getMes= sage().toString()); } } = --===============2007098541721027437==--