JBoss.org Community Documentation
This section provides a brief overview of the POJO Cache APIs. Please consult the javadoc for the full API.
PojoCacheFactory provides a couple of static methods to instantiate and obtain a PojoCache instance.
/**
* Create a PojoCache instance. Note that this will start the cache life cycle automatically.
* @param config A configuration string that represents the file name that is used to
* configure the underlying Cache instance.
* @return PojoCache
*/
public static PojoCache createInstance(String config);
/**
* Create a PojoCache instance.
* @param config A configuration string that represents the file name that is used to
* configure the underlying Cache instance.
* @param start If true, it will start the cache life cycle.
* @return PojoCache
*/
public static PojoCache createInstance(String config, boolean start);
/**
* Create a PojoCache instance.
* @param config A configuration object that is used to configure the underlying Cache instance.
* @param start If true, it will start the cache life cycle.
* @return PojoCache
*/
public static PojoCache createInstance(Configuration config, boolean start);
For example, to obtain a PojoCache instance and start the cache lifestyle automatically, we can do:
String configFile = "META-INF/replSync-service.xml";
PojoCache cache = PojoCacheFactory.createInstance(configFile);
PojoCache
is the main interface for POJO Cache operations. Since most of the
cache interaction is performed against the application domain
model, there are only a few methods on this interface.
/**
* Attach a POJO into PojoCache. It will also recursively put any sub-POJO into
* the cache system. A POJO can be the following and have the consequences when attached:
*
* It is PojoCacheable, that is, it has been annotated with
* {@see org.jboss.cache.aop.annotation.PojoCacheable} annotation (or via XML), and has
* been "instrumented" either compile- or load-time. The POJO will be mapped recursively to
* the system and fine-grained replication will be performed.
*
* It is Serializable. The POJO will still be stored in the cache system. However, it is
* treated as an "opaque" object per se. That is, the POJO will neither be intercepted
* (for fine-grained operation) or object relationship will be maintained.
*
* Neither of above. In this case, a user can specify whether it wants this POJO to be
* stored (e.g., replicated or persistent). If not, a PojoCacheException will be thrown.
*
* @param id An id String to identify the object in the cache. To promote concurrency, we
* recommend the use of hierarchical String separating by a designated separator. Default
* is "/" but it can be set differently via a System property, jbosscache.separator
* in the future release. E.g., "/ben", or "/student/joe", etc.
* @param pojo object to be inserted into the cache. If null, it will nullify the fqn node.
* @return Existing POJO or null if there is none.
* @throws PojoCacheException Throws if there is an error related to the cache operation.
*/
Object attach(String id, Object pojo) throws PojoCacheException;
As described in the above javadoc, this method "attaches" the
passed object to the cache at the specified location (
id
). The passed in object (
pojo
) must have been instrumented (using the
@Replicable
annotation) or implement the
Serializable
interface.
If the object is not instrumented, but serializable, POJO Cache will simply treat it as an opaque "primitive" type. That is, it will simply store it without mapping the object's fields into the cache. Replication is done on the object wide level and therefore it will not be fine-grained.
If the object has references to other objects, this call will
issue
attach()
calls recursively until the entire object graph is traversed. In
addition, object identity and object references are preserved.
So both circular and multiply referenced objects are mapped as
expected.
The return value after the call is the previous object under
id
, if any. As a result, a successful call i will replace that old
value with the new instance. Note that a user will only need to
issue this call once for each top-level object. Further calls
can be made directly on the graph, and they will be mapped as
expected.
/**
* Remove POJO object from the cache.
*
* @param id Is string that associates with this node.
* @return Original value object from this node.
* @throws PojoCacheException Throws if there is an error related to the cache operation.
*/
Object detach(String id) throws PojoCacheException;
This call will detach the POJO from the cache by removing the
contents under
id
and return the POJO instance stored there (null if it doesn't
exist). If successful, further operations against this object
will not affect the cache. Note this call will also remove
everything stored under
id
even if you have put other plain cache data there.
/**
* Retrieve POJO from the cache system. Return null if object does not exist in the cache.
* Note that this operation is fast if there is already a POJO instance attached to the cache.
*
* @param id that associates with this node.
* @return Current content value. Null if does not exist.
* @throws PojoCacheException Throws if there is an error related to the cache operation.
*/
Object find(String id) throws PojoCacheException;
This call will return the current object content located under
id
. This method call is useful when you don't have the exact POJO
reference. For example, when you fail over to the replicated
node, you want to get the object reference from the replicated
cache instance. In this case, PojoCache will create a new Java
object if it does not exist and then add the cache interceptor
such that every future access will be in sync with the
underlying cache store.
/**
* Query all managed POJO objects under the id recursively. Note that this will not return
* the sub-object POJOs, e.g., if Person has a sub-object of Address, it
* won't return Address pojo. Also note also that this operation is not thread-safe
* now. In addition, it assumes that once a POJO is found with a id, no more POJO is stored
* under the children of the id. That is, we don't mix the id with different POJOs.
*
* @param id The starting place to find all POJOs.
* @return Map of all POJOs found with (id, POJO) pair. Return size of 0, if not found.
* @throws PojoCacheException Throws if there is an error related to the cache operation.
*/
Map findAll(String id) throws PojoCacheException;
This call will return all the managed POJOs under cache with a
base Fqn name. It is recursive, meaning that it will traverse
all the sub-trees to find the POJOs under that base. For
example, if you specify the fqn to be root, e.g.,
"/"
, then it will return all the managed POJOs under the cache.
There are currently three annotations that can be used on attached
objects in POJO Cache:
@Replicable
,
@Transient
, and
@Serializable
. All of which affect how the annotated object is replicated.
The
@org.jboss.cache.annotation.Replicable
annotation is used to mark classes for instrumentation. Once
instrumented, individual field changes can be replicated
separately. See the instrumentation chapter for more information
on this process.
The following example will replicate changes to resource and name separately:
@Replicable
public class Gadget
{
private Resource resource;
private String name;
}
The @org.jboss.cache.annotation.Transient
annotation is used to
indicate that a field should not be replicable. This allows
non-transient fields to be included in normal Java serialization
output, but not when replicated by POJO Cache.
The following object will not replicate changes to resource.
@Replicable
public class Gadget
{
// resource won't be replicated
@Transient
private Resource resource;
}
The
@org.jboss.cache.annotation.Serializable
annotation indicates a field should be treated as a serialized
attribute. This, of course, requires that the type of the field
implement
Serializable
. If the marked field type has an @Replicable annotation, it
will be ignored.
@Replicable
public class Gadget
{
// resource won't be replicated
@Transient
private Resource resource;
// serialized even if SpecialAddress is @Replicable
@Serializable
private SpecialAddress specialAddress;
// other state variables
}