Commits

Anonymous committed a7d4d47

many javadoc fixes

  • Participants
  • Parent commits 345f688

Comments (0)

Files changed (6)

File src/core/java/com/opensymphony/oscache/base/AbstractCacheAdministrator.java

     }
 
     /**
-     * Are we caching entries in memory (true or false)?  Default is true.
+     * Whether entries are cached in memory or not.
+     * Default is true.
      * Set by the <code>cache.memory</code> property.
      *
      * @return Status whether or not memory caching is used.

File src/core/java/com/opensymphony/oscache/base/EntryUpdateState.java

     /**
      * The initial state when this object is first created
      */
-    private static final int NOT_YET_UPDATING = -1;
+    public static final int NOT_YET_UPDATING = -1;
 
     /**
      * Update in progress state
      */
-    private static final int UPDATE_IN_PROGRESS = 0;
+    public static final int UPDATE_IN_PROGRESS = 0;
 
     /**
      * Update complete state
      */
-    private static final int UPDATE_COMPLETE = 1;
+    public static final int UPDATE_COMPLETE = 1;
 
     /**
      * Update cancelled state
      */
-    private static final int UPDATE_CANCELLED = 2;
+    public static final int UPDATE_CANCELLED = 2;
 
     /**
      * Current update state
      */
-    private int state = NOT_YET_UPDATING;
+    int state = NOT_YET_UPDATING;
 
     /**
      * This is the initial state when an instance this object is first created.

File src/core/java/com/opensymphony/oscache/base/algorithm/AbstractConcurrentReadCache.java

 import java.util.*;
 
 /**
- * A version of Hashtable that supports mostly-concurrent reading, but
- * exclusive writing.  Because reads are not limited to periods
+ * A version of Hashtable that supports mostly-concurrent reading, but exclusive writing.
+ * Because reads are not limited to periods
  * without writes, a concurrent reader policy is weaker than a classic
  * reader/writer policy, but is generally faster and allows more
  * concurrency. This class is a good choice especially for tables that
     public static int DEFAULT_INITIAL_CAPACITY = 32;
 
     /**
-     * The minimum capacity, used if a lower value is implicitly specified
+     * The minimum capacity.
+     * Used if a lower value is implicitly specified
      * by either of the constructors with arguments.
      * MUST be a power of two.
      */
     private static final int MINIMUM_CAPACITY = 4;
 
     /**
-     * The maximum capacity, used if a higher value is implicitly specified
+     * The maximum capacity.
+     * Used if a higher value is implicitly specified
      * by either of the constructors with arguments.
      * MUST be a power of two <= 1<<30.
      */
     private static final int MAXIMUM_CAPACITY = 1 << 30;
 
     /**
-     * The default load factor for this table (1.0).
-     * Used when not otherwise specified in constructor.
+     * The default load factor for this table.
+     * Used when not otherwise specified in constructor, the default is 0.75f.
      **/
     public static final float DEFAULT_LOAD_FACTOR = 0.75f;
 
