Clover coverage report -
Coverage timestamp: Thu Jul 5 2007 20:02:32 EDT
file stats: LOC: 349   Methods: 0
NCLOC: 40   Classes: 1
 
 Source file Conditionals Statements Methods TOTAL
CacheLoader.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.loader;
 8   
 9    import net.jcip.annotations.ThreadSafe;
 10    import org.jboss.cache.CacheSPI;
 11    import org.jboss.cache.Fqn;
 12    import org.jboss.cache.Modification;
 13    import org.jboss.cache.RegionManager;
 14    import org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig;
 15   
 16    import java.io.ObjectInputStream;
 17    import java.io.ObjectOutputStream;
 18    import java.util.List;
 19    import java.util.Map;
 20    import java.util.Set;
 21   
 22    /**
 23    * A {@link org.jboss.cache.loader.CacheLoader} implementation persists and load keys to and from
 24    * secondary storage, such as a database or filesystem. Typically,
 25    * implementations store a series of keys and values (an entire {@link Map})
 26    * under a single {@link Fqn}. Loading and saving properties of an entire
 27    * {@link Map} should be atomic.
 28    * <p/>
 29    * Lifecycle: First an instance of the loader is created, then the
 30    * configuration ({@link #setConfig(org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig)}) and cache ({@link
 31    * #setCache(CacheSPI)}) are set. After this, {@link #create()} is called.
 32    * Then {@link #start()} is called. When re-deployed, {@link #stop()} will be
 33    * called, followed by another {@link #start()}. Finally, when shut down,
 34    * {@link #destroy()} is called, after which the loader is unusable.
 35    * <p/>
 36    * An {@link org.jboss.cache.loader.AbstractCacheLoader} is provided as a convenient starting place
 37    * when implementing your own {@link org.jboss.cache.loader.CacheLoader}.
 38    * <p/>
 39    * It is important to note that all implementations are thread safe, as concurrent reads and writes, potentially even to
 40    * the same {@link Fqn}, are possible.
 41    * <p/>
 42    *
 43    * @author <a href="mailto:manik@jboss.org">Manik Surtani (manik@jboss.org)</a>
 44    * @see CacheSPI
 45    * @see org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig
 46    * @see org.jboss.cache.loader.AbstractCacheLoader
 47    * @since 2.0.0
 48    */
 49    @ThreadSafe
 50    public interface CacheLoader
 51    {
 52    /**
 53    * Sets the configuration. This is called before {@link #create()} and {@link #start()}.
 54    *
 55    * @param config May be an instance of the {@link org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig} base
 56    * class, in which case the cache loader should use the
 57    * {@link org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig#getProperties()}
 58    * method to find configuration information. Alternatively,
 59    * may be a type-specific subclass of {@link org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig},
 60    * if there is one.
 61    */
 62    void setConfig(IndividualCacheLoaderConfig config);
 63   
 64    /**
 65    * Gets the configuration.
 66    *
 67    * @return the configuration, represented by a {@link org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig} object.
 68    */
 69    IndividualCacheLoaderConfig getConfig();
 70   
 71    /**
 72    * Sets the {@link CacheSPI} that is maintaining this CacheLoader.
 73    * This method allows this CacheLoader to set a reference to the {@link CacheSPI}.
 74    * This method is called be called after the CacheLoader instance has been constructed.
 75    *
 76    * @param c The cache on which this loader works
 77    */
 78    void setCache(CacheSPI c);
 79   
 80   
 81    /**
 82    * Returns a set of children node names.
 83    * All names are <em>relative</em> to this parent {@link Fqn}.
 84    * Returns null if the named node is not found or there are no children.
 85    * The returned set must not be modifiable. Implementors can use
 86    * {@link java.util.Collections#unmodifiableSet(java.util.Set)} to make the set unmodifiable.
 87    * <p/>
 88    * Implementors may impose restrictions on the contents of an Fqn (such as Strings-only) and as such, indirectly
 89    * impose the same restriction on the contents of a Set returned by getChildrenNames().
 90    * <p/>
 91    *
 92    * @param fqn The {@link Fqn} of the parent
 93    * @return Set a set of children. Returns null if no children nodes are
 94    * present, or the parent is not present
 95    */
 96    Set<?> getChildrenNames(Fqn fqn) throws Exception;
 97   
 98    /**
 99    * Returns all keys and values from the persistent store, given a {@link org.jboss.cache.Fqn}
 100    *
 101    * @param name the {@link Fqn} to search for.
 102    * @return Map<Object,Object> keys and values for the given node. Returns
 103    * null if the node is not found. If the node is found but has no
 104    * attributes, this method returns an empty Map.
 105    */
 106    Map<Object, Object> get(Fqn name) throws Exception;
 107   
 108   
 109    /**
 110    * Returns true if the CacheLoader has a node with a {@link Fqn}.
 111    *
 112    * @return true if node exists, false otherwise
 113    */
 114    boolean exists(Fqn name) throws Exception;
 115   
 116   
 117    /**
 118    * Puts a key and value into the attribute map of a given node. If the
 119    * node does not exist, all parent nodes from the root down are created
 120    * automatically. Returns the old value.
 121    */
 122    Object put(Fqn name, Object key, Object value) throws Exception;
 123   
 124    /**
 125    * Puts all entries of the map into the existing map of the given node,
 126    * overwriting existing keys, but not clearing the existing map before
 127    * insertion.
 128    * This is the same behavior as {@link Map#putAll}.
 129    * If the node does not exist, all parent nodes from the root down are created automatically
 130    *
 131    * @param name The fully qualified name of the node
 132    * @param attributes A Map of attributes. Can be null
 133    */
 134    void put(Fqn name, Map<Object, Object> attributes) throws Exception;
 135   
 136    /**
 137    * Applies all modifications to the backend store.
 138    * Changes may be applied in a single operation.
 139    *
 140    * @param modifications A List<Modification> of modifications
 141    */
 142    void put(List<Modification> modifications) throws Exception;
 143   
 144    /**
 145    * Removes the given key and value from the attributes of the given node.
 146    * Does nothing if the node doesn't exist
 147    * Returns the removed value.
 148    */
 149    Object remove(Fqn fqn, Object key) throws Exception;
 150   
 151    /**
 152    * Removes the given node and all its subnodes, does nothing if the node does not exist.
 153    *
 154    * @param fqn the {@link Fqn} of the node
 155    */
 156    void remove(Fqn fqn) throws Exception;
 157   
 158   
 159    /**
 160    * Removes all attributes from a given node, but doesn't delete the node
 161    * itself or any subnodes.
 162    *
 163    * @param fqn the {@link Fqn} of the node
 164    */
 165    void removeData(Fqn fqn) throws Exception;
 166   
 167   
 168    /**
 169    * Prepares a list of modifications. For example, for a DB-based CacheLoader:
 170    * <ol>
 171    * <li>Create a local (JDBC) transaction
 172    * <li>Associate the local transaction with <code>tx</code> (tx is the key)
 173    * <li>Execute the corresponding SQL statements against the DB (statements derived from modifications)
 174    * </ol>
 175    * For non-transactional CacheLoader (e.g. file-based), the implementation could attempt to implement it's own transactional
 176    * logic, attempting to write data to a temp location (or memory) and writing it to the proper location upon commit.
 177    *
 178    * @param tx The transaction, indended to be used by implementations as an identifier of the transaction (and not necessarily a JTA {@link javax.transaction.Transaction} object)
 179    * @param modifications A {@link List} containing {@link org.jboss.cache.Modification}s, for the given transaction
 180    * @param one_phase Persist immediately and (for example) commit the local JDBC transaction as well. When true,
 181    * we won't get a {@link #commit(Object)} or {@link #rollback(Object)} method call later
 182    * @throws Exception
 183    */
 184    void prepare(Object tx, List<Modification> modifications, boolean one_phase) throws Exception;
 185   
 186    /**
 187    * Commits the transaction. A DB-based CacheLoader would look up the local
 188    * JDBC transaction asociated with <code>tx</code> and commit that
 189    * transaction. Non-transactional CacheLoaders could simply write the data
 190    * that was previously saved transiently under the given <code>tx</code>
 191    * key, to (for example) a file system.
 192    * <p/>
 193    * <b>Note</b> this only holds if the previous prepare() did not define <pre>one_phase=true</pre>
 194    *
 195    * @param tx transaction to commit
 196    */
 197    void commit(Object tx) throws Exception;
 198   
 199    /**
 200    * Rolls the transaction back. A DB-based CacheLoader would look up the
 201    * local JDBC transaction asociated with <code>tx</code> and roll back that
 202    * transaction.
 203    *
 204    * @param tx transaction to roll back
 205    */
 206    void rollback(Object tx);
 207   
 208    /**
 209    * Fetches the entire state for this cache from secondary storage (disk, database)
 210    * and writes it to a provided ObjectOutputStream. State written to the provided
 211    * ObjectOutputStream parameter is used for initialization of a new CacheImpl instance.
 212    * When the state gets transferred to the new cache instance its cacheloader calls
 213    * {@link #storeEntireState(ObjectInputStream)}
 214    * <p/>
 215    * Implementations of this method should not catch any exception or close the
 216    * given ObjectOutputStream parameter. In order to ensure cacheloader interoperability
 217    * contents of the cache are written to the ObjectOutputStream as a sequence of
 218    * NodeData objects.
 219    * <p/>
 220    * Default implementation is provided by {@link AbstractCacheLoader} and ensures cacheloader
 221    * interoperability. Implementors are encouraged to consider extending AbstractCacheLoader
 222    * prior to implementing completely custom cacheloader.
 223    *
 224    * @param os ObjectOutputStream to write state
 225    * @see AbstractCacheLoader#loadEntireState(ObjectOutputStream)
 226    * @see org.jboss.cache.marshall.NodeData
 227    */
 228    void loadEntireState(ObjectOutputStream os) throws Exception;
 229   
 230    /**
 231    * Stores the entire state for this cache by reading it from a provided ObjectInputStream.
 232    * The state was provided to this cache by calling {@link #loadEntireState(ObjectOutputStream)}}
 233    * on some other cache instance. State currently in storage gets overwritten.
 234    * <p/>
 235    * Implementations of this method should not catch any exception or close the
 236    * given ObjectInputStream parameter. In order to ensure cacheloader interoperability
 237    * contents of the cache are read from the ObjectInputStream as a sequence of
 238    * NodeData objects.
 239    * <p/>
 240    * Default implementation is provided by {@link AbstractCacheLoader} and ensures cacheloader
 241    * interoperability. Implementors are encouraged to consider extending AbstractCacheLoader
 242    * prior to implementing completely custom cacheloader.
 243    *
 244    * @param is ObjectInputStream to read state
 245    * @see AbstractCacheLoader#storeEntireState(ObjectInputStream)
 246    * @see org.jboss.cache.marshall.NodeData
 247    */
 248    void storeEntireState(ObjectInputStream is) throws Exception;
 249   
 250    /**
 251    * Fetches a portion of the state for this cache from secondary storage (disk, database)
 252    * and writes it to a provided ObjectOutputStream. State written to the provided
 253    * ObjectOutputStream parameter is used for activation of a portion of a new CacheImpl instance.
 254    * When the state gets transferred to the new cache instance its cacheloader calls
 255    * {@link #storeState(Fqn,ObjectInputStream)}.
 256    * <p/>
 257    * Implementations of this method should not catch any exception or close the
 258    * given ObjectOutputStream parameter. In order to ensure cacheloader interoperability
 259    * contents of the cache are written to the ObjectOutputStream as a sequence of
 260    * NodeData objects.
 261    * <p/>
 262    * Default implementation is provided by {@link AbstractCacheLoader} and ensures cacheloader
 263    * interoperability. Implementors are encouraged to consider extending AbstractCacheLoader
 264    * prior to implementing completely custom cacheloader.
 265    *
 266    * @param subtree Fqn naming the root (i.e. highest level parent) node of
 267    * the subtree for which state is requested.
 268    * @param os ObjectOutputStream to write state
 269    * @see AbstractCacheLoader#loadState(Fqn,ObjectOutputStream)
 270    * @see org.jboss.cache.Region#activate()
 271    * @see org.jboss.cache.marshall.NodeData
 272    */
 273    void loadState(Fqn subtree, ObjectOutputStream os) throws Exception;
 274   
 275    /**
 276    * Stores the given portion of the cache tree's state in secondary storage.
 277    * Overwrite whatever is currently in secondary storage. If the transferred
 278    * state has Fqns equal to or children of parameter <code>subtree</code>,
 279    * then no special behavior is required. Otherwise, ensure that
 280    * the state is integrated under the given <code>subtree</code>. Typically
 281    * in the latter case <code>subtree</code> would be the Fqn of the buddy
 282    * backup region for
 283    * a buddy group; e.g.
 284    * <p/>
 285    * If the the transferred state had Fqns starting with "/a" and
 286    * <code>subtree</code> was "/_BUDDY_BACKUP_/192.168.1.2:5555" then the
 287    * state should be stored in the local persistent store under
 288    * "/_BUDDY_BACKUP_/192.168.1.2:5555/a"
 289    * <p/>
 290    * Implementations of this method should not catch any exception or close the
 291    * given ObjectInputStream parameter. In order to ensure cacheloader interoperability
 292    * contents of the cache are read from the ObjectInputStream as a sequence of
 293    * NodeData objects.
 294    * <p/>
 295    * Default implementation is provided by {@link AbstractCacheLoader} and ensures cacheloader
 296    * interoperability. Implementors are encouraged to consider extending AbstractCacheLoader
 297    * prior to implementing completely custom cacheloader.
 298    *
 299    * @param is ObjectInputStream to read state
 300    * @param subtree Fqn naming the root (i.e. highest level parent) node of
 301    * the subtree included in <code>state</code>. If the Fqns
 302    * of the data included in <code>state</code> are not
 303    * already children of <code>subtree</code>, then their
 304    * Fqns should be altered to make them children of
 305    * <code>subtree</code> before they are persisted.
 306    * @see AbstractCacheLoader#storeState(Fqn,ObjectInputStream)
 307    * @see org.jboss.cache.marshall.NodeData
 308    */
 309    void storeState(Fqn subtree, ObjectInputStream is) throws Exception;
 310   
 311    /**
 312    * Sets the {@link org.jboss.cache.RegionManager} this object should use to manage
 313    * marshalling/unmarshalling of different regions using different
 314    * classloaders.
 315    * <p/>
 316    * <strong>NOTE:</strong> This method is only intended to be used
 317    * by the <code>CacheSPI</code> instance this cache loader is
 318    * associated with.
 319    * </p>
 320    *
 321    * @param manager the region manager to use, or <code>null</code>.
 322    */
 323    void setRegionManager(RegionManager manager);
 324   
 325    /**
 326    * Lifecycle method, called when the cache loader is created.
 327    *
 328    * @throws java.lang.Exception
 329    */
 330    void create() throws java.lang.Exception;
 331   
 332    /**
 333    * Lifecycle method, called when the cache loader is started.
 334    *
 335    * @throws java.lang.Exception
 336    */
 337    void start() throws java.lang.Exception;
 338   
 339    /**
 340    * Lifecycle method, called when the cache loader is stopped.
 341    */
 342    void stop();
 343   
 344    /**
 345    * Lifecycle method, called when the cache loader is destroyed.
 346    */
 347    void destroy();
 348   
 349    }