Clover coverage report -
Coverage timestamp: Thu Jul 5 2007 20:02:32 EDT
file stats: LOC: 189   Methods: 0
NCLOC: 32   Classes: 2
 
 Source file Conditionals Statements Methods TOTAL
Region.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 org.jboss.cache.config.EvictionPolicyConfig;
 10    import org.jboss.cache.config.EvictionRegionConfig;
 11    import org.jboss.cache.eviction.EvictedEventNode;
 12    import org.jboss.cache.eviction.EvictionPolicy;
 13    import org.jboss.cache.eviction.LRUPolicy;
 14   
 15    /**
 16    * Defines characteristics such as class loading and eviction of {@link org.jboss.cache.Node}s belonging to a Region in a {@link Cache}.
 17    * A Region is described by an {@link #getFqn() Fqn} relative to the root of the cache.
 18    * All nodes and child nodes of this Fqn belong to this region.
 19    * <p/>
 20    * If a region is to be recognised as an eviction region (region of type {@link Type#EVICTION} then
 21    * it <b>must</b> have an {@link org.jboss.cache.config.EvictionPolicyConfig} set using {@link #setEvictionPolicy(org.jboss.cache.config.EvictionPolicyConfig)}.
 22    * <p/>
 23    * Similarly, to be recognised as a marshalling region (region of type {@link Type#MARSHALLING} then it <b>must</b> have a
 24    * {@link ClassLoader} registered using {@link #registerContextClassLoader(ClassLoader)}.
 25    * <p/>
 26    * Note that a single region can be both an eviction and marshalling region at the same time.
 27    * <p/>
 28    *
 29    * @author <a href="mailto:manik@jboss.org">Manik Surtani (manik@jboss.org)</a>
 30    * @see org.jboss.cache.RegionManager
 31    * @since 2.0.0
 32    */
 33    public interface Region extends Comparable<Region>
 34    {
 35   
 36    /**
 37    * Types of regions.
 38    */
 39    public enum Type
 40    {
 41    EVICTION, MARSHALLING, ANY
 42    }
 43   
 44    /**
 45    * Registers a specific {@link ClassLoader} for this region,
 46    * overridding the default cache class loader.
 47    *
 48    * @param classLoader specific class loader
 49    */
 50    void registerContextClassLoader(ClassLoader classLoader);
 51   
 52    /**
 53    * Unregisters a registered {@link ClassLoader}s for this region.
 54    */
 55    void unregisterContextClassLoader();
 56   
 57    /**
 58    * Activates this region for replication.
 59    * By default, the entire cache is activated for replication at start-up.
 60    *
 61    * @throws RegionNotEmptyException if the {@link Fqn} that represents this region already exists and contains data or children.
 62    */
 63    void activate() throws RegionNotEmptyException;
 64   
 65    /**
 66    * Activates this region for replication, but if the {@link Fqn} that represents this region already exists and
 67    * either contains data or children, no state transfers take place. The region is simply marked as active in this
 68    * case.
 69    */
 70    public void activateIfEmpty();
 71   
 72    /**
 73    * Deactivates this region from being replicated.
 74    */
 75    void deactivate();
 76   
 77    /**
 78    * Sets this region as active - this only marks a flag
 79    * and does not actually activates or
 80    * deactivates this region. Use {@link #activate()}
 81    * and {@link #deactivate()} for the full process.
 82    *
 83    * @param b
 84    */
 85    void setActive(boolean b);
 86   
 87    /**
 88    * Returns true if this region has been activated.
 89    *
 90    * @return true if this region has been activated.
 91    */
 92    boolean isActive();
 93   
 94    /**
 95    * Returns the configured {@link ClassLoader} for this region.
 96    *
 97    * @return a ClassLoader
 98    */
 99    ClassLoader getClassLoader();
 100   
 101    /**
 102    * Configures an eviction policy for this region.
 103    *
 104    * @param evictionPolicyConfig configuration to set
 105    */
 106    void setEvictionPolicy(EvictionPolicyConfig evictionPolicyConfig);
 107   
 108    /**
 109    * Returns an eviction policy configuration.
 110    *
 111    * @return an eviction policy configuration
 112    */
 113    EvictionPolicyConfig getEvictionPolicyConfig();
 114   
 115    /**
 116    * Returns an eviction policy.
 117    *
 118    * @return an eviction policy
 119    */
 120    EvictionPolicy getEvictionPolicy();
 121   
 122    /**
 123    * Returns an eviction region configuration for this region.
 124    *
 125    * @return an eviction region configuration
 126    */
 127    EvictionRegionConfig getEvictionRegionConfig();
 128   
 129    /**
 130    * Clears the node event queue used for processing eviction.
 131    *
 132    * @see #nodeEventQueueSize()
 133    */
 134    void resetEvictionQueues();
 135   
 136    /**
 137    * Returns the size of the node event queue, used by the eviction thread.
 138    *
 139    * @return number of events
 140    */
 141    int nodeEventQueueSize();
 142   
 143    /**
 144    * Returns the most recent {@link org.jboss.cache.eviction.EvictedEventNode} added to the event queue by
 145    * {@link #putNodeEvent(EvictedEventNode)}.
 146    *
 147    * @return the last {@link org.jboss.cache.eviction.EvictedEventNode}, or null if no more events exist
 148    */
 149    EvictedEventNode takeLastEventNode();
 150   
 151    /**
 152    * Adds an {@link org.jboss.cache.eviction.EvictedEventNode} to the internal queue for processing
 153    * by the eviction thread.
 154    *
 155    * @param event event to add
 156    */
 157    void putNodeEvent(EvictedEventNode event);
 158   
 159    /**
 160    * Marks a {@link org.jboss.cache.Node} as currently in use, by adding an event to the eviction queue.
 161    * If there is an {@link EvictionPolicy} associated with this region, and
 162    * it respects this event (e.g., {@link LRUPolicy} does), then the {@link org.jboss.cache.Node} will not
 163    * be evicted until {@link #unmarkNodeCurrentlyInUse(Fqn)} is invoked.
 164    * <p/>
 165    * This mechanism can be used to prevent eviction of data that the application
 166    * is currently using, in the absence of any locks on the {@link org.jboss.cache.Node} where the
 167    * data is stored.
 168    *
 169    * @param fqn Fqn of the node.
 170    * @see #unmarkNodeCurrentlyInUse(Fqn)
 171    */
 172    void markNodeCurrentlyInUse(Fqn fqn, long timeout);
 173   
 174    /**
 175    * Adds an event to the eviction queue indicating that a node is no longer in use.
 176    *
 177    * @param fqn Fqn of the node.
 178    * @see #markNodeCurrentlyInUse(Fqn,long)
 179    */
 180    void unmarkNodeCurrentlyInUse(Fqn fqn);
 181   
 182    /**
 183    * Returns the {@link org.jboss.cache.Fqn} of this region.
 184    *
 185    * @return the Fqn
 186    */
 187    Fqn getFqn();
 188   
 189    }