-    /** OpenSymphony BEGIN (pretty long!) */
+    //OpenSymphony BEGIN (pretty long!)
     protected static final String NULL = "_nul!~";
     protected static final transient Log log = LogFactory.getLog(AbstractConcurrentReadCache.class);
 
     protected transient int count;
 
     /**
-     * Persistence listener
+     * Persistence listener.
      */
     protected PersistenceListener persistenceListener = null;
 
     /**
-     * Use memory cache or not
+     * Use memory cache or not.
      */
     protected boolean memoryCaching = true;
 
     /**
-     * Use unlimited disk caching
+     * Use unlimited disk caching.
      */
     protected boolean unlimitedDiskCache = false;
 
     protected float loadFactor;
 
     /**
-     * Default cache capacity (number of entries)
+     * Default cache capacity (number of entries).
      */
     protected final int DEFAULT_MAX_ENTRIES = 100;
 
     /**
-     * Max number of element in cache when considered unlimited
+     * Max number of element in cache when considered unlimited.
      */
     protected final int UNLIMITED = 2147483646;
     protected transient Collection values = null;
 
     /**
-     * A HashMap containing the group information. Each entry uses the group
-     * name as the key, and holds a <code>Set</code> of containing keys of all
+     * A HashMap containing the group information.
+     * Each entry uses the group name as the key, and holds a
+     * <code>Set</code> of containing keys of all
      * the cache entries that belong to that particular group.
      */
     protected HashMap groups = null;
     protected transient Set keySet = null;
 
     /**
-     * Cache capacity (number of entries)
+     * Cache capacity (number of entries).
      */
     protected int maxEntries = DEFAULT_MAX_ENTRIES;
 
     /**
-     * The table is rehashed when its size exceeds this threshold.  (The
-     * value of this field is always (int)(capacity * loadFactor).)
+     * The table is rehashed when its size exceeds this threshold.
+     * (The value of this field is always (int)(capacity * loadFactor).)
      *
      * @serial
      */
     protected int threshold;
 
     /**
-     * Constructs a new, empty map with the specified initial
-     * capacity and the specified load factor.
+     * Constructs a new, empty map with the specified initial capacity and the specified load factor.
      *
      * @param initialCapacity the initial capacity
      *  The actual initial capacity is rounded to the nearest power of two.
     }
 
     /**
-     * Constructs a new, empty map with the specified initial
-     * capacity and default load factor.
+     * Constructs a new, empty map with the specified initial capacity and default load factor.
      *
      * @param   initialCapacity   the initial capacity of the
      *                            AbstractConcurrentReadCache.
     }
 
     /**
-     * Constructs a new, empty map with a default initial capacity
-     * and load factor.
+     * Constructs a new, empty map with a default initial capacity and load factor.
      */
     public AbstractConcurrentReadCache() {
         this(DEFAULT_INITIAL_CAPACITY, DEFAULT_LOAD_FACTOR);
     }
 
     /**
-     * Constructs a new map with the same mappings as the given map.  The
-     * map is created with a capacity of twice the number of mappings in
+     * Constructs a new map with the same mappings as the given map.
+     * The map is created with a capacity of twice the number of mappings in
      * the given map or 11 (whichever is greater), and a default load factor.
      */
     public AbstractConcurrentReadCache(Map t) {
     }
 
     /**
-     * Retrieve the cache capacity (number of entries)
+     * Retrieve the cache capacity (number of entries).
      */
     public int getMaxEntries() {
         return maxEntries;
     }
 
     /**
-     * Sets the memory caching flag
+     * Sets the memory caching flag.
      */
     public void setMemoryCaching(boolean memoryCaching) {
         this.memoryCaching = memoryCaching;
     }
 
     /**
-     * Check if memory caching is used
+     * Check if memory caching is used.
      */
     public boolean isMemoryCaching() {
         return memoryCaching;
     }
 
     /**
-     * Set the persistence listener to use
+     * Set the persistence listener to use.
      */
     public void setPersistenceListener(PersistenceListener listener) {
         this.persistenceListener = listener;
     }
 
     /**
-     * Get the persistence listener
+     * Get the persistence listener.
      */
     public PersistenceListener getPersistenceListener() {
         return persistenceListener;
     }
 
     /**
-     * Sets the unlimited disk caching flag
+     * Sets the unlimited disk caching flag.
      */
     public void setUnlimitedDiskCache(boolean unlimitedDiskCache) {
         this.unlimitedDiskCache = unlimitedDiskCache;
     }
 
     /**
-     * Check if we use unlimited disk cache
+     * Check if we use unlimited disk cache.
      */
     public boolean isUnlimitedDiskCache() {
         return unlimitedDiskCache;
     }
 
     /**
-     * Return the number of slots in this table
+     * Return the number of slots in this table.
      **/
     public synchronized int capacity() {
         return table.length;
     }
 
     /**
-     * Returns a shallow copy of this
+     * Returns a shallow copy of this.
      * <tt>AbstractConcurrentReadCache</tt> instance: the keys and
      * values themselves are not cloned.
      *
     }
 
     /**
-     * Returns a collection view of the mappings contained in this map.  Each
-     * element in the returned collection is a <tt>Map.Entry</tt>.  The
+     * Returns a collection view of the mappings contained in this map.
+     * Each element in the returned collection is a <tt>Map.Entry</tt>.  The
      * collection is backed by the map, so changes to the map are reflected in
      * the collection, and vice-versa.  The collection supports element
      * removal, which removes the corresponding mapping from the map, via the
     }
 
     /**
-     * Returns a set view of the keys contained in this map.  The set is
-     * backed by the map, so changes to the map are reflected in the set, and
+     * Returns a set view of the keys contained in this map.
+     * The set is backed by the map, so changes to the map are reflected in the set, and
      * vice-versa.  The set supports element removal, which removes the
      * corresponding mapping from this map, via the <tt>Iterator.remove</tt>,
      * <tt>Set.remove</tt>, <tt>removeAll</tt>, <tt>retainAll</tt>, and
     }
 
     /**
-     * Maps the specified <code>key</code> to the specified
-     * <code>value</code> in this table. Neither the key nor the
+     * Maps the specified <code>key</code> to the specified <code>value</code> in this table.
+     * Neither the key nor the
      * value can be <code>null</code>. <p>
      *
      * The value can be retrieved by calling the <code>get</code> method
     }
 
     /**
-     * Removes the key (and its corresponding value) from this
-     * table. This method does nothing if the key is not in the table.
+     * Removes the key (and its corresponding value) from this table.
+     * This method does nothing if the key is not in the table.
      *
      * @param   key   the key that needs to be removed.
      * @return  the value to which the key had been mapped in this table,
     }
 
     /**
-     * Returns a collection view of the values contained in this map.  The
-     * collection is backed by the map, so changes to the map are reflected in
+     * Returns a collection view of the values contained in this map.
+     * The collection is backed by the map, so changes to the map are reflected in
      * the collection, and vice-versa.  The collection supports element
      * removal, which removes the corresponding mapping from this map, via the
      * <tt>Iterator.remove</tt>, <tt>Collection.remove</tt>,
     }
 
     /**
-     * Get ref to groups; the reference and the cells it
+     * Get ref to groups.
+     * The reference and the cells it
      * accesses will be at least as fresh as from last
      * use of barrierLock
      **/
     }
 
     /**
-     * Helper method for entrySet.remove
+     * Helper method for entrySet remove.
      **/
     protected synchronized boolean findAndRemoveEntry(Map.Entry entry) {
         Object key = entry.getKey();
     }
 
     /**
-     * Remove an object from the persistence
-     * <p>
+     * Remove an object from the persistence.
      * @param key The key of the object to remove
      */
     protected void persistRemove(Object key) {
     }
 
     /**
-     * Removes a cache group using the persistence listener
-     * <p>
+     * Removes a cache group using the persistence listener.
      * @param groupName The name of the group to remove
      */
     protected void persistRemoveGroup(String groupName) {
     }
 
     /**
-     * Retrieve an object from the persistence listener
-     * <p>
+     * Retrieve an object from the persistence listener.
      * @param key The key of the object to retrieve
      */
     protected Object persistRetrieve(Object key) {
     }
 
     /**
-     * Retrieves a cache group using the persistence listener
-     * <p>
+     * Retrieves a cache group using the persistence listener.
      * @param groupName The name of the group to retrieve
      */
     protected Set persistRetrieveGroup(String groupName) {
     }
 
     /**
-     * Store an object in the cache using the persistence listener
-     * <p>
+     * Store an object in the cache using the persistence listener.
      * @param key The object key
      * @param obj The object to store
      */
     }
 
     /**
-     * Creates or Updates a cache group using the persistence listener
-     * <p>
+     * Creates or Updates a cache group using the persistence listener.
      * @param groupName The name of the group to update
      * @param group The entries for the group
      */
     protected abstract void itemPut(Object key);
 
     /**
-     * Notify any underlying algorithm that an item has been retrieved
-     * from the cache.
+     * Notify any underlying algorithm that an item has been retrieved from the cache.
      *
      * @param key The cache key of the item that was retrieved.
      */
     protected abstract void itemRemoved(Object key);
 
     /**
-     * The cache has reached its cacpacity and an item needs to be removed
+     * The cache has reached its cacpacity and an item needs to be removed.
      * (typically according to an algorithm such as LRU or FIFO).
      *
      * @return The key of whichever item was removed.
     protected abstract Object removeItem();
 
     /**
-     * Reconstitute the <tt>AbstractConcurrentReadCache</tt>
+     * Reconstitute the <tt>AbstractConcurrentReadCache</tt>.
      * instance from a stream (i.e.,
      * deserialize it).
      */
     }
 
     /**
-     * Rehashes the contents of this map into a new table
-     * with a larger capacity. This method is called automatically when the
+     * Rehashes the contents of this map into a new table with a larger capacity.
+     * This method is called automatically when the
      * number of keys in this map exceeds its capacity and load factor.
      */
     protected void rehash() {
     }
 
     /**
-     * Save the state of the <tt>AbstractConcurrentReadCache</tt>
-     * instance to a stream (i.e.,
-     * serialize it).
+     * Save the state of the <tt>AbstractConcurrentReadCache</tt> instance to a stream.
+     * (i.e., serialize it).
      *
      * @serialData The <i>capacity</i> of the
      * AbstractConcurrentReadCache (the length of the
     }
 
     /**
-     * Return hash code for Object x. Since we are using power-of-two
+     * Return hash code for Object x.
+     * Since we are using power-of-two
      * tables, it is worth the effort to improve hashcode via
      * the same multiplicative scheme as used in IdentityHashMap.
      */
     }
 
     /**
-     * Add this cache key to the groups specified groups. We have to treat the
+     * Add this cache key to the groups specified groups.
+     * We have to treat the
      * memory and disk group mappings seperately so they remain valid for their
      * corresponding memory/disk caches. (eg if mem is limited to 100 entries
      * and disk is unlimited, the group mappings will be different).
     }
 
     /**
-     * Remove this CacheEntry from the groups it no longer belongs to. We have
-     * to treat the memory and disk group mappings seperately so they remain
+     * Remove this CacheEntry from the groups it no longer belongs to.
+     *  We have to treat the memory and disk group mappings seperately so they remain
      * valid for their corresponding memory/disk caches. (eg if mem is limited
      * to 100 entries and disk is unlimited, the group mappings will be
      * different).
     }
 
     /**
-     * Updates the groups to reflect the differences between the old and new
-     * cache entries. Either of the old or new values can be <code>null</code>
+     * Updates the groups to reflect the differences between the old and new cache entries.
+     * Either of the old or new values can be <code>null</code>
      * or contain a <code>null</code> group list, in which case the entry's
      * groups will all be added or removed respectively.
      *
         }
 
         /**
-         * Set the value of this entry.  Note: In an entrySet or
+         * Set the value of this entry.
+         * Note: In an entrySet or
          * entrySet.iterator), unless the set or iterator is used under
          * synchronization of the table as a whole (or you can otherwise
          * guarantee lack of concurrent modification), <tt>setValue</tt>
         }
 
         /**
-         * Get the value.  Note: In an entrySet or entrySet.iterator,
+         * Get the value.
+         * Note: In an entrySet or entrySet.iterator,
          * unless the set or iterator is used under synchronization of the
          * table as a whole (or you can otherwise guarantee lack of
          * concurrent modification), <tt>getValue</tt> <em>might</em>

File src/core/java/com/opensymphony/oscache/base/events/ScopeEvent.java

 import java.util.Date;
 
 /**
- * A <code>ScopeEvent</code> is created when an event occurs across one
- * or all scopes. This type of event is only applicable to the
- * <code>ServletCacheAdministrator</code>.
+ * A <code>ScopeEvent</code> is created when an event occurs across one or all scopes.
+ * This type of event is only applicable to the <code>ServletCacheAdministrator</code>.
  *
  * @version        $Revision$
  * @author <a href="mailto:fbeauregard@pyxis-tech.com">Francois Beauregard</a>
     private int scope = 0;
 
     /**
-     * Constructs a scope event object with no specified origin
+     * Constructs a scope event object with no specified origin.
      *
      * @param eventType   Type of the event.
      * @param scope       Scope that applies to the event.
     }
 
     /**
-     * Constructs a scope event object
+     * Constructs a scope event object.
      *
      * @param eventType   Type of the event.
      * @param scope       Scope that applies to the event.

File src/core/java/com/opensymphony/oscache/extra/ScopeEventListenerImpl.java

 import com.opensymphony.oscache.base.events.ScopeEventType;
 
 /**
- * Implementation of a ScopeEventListener. It keeps track of the scope flush events
- *
+ * Implementation of a ScopeEventListener that keeps track of the scope flush events.
  * We are not using any synchronized so that this does not become a bottleneck.
  * The consequence is that on retrieving values, the operations that are
  * currently being done won't be counted.
     /**
      * Number of known scopes
      */
