JBoss.org Community Documentation
JBoss Cache consists of two components, Core Cache, and POJO Cache. Core Cache provides efficient memory storage, transactions, replication, eviction, persistent storage, and many other "core" features you would expect from a distributed cache. The Core Cache API is tree based. Data is arranged on the tree using nodes that each offer a map of attributes. This map-like API is intuitive and easy to use for caching data, but just like the Java Collection API, it operates only off of simple and serializable types. Therefore, it has the following constraints:
Serializable
interface. E.g.,
public Class Foo implements Serializable
value = new Foo();
cache.put(fqn, key, value);
value.update(); // update value
cache.put(fqn, key, value); // Need to repeat this step again to ask cache to persist or replicate the changes
thousand = new ThousandFieldObject();
cache.put(fqn, key, thousand);
thousand.setField1("blah"); // Only one field was modified
cache.put(fqn, key, thousand); // Replicates 1000 fields
Person
instances that share the same
Address
,
upon replication, it will be split into two separate
Address
instances (instead of just one). The following is the code snippet using Cache that illustrates this
problem:
joe = new Person("joe");
mary = new Person("mary");
addr = new Address("Taipei");
joe.setAddress(addr);
mary.setAddress(addr);
cache.put("/joe", "person", joe);
cache.put("/mary", "person", mary);
POJO Cache attempts to address these issues by building a layer on top of Core Cache which transparently maps normal Java object model operations to individual Node operations on the cache. This offers the following improvements:
Serializable
interface. Instead they are instrumented,
allowing POJO Cache to intercept individual operations.
POJO pojo = new POJO();
pojoCache.attach("id", pojo);
pojo.setName("some pojo"); // This will trigger replication automatically.
In POJO Cache, these are the typical development and programming steps:
@Replicable
attach()
to put your POJO under cache management.
More details on these steps will be given in later chapters.
Since POJO Cache is a layer on-top of Core Cache, all features available in Core Cache are also available in POJO Cache. Furthermore, you can obtain an instance to the underlying Core Cache by calling PojoCache.getCache()
. This is useful for resusing the same cache instance to store custom data, along with the POJO model.
Here are the current features and benefits of PojoCache:
Fine-grained replication. The replication modes supported are the
same as that of Core Cache:
LOCAL
, REPL_SYNC
, REPL_ASYNC
,
INVALIDATION_SYNC
, and INVALIDATION_ASYNC
(see the
main JBoss Cache reference documentation for details). The
replication level is fine-grained and is performed automatically once the POJO is mapped into the
internal cache store. When a POJO field is updated, a replication request
will be sent out only to the key
corresponding to that modified attribute (instead of the whole
object). This can have a potential performance boost during the replication
process; e.g., updating a single key in a big HashMap will only
replicate the single field instead of the whole map!
POJO p = new POJO();
p.setName("old value");
pojoCache.attach("id", p);
tx.begin(); // start a user transaction
p.setName("some pojo");
tx.rollback(); // this will cause the rollback
p.getName(); // is "old value"
In addition, operations under a transaction is batched. That is,
the update is not performed until the commit
phase. Further, if replication is enabled, other nodes will not see the changes until the transaction has completed successfully.
Passivation. POJO Cache supports the same passivation provided by Core Cache. When a node mapped by POJO Cache has reached a configured threshold, it is evicted from memory and stored using a cache loader. When the node is accessed again, it will be retrieved from the cache loader and put into memory. The configuration parameters are the same as those of the Cache counterpart. To configure the passivation, you will need to configure both the eviction policy and cache loader.
Object cache by reachability, i.e., recursive object mapping
into the cache store. On attach, POJO Cache
will attach all referenced objects as well. This feature is explained in more detail later.
Natural Object Relationships. Java references are preserved as they were written. That is, a user does not need to declare any object relationship (e.g., one-to-one, or one-to-many) to use the cache.
Object Identity. Object identity is preserved. Not only can a cached object be compared
using equals()
, but the comparison operator, ==
, can be
used as well. For example, an object such as
Address
may be multiple referenced by two
Person
s (e.g., joe
and mary
).
The objects retrieved from joe.getAddress()
and mary.getAddress()
should be identicali, when when retrieved from a different node in the cluster then that which attached them.
Inheritance. POJO Cache preserves the inheritance hierarchy of any object in the cache.
For example, if a Student
class inherits from a
Person class, once a Student
object is mapped to POJO Cache (e.g., attach
call), the fields in the base class Person
are mapped as well.
Collections. Java Collection types (e.g. List, Set, and Map) are transparently mapped using Java proxies. Details are described later.
Annotation based. Starting from release 2.0, JDK 5 annotations are used to indicate that an object should be instrumented for use under POJO Cache (once attached).
Transparent. Once a POJO is attached to the cache, subsequent object model changes are transparently handled. No further API calls are required.
To use POJO Cache, you obtain the instance from the PojoCacheFactory by supplying a config file that is used by the delegating Cache implementation. Once the PojoCache instance is obtained, you can call the cache life cycle method to start the cache. Below is a code snippet that creates and starts the cache:
String configFile = "replSync-service.xml";
boolean toStart = false;
PojoCache pcache = PojoCacheFactory.createCache(configFiel, toStart);
pcache.start(); // if toStart above is true, it will starts the cache automatically.
pcache.attach(id, pojo);
// ...
pcache.stop(); // stop the cache. This will take PojoCache out of the clustering group, if any, e.g.
POJO Cache
is currently supported on JDK 5 (since release 2.0).
It requires the following libraries (in
addition to jboss-cache.jar and the required libraries for Core
Cache) to start up:
Library: