Clover coverage report -
Coverage timestamp: Thu Jul 5 2007 20:02:32 EDT
file stats: LOC: 178   Methods: 0
NCLOC: 23   Classes: 1
 
 Source file Conditionals Statements Methods TOTAL
PojoCache.java - - - -
coverage
 1    /*
 2    * JBoss, the OpenSource J2EE webOS
 3    *
 4    * Distributable under LGPL license.
 5    * See terms of license at gnu.org.
 6    */
 7    package org.jboss.cache.pojo;
 8   
 9    import java.util.Collection;
 10    import java.util.Map;
 11    import java.util.regex.Pattern;
 12   
 13    import org.jboss.cache.Cache;
 14    import org.jboss.cache.pojo.notification.annotation.PojoCacheListener;
 15   
 16    /**
 17    * <p>Main PojoCache APIs. PojoCache is an in-memory, transactional, fine-grained, and
 18    * object-oriented POJO (plain old Java object) distributed cache system. It
 19    * differs from the traditional generic distributed cache library by operating on the
 20    * POJO level directly without requiring that object to be serializable. It can preserve
 21    * object graph relationship during replication or persistency. It also track the
 22    * replication via fine-grained maner, i.e., only modified fields are replicated.</p>
 23    *
 24    * @author Ben Wang
 25    * @since 2.0
 26    */
 27    public interface PojoCache
 28    {
 29    /**
 30    * <p>Attach a POJO into PojoCache. It will also recursively put any
 31    * sub-POJO into the cache system. A POJO can be the following and have the
 32    * consqeuences when attached:</p> <p/> <li>it is Replicable, that is, it
 33    * has been annotated with {@link @org.jboss.cache.pojo.annotation.Replicable} annotation (or via XML),
 34    * and has
 35    * been "instrumented" either compile- or load-time. The POJO will be mapped
 36    * recursively to the system and fine-grained replication will be
 37    * performed.</li> <li>It is Serializable. The POJO will still be stored in
 38    * the cache system. However, it is treated as an "opaque" object per se.
 39    * That is, the POJO will neither be intercepted
 40    * (for fine-grained operation) or object relantionship will be
 41    * maintained.</li>
 42    * <li>Neither of above. In this case, a user can specify whether it wants
 43    * this POJO to be stored (e.g., replicated or persistent). If not, a
 44    * PojoCacheException will be thrown.</li>
 45    *
 46    * @param id An id String to identify the object in the cache. To promote
 47    * concurrency, we recommend the use of hierarchical String separating by a
 48    * designated separator. Default is "/" but it can be set differently via a
 49    * System property, jbosscache.separator in the future release. E.g., "ben",
 50    * or "student/joe", etc.
 51    * @param pojo object to be inerted into the cache. If null, it will nullify
 52    * the fqn node.
 53    * @return Existing POJO or null if there is none.
 54    * @throws PojoCacheException Throws if there is an error related to the cache operation.
 55    */
 56    Object attach(String id, Object pojo) throws PojoCacheException;
 57   
 58    /**
 59    * Remove POJO object from the cache.
 60    *
 61    * @param id Is string that associates with this node.
 62    * @return Original value object from this node.
 63    * @throws PojoCacheException Throws if there is an error related to the cache operation.
 64    */
 65    Object detach(String id) throws PojoCacheException;
 66   
 67    /**
 68    * Return the POJO id that is associated with PojoCache. Note that if a POJO has not yet
 69    * attached to the cache system, it will simply return null.
 70    *
 71    * @param pojo The POJO that is attached to PojoCache.
 72    * @return String ID. Null if not existed.
 73    */
 74    String getPojoID(Object pojo);
 75   
 76    /**
 77    * Retrieve POJO from the cache system. Return null if object does not exist in the cache.
 78    * Note that this operation is fast if there is already a POJO instance attached to the cache.
 79    *
 80    * @param id that associates with this node.
 81    * @return Current content value. Null if does not exist.
 82    * @throws PojoCacheException Throws if there is an error related to the cache operation.
 83    */
 84    Object find(String id) throws PojoCacheException;
 85   
 86    /**
 87    * Query all managed POJO objects under the id recursively. Note that this will not return
 88    * the sub-object POJOs, e.g., if <em>Person</em> has a sub-object of <em>Address</em>, it
 89    * won't return <em>Address</em> pojo. Also note also that this operation is not thread-safe
 90    * now. In addition, it assumes that once a POJO is found with a id, no more POJO is stored
 91    * under the children of the id. That is, we don't mix the id with different POJOs.
 92    *
 93    * @param id The starting place to find all POJOs.
 94    * @return Map of all POJOs found with (id, POJO) pair. Return size of 0, if not found.
 95    * @throws PojoCacheException Throws if there is an error related to the cache operation.
 96    */
 97    Map findAll(String id) throws PojoCacheException;
 98   
 99    /**
 100    * Lifecycle method to start PojoCache.
 101    *
 102    * @throws PojoCacheException
 103    */
 104    void create() throws PojoCacheException;
 105   
 106    /**
 107    * Lifecycle method to start PojoCache.
 108    *
 109    * @throws PojoCacheException
 110    */
 111    void start() throws PojoCacheException;
 112   
 113    /**
 114    * Lifecycle method to stop PojoCache. Note that PojoCache can be stopped and started
 115    * repeatedly.
 116    *
 117    * @throws PojoCacheException
 118    */
 119    void stop() throws PojoCacheException;
 120   
 121    /**
 122    * Lifecycle method to destroy PojoCache.
 123    *
 124    * @throws PojoCacheException
 125    */
 126    void destroy() throws PojoCacheException;
 127   
 128    /**
 129    * <p>
 130    * Add a PojoCache listener. A given listener instance can only be added once.
 131    * To have a duplicate listener simply create a new instance.
 132    *
 133    * <p>
 134    * The listener must be annotated with the {@link PojoCacheListener} annotation, and
 135    * all callback methods need to be annotated with the respective event annotations.
 136    * Otherwise, an exception will be thrown.
 137    *
 138    * @param listener the listener instance to register
 139    * @throws IllegalArgumentException if listener does not conform to annotation requirements
 140    * @see PojoCacheListener for examples
 141    */
 142    void addListener(Object listener);
 143   
 144    /**
 145    * <p>
 146    * Add a PojoCache listener that will only monitor a specific ID(FQN) pattern.
 147    * A given listener instance can only be added once, whether or not there is
 148    * a pattern. To have a duplicate listener simply create a new instance.
 149    *
 150    * <p>
 151    * The listener must be annotated with the {@link PojoCacheListener} annotation, and
 152    * all callback methods need to be annotated with the respective event annotations.
 153    * Otherwise, an exception will be thrown.
 154    *
 155    * @param listener the listener instance to register
 156    * @param pattern the ID pattern for notifications of interest
 157    * @throws IllegalArgumentException if listener does not conform to annotation requirements
 158    * @see PojoCacheListener for examples
 159    */
 160    void addListener(Object listener, Pattern pattern);
 161   
 162    /**
 163    * Retrieve a read-only list of listeners.
 164    */
 165    Collection<Object> getListeners();
 166   
 167    /**
 168    * Remove the specific listener.
 169    *
 170    * @param listener the listener to remove
 171    */
 172    void removeListener(Object listener);
 173   
 174    /**
 175    * Obtain the underlying generic cache system. Use this for non-POJO cache operation, e.g.
 176    */
 177    Cache<Object, Object> getCache();
 178    }