PojoCache 2.0 Interface
ben.wang Jun 16, 2006 1:54 AMNow that the underlying Cache API has stablized, I am also publishing the PojoCache 2.0 APIs. The main changes are:
1. API name changes like putObject to attach and removeObject to detach.
2. Decouple from underlying plain cache implementation. That is the new PojoCache implementation will implment both PojoCache and Cache interfaces. But there is no direct coupling of PojoCache API to Cache one, e.g., Fqn of the tree structure. For the key to identify the POJO in the cache system, I am using a String id now.
/* * JBoss, the OpenSource J2EE webOS * * Distributable under LGPL license. * See terms of license at gnu.org. */ package org.jboss.cache.pojo; import java.util.Map; /** * <p>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.</p> * * @author Ben Wang * @since 2.0 */ public interface PojoCache { /** * <p>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:</p> * * <li>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.</li> * <li>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.</li> * <li>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. For conveient, the id can * be hierarchical separating by "/" separation, for example. * @param pojo object to be inerted into the cache. If null, it will nullify the fqn node. * @return Existing POJO or null if there is not. * @throws PojoCacheException Throws if there is an error related to the cache operation, e.g., * {@link org.jboss.cache.lock.TimeoutException}. */ Object attach(String id, Object pojo) throws PojoCacheException; /** * 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, e.g., * {@see org.jboss.cache.lock.TimeoutException}. */ Object detach(String id) throws PojoCacheException; /** * Remove POJO object from the cache. * * @param pojo The managed POJO. * @return Original value object from this node. * @throws PojoCacheException Throws if there is an error related to the cache operation, e.g., * {@see org.jboss.cache.lock.TimeoutException}. */ Object detach(Object pojo) throws PojoCacheException; /** * Retrieve pojo from the cache. Return null if object does not exist in the cache. * Note that this operation is fast if there is already an 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, e.g., * {@see org.jboss.cache.lock.TimeoutException}. */ Object find(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 fqn, no more pojo is stored under the children * of the fqn. That is, we don't mixed the fqn with different pojos. * * @param id The starting place to find all pojos. * @return Map of all pojos found with (fqn, pojo) pair. Return size of 0, if not found. * @throws PojoCacheException Throws if there is an error related to the cache operation, e.g., * {@see org.jboss.cache.lock.TimeoutException}. */ Map findAll(String id) throws PojoCacheException; }