org.jboss.cache.pojo
Interface PojoCache

All Known Subinterfaces:

PojoCacheMBean

All Known Implementing Classes:

PojoCacheImpl

public interface PojoCache

Main PojoCache APIs. PojoCache is an in-memory, transactional, fine-grained, and object-oriented POJO (plain old Java object) distributed cache system. It differs from the traditional generic distributed cache library by operating on the POJO level directly without requiring that object to be serializable. It can preserve object graph relationship during replication or persistency. It also track the replication via fine-grained maner, i.e., only modified fields are replicated.

Since:

2.0

Author:

Ben Wang

Method Summary

void	addListener(java.lang.Object listener) Add a PojoCache listener.
void	addListener(java.lang.Object listener, java.util.regex.Pattern pattern) Add a PojoCache listener that will only monitor a specific ID(FQN) pattern.
java.lang.Object	attach(java.lang.String id, java.lang.Object pojo) Attach a POJO into PojoCache.
void	create() Lifecycle method to start PojoCache.
void	destroy() Lifecycle method to destroy PojoCache.
java.lang.Object	detach(java.lang.String id) Remove POJO object from the cache.
java.lang.Object	find(java.lang.String id) Retrieve POJO from the cache system.
java.util.Map	findAll(java.lang.String id) Query all managed POJO objects under the id recursively.
Cache<java.lang.Object,java.lang.Object>	getCache() Obtain the underlying generic cache system.
java.util.Collection<java.lang.Object>	getListeners() Retrieve a read-only list of listeners.
java.lang.String	getPojoID(java.lang.Object pojo) Return the POJO id that is associated with PojoCache.
void	removeListener(java.lang.Object listener) Remove the specific listener.
void	start() Lifecycle method to start PojoCache.
void	stop() Lifecycle method to stop PojoCache.

Method Detail

attach

java.lang.Object attach(java.lang.String id,
                        java.lang.Object pojo)
                        throws PojoCacheException

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 consqeuences when attached:

it is Replicable, that is, it has been annotated with @org.jboss.cache.pojo.annotation.Replicable 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 relantionship 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.

Parameters:

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.

pojo - object to be inerted into the cache. If null, it will nullify the fqn node.

Returns:

Existing POJO or null if there is none.

Throws:

PojoCacheException - Throws if there is an error related to the cache operation.

detach

java.lang.Object detach(java.lang.String id)
                        throws PojoCacheException

Remove POJO object from the cache.

Parameters:

id - Is string that associates with this node.

Returns:

Original value object from this node.

Throws:

PojoCacheException - Throws if there is an error related to the cache operation.

getPojoID

java.lang.String getPojoID(java.lang.Object pojo)

Return the POJO id that is associated with PojoCache. Note that if a POJO has not yet attached to the cache system, it will simply return null.

Parameters:

pojo - The POJO that is attached to PojoCache.

Returns:

String ID. Null if not existed.

find

java.lang.Object find(java.lang.String id)
                      throws PojoCacheException

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.

Parameters:

id - that associates with this node.

Returns:

Current content value. Null if does not exist.

Throws:

PojoCacheException - Throws if there is an error related to the cache operation.

findAll

java.util.Map findAll(java.lang.String id)
                      throws PojoCacheException

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.

Parameters:

id - The starting place to find all POJOs.

Returns:

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.

create

void create()
            throws PojoCacheException

Lifecycle method to start PojoCache.

Throws:

PojoCacheException

start

void start()
           throws PojoCacheException

Lifecycle method to start PojoCache.

Throws:

PojoCacheException

stop

void stop()
          throws PojoCacheException

Lifecycle method to stop PojoCache. Note that PojoCache can be stopped and started repeatedly.

Throws:

PojoCacheException

destroy

void destroy()
             throws PojoCacheException

Lifecycle method to destroy PojoCache.

Throws:

PojoCacheException

addListener

void addListener(java.lang.Object listener)

Add a PojoCache listener. A given listener instance can only be added once. To have a duplicate listener simply create a new instance.

The listener must be annotated with the PojoCacheListener annotation, and all callback methods need to be annotated with the respective event annotations. Otherwise, an exception will be thrown.

Parameters:

listener - the listener instance to register

Throws:

java.lang.IllegalArgumentException - if listener does not conform to annotation requirements

See Also:

for examples

addListener

void addListener(java.lang.Object listener,
                 java.util.regex.Pattern pattern)

Add a PojoCache listener that will only monitor a specific ID(FQN) pattern. A given listener instance can only be added once, whether or not there is a pattern. To have a duplicate listener simply create a new instance.

The listener must be annotated with the PojoCacheListener annotation, and all callback methods need to be annotated with the respective event annotations. Otherwise, an exception will be thrown.

Parameters:

listener - the listener instance to register

pattern - the ID pattern for notifications of interest

Throws:

java.lang.IllegalArgumentException - if listener does not conform to annotation requirements

See Also:

for examples

getListeners

java.util.Collection<java.lang.Object> getListeners()

Retrieve a read-only list of listeners.

removeListener

void removeListener(java.lang.Object listener)

Remove the specific listener.

Parameters:

listener - the listener to remove

getCache

Cache<java.lang.Object,java.lang.Object> getCache()

Obtain the underlying generic cache system. Use this for non-POJO cache operation, e.g.