Clover coverage report -
Coverage timestamp: Thu Jul 5 2007 20:02:32 EDT
file stats: LOC: 370   Methods: 0
NCLOC: 39   Classes: 1
 
 Source file Conditionals Statements Methods TOTAL
Cache.java - - - -
coverage
 1    /*
 2    * JBoss, Home of Professional Open Source
 3    *
 4    * Distributable under LGPL license.
 5    * See terms of license at gnu.org.
 6    */
 7    package org.jboss.cache;
 8   
 9    import net.jcip.annotations.ThreadSafe;
 10    import org.jboss.cache.config.Configuration;
 11    import org.jgroups.Address;
 12   
 13    import java.util.List;
 14    import java.util.Map;
 15    import java.util.Set;
 16   
 17    /**
 18    * Interface for a Cache where data mappings are grouped and stored in a tree data
 19    * structure consisting of {@link Node}s.
 20    * <p/>
 21    * This is the central construct and basic client API of JBoss Cache and is used for
 22    * cache-wide operations.
 23    * <p/>
 24    * The cache is constructed using a {@link CacheFactory} and is started
 25    * using {@link #start}, if not already started by the CacheFactory.
 26    * <p/>
 27    * Once constructed, the Cache interface can be used to create or access {@link Node}s, which contain data. Once references
 28    * to {@link Node}s are obtained, data can be stored in them,
 29    * <p/>
 30    * As a convenience (and mainly to provide a familiar API to the older JBoss Cache 1.x.x releases) methods are provided that
 31    * operate directly on nodes.
 32    * <ul>
 33    * <li>{@link #put(Fqn,Object,Object)} </li>
 34    * <li>{@link #put(Fqn,java.util.Map)} </li>
 35    * <li>{@link #get(Fqn,Object)} </li>
 36    * <li>{@link #remove(Fqn,Object)} </li>
 37    * <li>{@link #removeNode(Fqn)} </li>
 38    * </ul>
 39    * <p/>
 40    * A simple example of usage:
 41    * <pre>
 42    * // creates with default settings and starts the cache
 43    * Cache cache = DefaultCacheFactory.getInstance().createCache();
 44    * Fqn personRecords = Fqn.fromString("/org/mycompany/personRecords");
 45    * <p/>
 46    * Node rootNode = cache.getRoot();
 47    * Node personRecordsNode = rootNode.addChild(personRecords);
 48    * <p/>
 49    * // now add some person records.
 50    * Fqn peterGriffin = Fqn.fromString("/peterGriffin");
 51    * Fqn stewieGriffin = Fqn.fromString("/stewieGriffin");
 52    * <p/>
 53    * // the addChild() API uses relative Fqns
 54    * Node peter = personRecordsNode.addChild(peterGriffin);
 55    * Node stewie = personRecordsNode.addChild(stewieGriffin);
 56    * <p/>
 57    * peter.put("name", "Peter Griffin");
 58    * peter.put("ageGroup", "MidLifeCrisis");
 59    * peter.put("homicidal", Boolean.FALSE);
 60    * <p/>
 61    * stewie.put("name", "Stewie Griffin");
 62    * stewie.put("ageGroup", "Infant");
 63    * stewie.put("homicidal", Boolean.TRUE);
 64    * <p/>
 65    * peter.getFqn().toString(); // will print out /org/mycompany/personRecords/peterGriffin
 66    * stewie.getFqn().toString(); // will print out /org/mycompany/personRecords/stewieGriffin
 67    * <p/>
 68    * peter.getFqn().getParent().equals(stewie.getFqn().getParent()); // will return true
 69    * <p/>
 70    * </pre>
 71    * <p/>
 72    * For more information, please read the JBoss Cache user guide and tutorial, available on <a href="http://labs.jboss.com/portal/jbosscache/docs/index.html" target="_BLANK">the JBoss Cache documentation site</a>,
 73    * and look through the examples <a href="http://labs.jboss.com/portal/jbosscache/download/index.html" target="_BLANK">shipped with the JBoss Cache distribution</a>.
 74    *
 75    * @author <a href="mailto:manik@jboss.org">Manik Surtani (manik@jboss.org)</a>
 76    * @see Node
 77    * @see CacheFactory
 78    * @since 2.0.0
 79    */
 80    @ThreadSafe
 81    public interface Cache<K, V>
 82    {
 83    /**
 84    * Retrieves the configuration of this cache.
 85    *
 86    * @return the configuration.
 87    */
 88    Configuration getConfiguration();
 89   
 90    /**
 91    * Returns the root node of this cache.
 92    *
 93    * @return the root node
 94    */
 95    Node<K, V> getRoot();
 96   
 97    /**
 98    * Adds a {@link CacheListener} to the entire cache. The object passed in needs to be properly annotated with the
 99    * {@link @org.jboss.cache.notifications.annotation.CacheListener} annotation otherwise an {@link org.jboss.cache.notifications.IncorrectCacheListenerException} will be thrown.
 100    *
 101    * @param listener listener to add
 102    */
 103    void addCacheListener(Object listener);
 104   
 105    /**
 106    * Adds a {@link CacheListener} to a given region. The object passed in needs to be properly annotated with the
 107    * {@link @org.jboss.cache.notifications.annotation.CacheListener} annotation otherwise an {@link org.jboss.cache.notifications.IncorrectCacheListenerException} will be thrown.
 108    *
 109    * @param region region to add listener to
 110    * @param listener listener to add
 111    */
 112    void addCacheListener(Fqn<?> region, Object listener);
 113   
 114    /**
 115    * Removes a {@link CacheListener} from the cache. The object passed in needs to be properly annotated with the
 116    * {@link @org.jboss.cache.notifications.annotation.CacheListener} annotation otherwise an {@link org.jboss.cache.notifications.IncorrectCacheListenerException} will be thrown.
 117    *
 118    * @param listener listener to remove
 119    */
 120    void removeCacheListener(Object listener);
 121   
 122    /**
 123    * Removes a {@link CacheListener} from a given region. The object passed in needs to be properly annotated with the
 124    * {@link @org.jboss.cache.notifications.annotation.CacheListener} annotation otherwise an {@link org.jboss.cache.notifications.IncorrectCacheListenerException} will be thrown.
 125    *
 126    * @param region region from which to remove listener
 127    * @param listener listener to remove
 128    */
 129    void removeCacheListener(Fqn<?> region, Object listener);
 130   
 131    /**
 132    * Retrieves an immutable {@link List} of objects annotated as {@link org.jboss.cache.notifications.annotation.CacheListener}s attached to the cache.
 133    *
 134    * @return an immutable {@link List} of objects annotated as {@link org.jboss.cache.notifications.annotation.CacheListener}s attached to the cache.
 135    */
 136    Set<Object> getCacheListeners();
 137   
 138    /**
 139    * Retrieves an immutable {@link List} of objects annotated as {@link org.jboss.cache.notifications.annotation.CacheListener}s attached to a specific region.
 140    *
 141    * @return an immutable {@link List} of objects annotated as {@link org.jboss.cache.notifications.annotation.CacheListener}s attached to a specific region.
 142    */
 143    Set<Object> getCacheListeners(Fqn<?> region);
 144   
 145    /**
 146    * Associates the specified value with the specified key for a {@link Node} in this cache.
 147    * If the {@link Node} previously contained a mapping for this key, the old value is replaced by the specified value.
 148    *
 149    * @param fqn <b><i>absolute</i></b> {@link Fqn} to the {@link Node} to be accessed.
 150    * @param key key with which the specified value is to be associated.
 151    * @param value value to be associated with the specified key.
 152    * @return previous value associated with specified key, or <code>null</code> if there was no mapping for key.
 153    * A <code>null</code> return can also indicate that the Node previously associated <code>null</code> with the specified key, if the implementation supports null values.
 154    */
 155    V put(Fqn<?> fqn, K key, V value);
 156   
 157    /**
 158    * Under special operating behavior, associates the value with the specified key for a node identified by the Fqn passed in.
 159    * <ul>
 160    * <li> Only goes through if the node specified does not exist; no-op otherwise.</i>
 161    * <li> Force asynchronous mode for replication or invalidation to prevent any blocking.</li>
 162    * <li> 0ms lock timeout to prevent any blocking here either. If the lock is not acquired, this method is a no-op, and swallows the timeout exception.</li>
 163    * <li> Ongoing transactions are suspended before this call, so failures here will not affect any ongoing transactions.</li>
 164    * <li> Errors and exceptions are 'silent' - logged at a much lower level than normal, and this method does not throw exceptions</li>
 165    * </ul>
 166    * This method is for caching data that has an external representation in storage, where, concurrent modification and
 167    * transactions are not a consideration, and failure to put the data in the cache should be treated as a 'suboptimal outcome'
 168    * rather than a 'failing outcome'.
 169    * <p/>
 170    * An example of when this method is useful is when data is read from, for example, a legacy datastore, and is cached before
 171    * returning the data to the caller. Subsequent calls would prefer to get the data from the cache and if the data doesn't exist
 172    * in the cache, fetch again from the legacy datastore.
 173    * <p/>
 174    * See <a href="http://jira.jboss.com/jira/browse/JBCACHE-848">JBCACHE-848</a> for details around this feature.
 175    * <p/>
 176    *
 177    * @param fqn <b><i>absolute</i></b> {@link Fqn} to the {@link Node} to be accessed.
 178    * @param key key with which the specified value is to be associated.
 179    * @param value value to be associated with the specified key.
 180    */
 181    void putForExternalRead(Fqn<?> fqn, K key, V value);
 182   
 183    /**
 184    * Copies all of the mappings from the specified map to a {@link Node}.
 185    *
 186    * @param fqn <b><i>absolute</i></b> {@link Fqn} to the {@link Node} to copy the data to
 187    * @param data mappings to copy
 188    */
 189    void put(Fqn<?> fqn, Map<K, V> data);
 190   
 191    /**
 192    * Removes the mapping for this key from a Node.
 193    * Returns the value to which the Node previously associated the key, or
 194    * <code>null</code> if the Node contained no mapping for this key.
 195    *
 196    * @param fqn <b><i>absolute</i></b> {@link Fqn} to the {@link Node} to be accessed.
 197    * @param key key whose mapping is to be removed from the Node
 198    * @return previous value associated with specified Node's key
 199    */
 200    V remove(Fqn<?> fqn, K key);
 201   
 202    /**
 203    * Removes a {@link Node} indicated by absolute {@link Fqn}.
 204    *
 205    * @param fqn {@link Node} to remove
 206    * @return true if the node was removed, false if the node was not found
 207    */
 208    boolean removeNode(Fqn<?> fqn);
 209   
 210    /**
 211    * Convenience method that allows for direct access to the data in a {@link Node}.
 212    *
 213    * @param fqn <b><i>absolute</i></b> {@link Fqn} to the {@link Node} to be accessed.
 214    * @param key key under which value is to be retrieved.
 215    * @return returns data held under specified key in {@link Node} denoted by specified Fqn.
 216    */
 217    V get(Fqn<?> fqn, K key);
 218   
 219    /**
 220    * Eviction call that evicts the specified {@link Node} from memory.
 221    *
 222    * @param fqn <b><i>absolute</i></b> {@link Fqn} to the {@link Node} to be evicted.
 223    * @param recursive evicts children as well
 224    */
 225    void evict(Fqn<?> fqn, boolean recursive);
 226   
 227    /**
 228    * Retrieves a {@link Region} for a given {@link Fqn}. If the region does not exist,
 229    * and <li>createIfAbsent</li> is true, then one is created.
 230    * <p/>
 231    * If not, parent Fqns will be consulted in turn for registered regions, gradually working up to
 232    * Fqn.ROOT. If no regions are defined in any of the parents either, a null is returned.
 233    *
 234    * @param fqn Fqn that is contained in a region.
 235    * @param createIfAbsent If true, will create a new associated region if not found.
 236    * @return a MarshRegion. Null if none is found.
 237    * @throws UnsupportedOperationException if the region cannot be defined.
 238    * @see Region
 239    */
 240    Region getRegion(Fqn<?> fqn, boolean createIfAbsent);
 241   
 242    /**
 243    * Removes a region denoted by the Fqn passed in.
 244    *
 245    * @param fqn of the region to remove
 246    * @return true if a region did exist and was removed; false otherwise.
 247    */
 248    boolean removeRegion(Fqn<?> fqn);
 249   
 250    /**
 251    * Lifecycle method that initializes configuration state, the root node, etc.
 252    *
 253    * @throws CacheException if there are creation problems
 254    */
 255    void create() throws CacheException;
 256   
 257    /**
 258    * Lifecycle method that starts the cache loader,
 259    * starts cache replication, starts the region manager, etc.
 260    *
 261    * @throws CacheException if there are startup problems
 262    */
 263    void start() throws CacheException;
 264   
 265    /**
 266    * Lifecycle method that stops the cache, including replication,
 267    * clustering, cache loading, notifications, etc.
 268    */
 269    void stop();
 270   
 271    /**
 272    * Lifecycle method that clears state.
 273    * Cache can then be restarted using {@link #start}.
 274    */
 275    void destroy();
 276   
 277    /**
 278    * Gets where the cache currently is its lifecycle transitions.
 279    *
 280    * @return the CacheStatus. Will not return <code>null</code>.
 281    */
 282    CacheStatus getCacheStatus();
 283   
 284    /**
 285    * @return the current invocation context for the current invocation and cache instance.
 286    * @see org.jboss.cache.InvocationContext
 287    */
 288    InvocationContext getInvocationContext();
 289   
 290    /**
 291    * Sets the passed in {@link org.jboss.cache.InvocationContext} as current.
 292    *
 293    * @param ctx invocation context to use
 294    */
 295    void setInvocationContext(InvocationContext ctx);
 296   
 297    /**
 298    * Returns the local address of this cache in a cluster, or <code>null</code>
 299    * if running in local mode.
 300    *
 301    * @return the local address of this cache in a cluster, or <code>null</code>
 302    * if running in local mode.
 303    */
 304    Address getLocalAddress();
 305   
 306    /**
 307    * Returns a list of members in the cluster, or <code>null</code>
 308    * if running in local mode.
 309    *
 310    * @return a {@link List} of members in the cluster, or <code>null</code>
 311    * if running in local mode.
 312    */
 313    List<Address> getMembers();
 314   
 315    /**
 316    * Moves a part of the cache to a different subtree.
 317    * <p/>
 318    * E.g.:
 319    * <p/>
 320    * assume a cache structure such as:
 321    * <p/>
 322    * <pre>
 323    * /a/b/c
 324    * /a/b/d
 325    * /a/b/e
 326    * <p/>
 327    * <p/>
 328    * Fqn f1 = Fqn.fromString("/a/b/c");
 329    * Fqn f2 = Fqn.fromString("/a/b/d");
 330    * <p/>
 331    * cache.move(f1, f2);
 332    * </pre>
 333    * <p/>
 334    * Will result in:
 335    * <pre>
 336    * <p/>
 337    * /a/b/d/c
 338    * /a/b/e
 339    * <p/>
 340    * </pre>
 341    * <p/>
 342    * and now
 343    * <p/>
 344    * <pre>
 345    * Fqn f3 = Fqn.fromString("/a/b/e");
 346    * Fqn f4 = Fqn.fromString("/a");
 347    * cache.move(f3, f4);
 348    * </pre>
 349    * <p/>
 350    * will result in:
 351    * <pre>
 352    * /a/b/d/c
 353    * /a/e
 354    * </pre>
 355    * No-op if the node to be moved is the root node.
 356    *
 357    * @param nodeToMove the Fqn of the node to move.
 358    * @param newParent new location under which to attach the node being moved.
 359    * @throws NodeNotExistsException may throw one of these if the target node does not exist or if a different thread has moved this node elsewhere already.
 360    */
 361    void move(Fqn<?> nodeToMove, Fqn<?> newParent) throws NodeNotExistsException;
 362   
 363    /**
 364    * Returns the version of the cache as a string.
 365    *
 366    * @return the version string of the cache.
 367    * @see Version#printVersion
 368    */
 369    String getVersion();
 370    }