[jboss-cvs] JBossCache/src/org/jboss/cache ...
Manik Surtani
msurtani at jboss.com
Fri Jan 19 09:47:40 EST 2007
User: msurtani
Date: 07/01/19 09:47:40
Modified: src/org/jboss/cache AbstractCacheListener.java
CacheException.java CacheSPI.java NodeSPI.java
Fqn.java Node.java CacheImpl.java Cache.java
VersionedNode.java CacheListener.java
UnversionedNode.java
Log:
Improved Javadocs
Revision Changes Path
1.5 +2 -1 JBossCache/src/org/jboss/cache/AbstractCacheListener.java
(In the diff below, changes in quantity of whitespace are not shown.)
Index: AbstractCacheListener.java
===================================================================
RCS file: /cvsroot/jboss/JBossCache/src/org/jboss/cache/AbstractCacheListener.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- AbstractCacheListener.java 3 Jan 2007 17:50:31 -0000 1.4
+++ AbstractCacheListener.java 19 Jan 2007 14:47:40 -0000 1.5
@@ -11,10 +11,11 @@
import java.util.Map;
/**
- * An abstract implementation of {@link CacheListener} with no-op methods. Subclass this as a convenience to
+ * An abstract implementation of {@link CacheListener} with no-op methods. Subclass this as a convenience, rather than
* implementing all the methods in {@link CacheListener}.
*
* @author <a href="mailto:manik at jboss.org">Manik Surtani (manik at jboss.org)</a>
+ * @see org.jboss.cache.CacheListener
* @since 2.0.0
*/
public abstract class AbstractCacheListener implements CacheListener
1.6 +5 -9 JBossCache/src/org/jboss/cache/CacheException.java
(In the diff below, changes in quantity of whitespace are not shown.)
Index: CacheException.java
===================================================================
RCS file: /cvsroot/jboss/JBossCache/src/org/jboss/cache/CacheException.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -b -r1.5 -r1.6
--- CacheException.java 11 Dec 2006 21:14:34 -0000 1.5
+++ CacheException.java 19 Jan 2007 14:47:40 -0000 1.6
@@ -1,4 +1,4 @@
-// $Id: CacheException.java,v 1.5 2006/12/11 21:14:34 genman Exp $
+// $Id: CacheException.java,v 1.6 2007/01/19 14:47:40 msurtani Exp $
/*
* JBoss, the OpenSource J2EE webOS
@@ -10,17 +10,13 @@
package org.jboss.cache;
/**
- * CacheException, mother of all cache exceptions
+ * Thrown when operations on {@link org.jboss.cache.Cache} or {@link org.jboss.cache.Node} fail unexpectedly.
+ * <p/>
+ * Specific subclasses such as {@link org.jboss.cache.lock.TimeoutException}, {@link org.jboss.cache.config.ConfigurationException} and {@link org.jboss.cache.lock.LockingException}
+ * have more specific uses.
*
* @author <a href="mailto:bela at jboss.org">Bela Ban</a>
* @author <a href="mailto:manik at jboss.org">Manik Surtani</a>
- * @version $Revision: 1.5 $
- * <p/>
- * <p><b>Revisions:</b>
- * <p/>
- * <p>Dec 27 2002 Bela Ban: first implementation
- * <p>Jan 20 2003 Bela Ban: extend NestedException (otherwise build with JDK 1.3 fails)
- * <p>Jul 17 2006 Manik Surtani: extends RuntimeException, exception chaining ctor
*/
public class CacheException extends RuntimeException
{
1.31 +4 -1 JBossCache/src/org/jboss/cache/CacheSPI.java
(In the diff below, changes in quantity of whitespace are not shown.)
Index: CacheSPI.java
===================================================================
RCS file: /cvsroot/jboss/JBossCache/src/org/jboss/cache/CacheSPI.java,v
retrieving revision 1.30
retrieving revision 1.31
diff -u -b -r1.30 -r1.31
--- CacheSPI.java 17 Jan 2007 16:24:07 -0000 1.30
+++ CacheSPI.java 19 Jan 2007 14:47:40 -0000 1.31
@@ -26,7 +26,7 @@
* to this interface should only be obtained when it is passed in to your code, for example when you write an
* {@link Interceptor}, {@link CacheLoader} or {@link CacheListener}.
* <p/>
- * <B><I>You should not attempt to directly cast a {@link Cache} instance to this interface, as in future, the implementation may not allow it.</I></B>
+ * <B><I>You should NEVER attempt to directly cast a {@link Cache} instance to this interface. In future, the implementation may not allow it.</I></B>
* <p/>
* This interface contains overridden method signatures of some methods from {@link Cache}, overridden to ensure return
* types of {@link Node} are replaced with {@link NodeSPI}.
@@ -35,6 +35,9 @@
* @author <a href="mailto:manik at jboss.org">Manik Surtani (manik at jboss.org)</a>
* @see NodeSPI
* @see Cache
+ * @see org.jboss.cache.CacheListener
+ * @see org.jboss.cache.loader.CacheLoader
+ * @see org.jboss.cache.interceptors.Interceptor
* @since 2.0.0
*/
public interface CacheSPI extends Cache
1.13 +30 -21 JBossCache/src/org/jboss/cache/NodeSPI.java
(In the diff below, changes in quantity of whitespace are not shown.)
Index: NodeSPI.java
===================================================================
RCS file: /cvsroot/jboss/JBossCache/src/org/jboss/cache/NodeSPI.java,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -b -r1.12 -r1.13
--- NodeSPI.java 19 Jan 2007 02:04:11 -0000 1.12
+++ NodeSPI.java 19 Jan 2007 14:47:40 -0000 1.13
@@ -13,9 +13,10 @@
import java.util.Set;
/**
- * A more detailed interface to {@link Node}, which is used when writing plugins for or extending JBoss Cache.
+ * A more detailed interface to {@link Node}, which is used when writing plugins for or extending JBoss Cache. References are usually
+ * obtained by calling methods on {@link org.jboss.cache.CacheSPI}.
* <p/>
- * <B><I>You should not attempt to directly cast a {@link Node} instance to this interface, as in future, the implementation may not allow it.</I></B>
+ * <B><I>You should NEVER attempt to directly cast a {@link Node} instance to this interface. In future, the implementation may not allow it.</I></B>
* <p/>
* This interface contains overridden method signatures of some methods from {@link Node}, overridden to ensure return
* types of {@link Node} are replaced with {@link NodeSPI}.
@@ -201,7 +202,8 @@
*
* @param includeMarkedAsDeleted if true, the returned set will include nodes marked as deleted
* @return a set of nodes
- * @throws org.jboss.cache.lock.LockingException if locking was not obtained
+ * @throws org.jboss.cache.lock.LockingException
+ * if locking was not obtained
*/
Set<NodeSPI> getChildrenDirect(boolean includeMarkedAsDeleted);
@@ -214,8 +216,9 @@
*
* @param childName
* @return child node
+ * @throws org.jboss.cache.lock.LockingException
+ * if locking was not obtained
* @see #getChild(Object)
- * @throws org.jboss.cache.lock.LockingException if locking was not obtained
*/
NodeSPI getChildDirect(Object childName);
@@ -228,8 +231,9 @@
*
* @param childName
* @return child node
+ * @throws org.jboss.cache.lock.LockingException
+ * if locking was not obtained
* @see #addChild(Fqn)
- * @throws org.jboss.cache.lock.LockingException if locking was not obtained
*/
NodeSPI addChildDirect(Fqn childName);
@@ -242,8 +246,9 @@
*
* @param childName
* @return child node
+ * @throws org.jboss.cache.lock.LockingException
+ * if locking was not obtained
* @see #getChild(Fqn)
- * @throws org.jboss.cache.lock.LockingException if locking was not obtained
*/
NodeSPI getChildDirect(Fqn childName);
@@ -255,8 +260,9 @@
* The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a
*
* @param fqn of child.
+ * @throws org.jboss.cache.lock.LockingException
+ * if locking was not obtained
* @see #removeChild(Fqn)
- * @throws org.jboss.cache.lock.LockingException if locking was not obtained
*/
void removeChildDirect(Fqn fqn);
@@ -268,8 +274,9 @@
* The caller needs to ensure a proper lock has been obtained prior to calling this method.
*
* @param childName of child.
+ * @throws org.jboss.cache.lock.LockingException
+ * if locking was not obtained
* @see #removeChild(Object)
- * @throws org.jboss.cache.lock.LockingException if locking was not obtained
*/
void removeChildDirect(Object childName);
@@ -283,8 +290,9 @@
*
* @param key to remove
* @return the old data contained under the key
+ * @throws org.jboss.cache.lock.LockingException
+ * if locking was not obtained
* @see #remove(Object)
- * @throws org.jboss.cache.lock.LockingException if locking was not obtained
*/
Object removeDirect(Object key);
@@ -298,12 +306,13 @@
*
* @param key of data
* @param value of data
+ * @return the previous value under the key passed in, or <tt>null</tt>
* @see #put(Object,Object)
*/
Object putDirect(Object key, Object value);
/**
- * Functionally the same as {@link #put(Map)} except that it operates directly on the node and bypasses the
+ * Functionally the same as {@link #putAll(Map)} except that it operates directly on the node and bypasses the
* interceptor chain.
* <p/>
* The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a
@@ -311,9 +320,9 @@
* <p/>
*
* @param data to put
- * @see #put(Map)
+ * @see #putAll(Map)
*/
- void putDirect(Map<Object, Object> data);
+ void putAllDirect(Map<Object, Object> data);
/**
* Functionally the same as {@link #getData()} except that it operates directly on the node and bypasses the
1.48 +32 -33 JBossCache/src/org/jboss/cache/Fqn.java
(In the diff below, changes in quantity of whitespace are not shown.)
Index: Fqn.java
===================================================================
RCS file: /cvsroot/jboss/JBossCache/src/org/jboss/cache/Fqn.java,v
retrieving revision 1.47
retrieving revision 1.48
diff -u -b -r1.47 -r1.48
--- Fqn.java 19 Jan 2007 02:04:10 -0000 1.47
+++ Fqn.java 19 Jan 2007 14:47:40 -0000 1.48
@@ -24,15 +24,15 @@
import java.util.StringTokenizer;
/**
- * A fully-qualified name (FQN) is a list of names
- * (typically Strings but can be any Object),
- * which specify a particular {@link Node} or sometimes a {@link Region}
- * in a {@link Cache}.
- * This name can be relative from the root node, or relative to
- * any node in the cache.
+ * A Fully Qualified Name (Fqn) is a list of names (typically Strings but can be any Object),
+ * which represent a path to a particular {@link Node} or sometimes a {@link Region} in a {@link Cache}.
+ * <p/>
+ * This name can be absolute (i.e., relative from the root node - {@link #ROOT}), or relative to any node in the cache. Reading the
+ * documentation on each API call that makes use of {@link org.jboss.cache.Fqn}s will tell you whether the API expects a
+ * relative or absolute Fqn.
* <p/>
* For instance, using this class to fetch a particular node might look like
- * this. (Here data on "Joe" is kept under the "Smith" surname Node, under
+ * this. (Here data on "Joe" is kept under the "Smith" surname node, under
* the "people" tree.)
* <pre>
* Fqn abc = Fqn.fromString("/people/Smith/Joe/");
@@ -43,7 +43,7 @@
* Fqn abc = new Fqn(new String[] { "people", "Smith", "Joe" });
* </pre>
* This is a bit more efficient to construct.
- *
+ * <p/>
* <p/>
* Note that<br>
* <p/>
@@ -60,7 +60,7 @@
* Another way to look at it is that the "/" separarator is only parsed when it forms
* part of a String passed in to Fqn.fromString() and not otherwise.
*
- * @version $Revision: 1.47 $
+ * @version $Revision: 1.48 $
*/
public class Fqn implements Cloneable, Externalizable, Comparable<Fqn>
{
@@ -428,13 +428,13 @@
/**
* Returns true if this fqn is child of parentFqn.
* Example usage:
- <pre>
- Fqn f1 = Fqn.fromString("/a/b");
- Fqn f2 = Fqn.fromString("/a/b/c");
- // f1.isChildOf(f2) == true
- // f1.isChildOf(f1) == false
- // f2.isChildOf(f1) == false
- </pre>
+ * <pre>
+ * Fqn f1 = Fqn.fromString("/a/b");
+ * Fqn f2 = Fqn.fromString("/a/b/c");
+ * // f1.isChildOf(f2) == true
+ * // f1.isChildOf(f1) == false
+ * // f2.isChildOf(f1) == false
+ * </pre>
*
* @param parentFqn
* @return true if the target is a child of parentFqn
@@ -449,13 +449,13 @@
/**
* Returns true if this fqn is equals or the child of parentFqn.
* Example usage:
- <pre>
- Fqn f1 = Fqn.fromString("/a/b");
- Fqn f2 = Fqn.fromString("/a/b/c");
- // f1.isChildOrEquals(f2) == true
- // f1.isChildOrEquals(f1) == true
- // f2.isChildOrEquals(f1) == false
- </pre>
+ * <pre>
+ * Fqn f1 = Fqn.fromString("/a/b");
+ * Fqn f2 = Fqn.fromString("/a/b/c");
+ * // f1.isChildOrEquals(f2) == true
+ * // f1.isChildOrEquals(f1) == true
+ * // f2.isChildOrEquals(f1) == false
+ * </pre>
*/
public boolean isChildOrEquals(Fqn parentFqn)
{
@@ -492,14 +492,13 @@
* Returns the parent of this FQN.
* The parent of the root node is {@link #ROOT}.
* Examples:
- <pre>
- Fqn f1 = Fqn.fromString("/a");
- Fqn f2 = Fqn.fromString("/a/b");
- // f1.equals( f2.getParent() ) == true
- // f1.getParent().getParent().equals(Fqn.ROOT) == true
- // Fqn.ROOT.equals( Fqn.ROOT.getParent() ) == true
- </pre>
- *
+ * <pre>
+ * Fqn f1 = Fqn.fromString("/a");
+ * Fqn f2 = Fqn.fromString("/a/b");
+ * // f1.equals( f2.getParent() ) == true
+ * // f1.getParent().getParent().equals(Fqn.ROOT) == true
+ * // Fqn.ROOT.equals( Fqn.ROOT.getParent() ) == true
+ * </pre>
*/
public Fqn getParent()
{
1.59 +9 -7 JBossCache/src/org/jboss/cache/Node.java
(In the diff below, changes in quantity of whitespace are not shown.)
Index: Node.java
===================================================================
RCS file: /cvsroot/jboss/JBossCache/src/org/jboss/cache/Node.java,v
retrieving revision 1.58
retrieving revision 1.59
diff -u -b -r1.58 -r1.59
--- Node.java 19 Jan 2007 10:50:42 -0000 1.58
+++ Node.java 19 Jan 2007 14:47:40 -0000 1.59
@@ -13,17 +13,19 @@
* A Node is a {@link Fqn named} logical grouping of data in the JBoss {@link Cache}.
* A node should be used to contain data for a single data record, for example
* information about a particular person or account.
+ * <p/>
* One purpose of grouping cache data into separate nodes is to minimize transaction
- * locking interference,
- * so for example, when multiple threads or possibly distributed caches are acccessing
- * different accounts simultaneously.
- * Another is that when making changes to this Node, its data might be kept in a single
- * database row or file on disk.
+ * locking interference, and increase concurrency. So for example, when multiple threads or
+ * possibly distributed caches are acccessing different accounts simultaneously.
+ * <p/>
+ * Another is that when making changes to this node, its data might be kept in a single
+ * database row or file on disk. (Persisted via the use of a {@link org.jboss.cache.loader.CacheLoader}.)
* <p/>
- * A Node has references to its children, parent (each Node except the root has
- * a single parent) and data contained within the Node (key-value pairs). The
+ * A node has references to its children, parent (each node except the root - defined by {@link Fqn#ROOT} - has
+ * a single parent) and data contained within the node (as key/value pairs). The
* data access methods are similar to the collections {@link Map} interface,
* but some are read-only or return copies of the underlying the data.
+ * <p/>
*
* @author <a href="mailto:manik at jboss.org">Manik Surtani (manik at jboss.org)</a>
* @see Cache
1.33 +2 -2 JBossCache/src/org/jboss/cache/CacheImpl.java
(In the diff below, changes in quantity of whitespace are not shown.)
Index: CacheImpl.java
===================================================================
RCS file: /cvsroot/jboss/JBossCache/src/org/jboss/cache/CacheImpl.java,v
retrieving revision 1.32
retrieving revision 1.33
diff -u -b -r1.32 -r1.33
--- CacheImpl.java 17 Jan 2007 16:24:07 -0000 1.32
+++ CacheImpl.java 19 Jan 2007 14:47:40 -0000 1.33
@@ -94,7 +94,7 @@
* @author <a href="mailto:manik at jboss.org">Manik Surtani (manik at jboss.org)</a>
* @author Brian Stansberry
* @author Daniel Huang (dhuang at jboss.org)
- * @version $Id: CacheImpl.java,v 1.32 2007/01/17 16:24:07 msurtani Exp $
+ * @version $Id: CacheImpl.java,v 1.33 2007/01/19 14:47:40 msurtani Exp $
* <p/>
* @see <a href="http://labs.jboss.com/portal/jbosscache/docs">JBossCache doc</a>
*/
@@ -2135,7 +2135,7 @@
}
if (erase_contents) n.clearDataDirect();
- n.putDirect(data);
+ n.putAllDirect(data);
notifier.notifyNodeModified(fqn, false, CacheListener.ModificationType.PUT_MAP, n.getDataDirect(), true);
1.21 +68 -16 JBossCache/src/org/jboss/cache/Cache.java
(In the diff below, changes in quantity of whitespace are not shown.)
Index: Cache.java
===================================================================
RCS file: /cvsroot/jboss/JBossCache/src/org/jboss/cache/Cache.java,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -b -r1.20 -r1.21
--- Cache.java 19 Jan 2007 02:04:10 -0000 1.20
+++ Cache.java 19 Jan 2007 14:47:40 -0000 1.21
@@ -16,12 +16,60 @@
/**
* Interface for a Cache where data mappings are grouped and stored in a tree data
* structure consisting of {@link Node}s.
+ * <p/>
* This is the central construct and basic client API of JBoss Cache and is used for
* cache-wide operations.
* <p/>
* The cache is constructed using a {@link CacheFactory} and is started
- * using {@link #start}, optionally preceeded by a call to @{link #create}.
+ * using {@link #start}, if not already started by the CacheFactory.
+ * <p/>
+ * Once constructed, the Cache interface can be used to create or access {@link Node}s, which contain data. Once references
+ * to {@link Node}s are obtained, data can be stored in them,
+ * <p/>
+ * As a convenience (and mainly to provide a familiar API to the older JBoss Cache 1.x.x releases) methods are provided that
+ * operate directly on nodes.
+ * <ul>
+ * <li>{@link #put(Fqn,Object,Object)} </li>
+ * <li>{@link #put(Fqn,java.util.Map)} </li>
+ * <li>{@link #get(Fqn,Object)} </li>
+ * <li>{@link #remove(Fqn,Object)} </li>
+ * <li>{@link #removeNode(Fqn)} </li>
+ * </ul>
+ * <p/>
+ * A simple example of usage:
+ * <pre>
+ * // creates with default settings and starts the cache
+ * Cache cache = DefaultCacheFactory.getInstance().createCache();
+ * Fqn personRecords = Fqn.fromString("/org/mycompany/personRecords");
+ * <p/>
+ * Node rootNode = cache.getRoot();
+ * Node personRecordsNode = rootNode.addChild(personRecords);
+ * <p/>
+ * // now add some person records.
+ * Fqn peterGriffin = Fqn.fromString("/peterGriffin");
+ * Fqn stewieGriffin = Fqn.fromString("/stewieGriffin");
+ * <p/>
+ * // the addChild() API uses relative Fqns
+ * Node peter = personRecordsNode.addChild(peterGriffin);
+ * Node stewie = personRecordsNode.addChild(stewieGriffin);
+ * <p/>
+ * peter.put("name", "Peter Griffin");
+ * peter.put("ageGroup", "MidLifeCrisis");
+ * peter.put("homicidal", Boolean.FALSE);
* <p/>
+ * stewie.put("name", "Stewie Griffin");
+ * stewie.put("ageGroup", "Infant");
+ * stewie.put("homicidal", Boolean.TRUE);
+ * <p/>
+ * peter.getFqn().toString(); // will print out /org/mycompany/personRecords/peterGriffin
+ * stewie.getFqn().toString(); // will print out /org/mycompany/personRecords/stewieGriffin
+ * <p/>
+ * peter.getFqn().getParent().equals(stewie.getFqn().getParent()); // will return true
+ * <p/>
+ * </pre>
+ * <p/>
+ * 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>,
+ * 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>.
*
* @author <a href="mailto:manik at jboss.org">Manik Surtani (manik at jboss.org)</a>
* @see Node
@@ -111,6 +159,7 @@
* This method is for caching data that has an external representation in storage,
* where, concurrent modification and transactions are not a consideration.
* <p/>
+ *
* @param fqn <b><i>absolute</i></b> {@link Fqn} to the {@link Node} to be accessed.
* @param key key with which the specified value is to be associated.
* @param value value to be associated with the specified key.
@@ -138,6 +187,7 @@
/**
* Removes a {@link Node} indicated by absolute {@link Fqn}.
+ *
* @param fqn {@link Node} to remove
*/
void removeNode(Fqn fqn);
@@ -213,6 +263,7 @@
/**
* Returns the local address of this cache in a cluster, or <code>null</code>
* if running in local mode.
+ *
* @return the local address of this cache in a cluster, or <code>null</code>
* if running in local mode.
*/
@@ -221,6 +272,7 @@
/**
* Returns a list of members in the cluster, or <code>null</code>
* if running in local mode.
+ *
* @return a {@link List} of members in the cluster, or <code>null</code>
* if running in local mode.
*/
@@ -277,8 +329,8 @@
/**
* Returns the version of the cache as a string.
*
- * @see Version#printVersion
* @return the version string of the cache.
+ * @see Version#printVersion
*/
String getVersion();
}
1.10 +7 -1 JBossCache/src/org/jboss/cache/VersionedNode.java
(In the diff below, changes in quantity of whitespace are not shown.)
Index: VersionedNode.java
===================================================================
RCS file: /cvsroot/jboss/JBossCache/src/org/jboss/cache/VersionedNode.java,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -b -r1.9 -r1.10
--- VersionedNode.java 19 Jan 2007 02:04:11 -0000 1.9
+++ VersionedNode.java 19 Jan 2007 14:47:40 -0000 1.10
@@ -12,9 +12,15 @@
import java.util.Map;
/**
- * VersionedNode extends the unversioned node by adding a data version.
+ * VersionedNode extends the {@link org.jboss.cache.UnversionedNode} by adding a {@link org.jboss.cache.optimistic.DataVersion} property.
+ * <p/>
+ * Unlike {@link org.jboss.cache.UnversionedNode}, this node supports {@link #getVersion} and {@link #setVersion(org.jboss.cache.optimistic.DataVersion)}
+ * defined in {@link org.jboss.cache.NodeSPI}
+ * <p/>
+ * Typically used when the cache mode configured is {@link org.jboss.cache.config.Configuration.NodeLockingScheme#OPTIMISTIC}
*
* @author <a href="mailto:manik at jboss.org">Manik Surtani (manik at jboss.org)</a>
+ * @since 2.0.0
*/
public class VersionedNode extends UnversionedNode
{
1.8 +18 -3 JBossCache/src/org/jboss/cache/CacheListener.java
(In the diff below, changes in quantity of whitespace are not shown.)
Index: CacheListener.java
===================================================================
RCS file: /cvsroot/jboss/JBossCache/src/org/jboss/cache/CacheListener.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -b -r1.7 -r1.8
--- CacheListener.java 19 Jan 2007 02:04:10 -0000 1.7
+++ CacheListener.java 19 Jan 2007 14:47:40 -0000 1.8
@@ -13,9 +13,22 @@
/**
* A listener API where listeners can be attached to a running {@link Cache} so users can be notified of {@link Cache} events.
* <p/>
+ * The {@link org.jboss.cache.AbstractCacheListener} provides a class with no-op implementations for all the methods defined in the
+ * interface, as a convenience if you are not interested in listening for all available events.
+ * <p/>
+ * It is important to note that notifications happen in the same process thread as the call to the cache. This means that if your
+ * listener implementation blocks or performs a long-running task, the original caller which triggered the cache event may block until
+ * the listener callback completes. It is therefore a good idea to use the listener to be notified of an event but to perform any
+ * long running tasks in a separate thread so as not to block the original caller.
+ * <p/>
+ * Also important to note is that all data maps passed in to the listener methods are read-only defensive copies of the actual data
+ * stored in the cache. Therefore it is safe to assume that the collections are static snapshots. If changes to the cache data are
+ * to be triggered by such events, make calls on the cache directly rather than attempting to change the data maps.
+ * <p/>
*
* @author <a href="mailto:manik at jboss.org">Manik Surtani (manik at jboss.org)</a>
* @see Cache#addCacheListener(CacheListener) to register a listener
+ * @see org.jboss.cache.AbstractCacheListener
* @since 2.0.0
*/
public interface CacheListener
@@ -23,8 +36,10 @@
/**
* Different cache modification types.
+ *
+ * @see CacheListener#nodeModified(Fqn,boolean,boolean,org.jboss.cache.CacheListener.ModificationType,java.util.Map)
*/
- public enum ModificationType
+ enum ModificationType
{
PUT_DATA, REMOVE_DATA, PUT_MAP
}
1.22 +7 -16 JBossCache/src/org/jboss/cache/UnversionedNode.java
(In the diff below, changes in quantity of whitespace are not shown.)
Index: UnversionedNode.java
===================================================================
RCS file: /cvsroot/jboss/JBossCache/src/org/jboss/cache/UnversionedNode.java,v
retrieving revision 1.21
retrieving revision 1.22
diff -u -b -r1.21 -r1.22
--- UnversionedNode.java 19 Jan 2007 10:50:42 -0000 1.21
+++ UnversionedNode.java 19 Jan 2007 14:47:40 -0000 1.22
@@ -26,7 +26,11 @@
import java.util.concurrent.ConcurrentHashMap;
/**
- * Basic data node class.
+ * Basic data node class. Throws {@link UnsupportedOperationException} for version-specific methods like {@link #getVersion()} and
+ * {@link #setVersion(org.jboss.cache.optimistic.DataVersion)}, defined in {@link org.jboss.cache.NodeSPI}.
+ *
+ * @author Manik Surtani (<a href="mailto:manik at jboss.org">manik at jboss.org</a>)
+ * @since 2.0.0
*/
public class UnversionedNode extends AbstractNode implements NodeSPI
{
@@ -65,7 +69,7 @@
/**
* Map of general data keys to values.
*/
- private final Map data = new HashMap();
+ private final Map<Object, Object> data = new HashMap<Object, Object>();
/**
* Constructs a new node with an FQN of Root.
@@ -145,19 +149,6 @@
return children;
}
- public void setCache(CacheSPI cache)
- {
- this.cache = (CacheImpl) cache;
- this.lock_ = null;
- if (children != null)
- {
- for (Node n : children.values())
- {
- ((UnversionedNode) n).setCache(cache);
- }
- }
- }
-
public CacheSPI getCache()
{
return cache;
@@ -521,7 +512,7 @@
cache.put(fqn, data);
}
- public synchronized void putDirect(Map data)
+ public synchronized void putAllDirect(Map<Object, Object> data)
{
if (data == null) return;
this.data.putAll(data);
More information about the jboss-cvs-commits
mailing list