-    private static final int NB_SCOPES = 4;
+    public static final int NB_SCOPES = 4;
 
     /**
      * Page scope number
      */
-    private static final int PAGE_SCOPE = 1;
+    public static final int PAGE_SCOPE = 1;
 
     /**
      * Request scope number
      */
-    private static final int REQUEST_SCOPE = 2;
+    public static final int REQUEST_SCOPE = 2;
 
     /**
      * Session scope number
      */
-    private static final int SESSION_SCOPE = 3;
+    public static final int SESSION_SCOPE = 3;
 
     /**
      * Application scope number
      */
-    private static final int APPLICATION_SCOPE = 4;
+    public static final int APPLICATION_SCOPE = 4;
 
     /**
-     * Flush counter for all scopes. Add one to the number of scope because
-     * the array is being used from position 1 instead of 0 for convenience
+     * Flush counter for all scopes.
+     * Add one to the number of scope because the array is being used
+     * from position 1 instead of 0 for convenience
      */
     private int[] scopeFlushCount = new int[NB_SCOPES + 1];
 
-    /**
-     * Constructor, empty for us
-     */
     public ScopeEventListenerImpl() {
     }
 
     /**
-     * Gets the flush count for scope 4
+     * Gets the flush count for scope {@link ScopeEventListenerImpl#APPLICATION_SCOPE}.
      * <p>
      * @return The total number of application flush
      */
     }
 
     /**
-     * Gets the flush count for scope 1
-     * <p>
+     * Gets the flush count for scope {@link ScopeEventListenerImpl#PAGE_SCOPE}.
      * @return The total number of page flush
      */
     public int getPageScopeFlushCount() {
     }
 
     /**
-     * Gets the flush count for scope 2
-     * <p>
+     * Gets the flush count for scope {@link ScopeEventListenerImpl#REQUEST_SCOPE}.
      * @return The total number of request flush
      */
     public int getRequestScopeFlushCount() {
     }
 
     /**
-     * Gets the flush count for scope 3
-     * <p>
+     * Gets the flush count for scope {@link ScopeEventListenerImpl#SESSION_SCOPE}.
      * @return The total number of session flush
      */
     public int getSessionScopeFlushCount() {
     }
 
     /**
-     * Returns the total flush count
-     * <p>
+     * Returns the total flush count.
      * @return The total number of scope flush
      */
     public int getTotalScopeFlushCount() {
     }
 
     /**
-     * Handles all the scope flush events
-     * <p>
+     * Handles all the scope flush events.
      * @param event The scope event
      */
     public void scopeFlushed(ScopeEvent event) {
     }
 
     /**
-     * Returns all the flush counter in a string from
+     * Returns all the flush counter in a string form.
      */
     public String toString() {
         StringBuffer returnString = new StringBuffer("Flush count for ");

File src/core/java/com/opensymphony/oscache/web/tag/FlushTag.java

 import javax.servlet.jsp.tagext.TagSupport;
 
 /**
- * FlushTag flushes caches created with &lt;cache&gt;<p>
+ * FlushTag flushes caches created with &lt;cache&gt;.
  *
- * It gives programmatic control over when caches are flushed, and can flush all caches at once.<p>
+ * This tag provides programmatic control over when caches are flushed,
+ * and can flush all caches at once.<p>
  *
  * Usage Examples:
  * <pre><code>
     ServletCacheAdministrator admin = null;
 
     /**
-     * A cache group. If this is supplied, all content in that group will be flushed
+     * A cache group.
+     * If specified, all content in that group will be flushed
      */
     String group = null;
 
     /**
-     * Tag key
+     * Tag key.
      */
     String key = null;
 
     /**
-     * if pattern value is specified, all keys that contain the pattern are flushed
+     * if pattern value is specified, all keys that contain the pattern are flushed.
      */
     String pattern = null;
     String scope = null;
     int cacheScope = -1;
 
     /**
-     *  The ISO-639 language code to distinguish different pages in application scope
+     *  The ISO-639 language code to distinguish different pages in application scope.
      */
     private String language = null;
 
     /**
-     * The group to be flushed. If specified, all cached content in the group
-     * will be flushed.
+     * The group to be flushed.
+     * If specified, all cached content in the group will be flushed.
      *
      * @param group The name of the group to flush.
      */
     }
 
     /**
-     * The key to be flushed. If specified, only one cache entry will be flushed.
+     * The key to be flushed.
+     * If specified, only one cache entry will be flushed.
      *
      * @param value The key of the specific entry to flush.
      */
     }
 
     /**
-     * Set the ISO-639 language code to distinguish different pages in application scope
+     * Set the ISO-639 language code to distinguish different pages in application scope.
      *
      * @param value The language code for this cache entry.
      */
     }
 
     /**
-     *  The key pattern to be flushed. If specified, all entries that contain
-     *  the pattern will be flushed.
-     *
-     *        @param value The key of the specific entry to flush.
+     *  The key pattern to be flushed.
+     * If specified, all entries that contain the pattern will be flushed.
+     *  @param value The key of the specific entry to flush.
      */
     public void setPattern(String value) {
         this.pattern = value;
     }
 
     /**
-     * Process the start of the tag
+     * Process the start of the tag.
      *
      * @throws JspTagException The standard tag exception thrown.
      * @return The standard Tag return.