[jboss-cvs] JBossCache/src/org/jboss/cache ...
Manik Surtani
msurtani at jboss.com
Fri Jan 5 03:58:37 EST 2007
User: msurtani
Date: 07/01/05 03:58:37
Modified: src/org/jboss/cache CacheSPI.java NodeSPI.java
UnversionedNode.java
Log:
- Improved javadocs
- allow for deep remove and get direct
Revision Changes Path
1.27 +8 -3 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.26
retrieving revision 1.27
diff -u -b -r1.26 -r1.27
--- CacheSPI.java 4 Jan 2007 05:35:39 -0000 1.26
+++ CacheSPI.java 5 Jan 2007 08:58:37 -0000 1.27
@@ -24,8 +24,13 @@
/**
* A more detailed interface to {@link Cache}, which is used when writing plugins for or extending JBoss Cache. A reference
* 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}. You should not attempt to directly cast a {@link Cache} instance
- * to this interface, as in future, the implementation may not allow it.
+ * {@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>
+ * <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}.
+ * <p/>
*
* @author <a href="mailto:manik at jboss.org">Manik Surtani (manik at jboss.org)</a>
* @see NodeSPI
@@ -35,7 +40,7 @@
public interface CacheSPI extends Cache
{
/**
- * Overrides {@link org.jboss.cache.Cache#getRoot()} to return a NodeSPI instead of a Node.
+ * Overrides {@link org.jboss.cache.Cache#getRoot()} to return a {@link org.jboss.cache.NodeSPI} instead of a {@link org.jboss.cache.Node}.
*/
NodeSPI getRoot();
1.10 +81 -0 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.9
retrieving revision 1.10
diff -u -b -r1.9 -r1.10
--- NodeSPI.java 4 Jan 2007 14:36:00 -0000 1.9
+++ NodeSPI.java 5 Jan 2007 08:58:37 -0000 1.10
@@ -14,9 +14,30 @@
/**
* A more detailed interface to {@link Node}, which is used when writing plugins for or extending JBoss Cache.
+ * <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>
+ * <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}.
+ * <p/>
+ * <b><i>An important note</i></b> on the xxxDirect() methods below. These methods are counterparts to similarly named
+ * methods in {@link Node} - e.g., {@link NodeSPI#getDirect(Object)} is a direct access counterpart to {@link Node#get(Object)},
+ * the difference being that:
+ * <p/>
+ * <ul>
+ * <li>{@link Node#get(Object)} - Passes the call up the interceptor stack, applies all aspects including node locking, cache loading, passivation, etc etc.</li>
+ * <li>{@link NodeSPI#get(Object)} - directly works on the underlying data in the node.</li>
+ * </ul>
+ * <p/>
+ * The big difference with the direct access methods are that it is the onus of the caller to ensure proper locks are obtained
+ * prior to the call. A proper call should have gone through a locking-capable interceptor first and based on the cache
+ * configuration's locking policy, an appropriate lock should be obtained prior to the call. These direct access methods will
+ * throw {@link org.jboss.cache.lock.LockingException}s if appropriate locks haven't been obtained by the caller.
+ * <p/>
*
* @author <a href="mailto:manik at jboss.org">Manik Surtani (manik at jboss.org)</a>
* @see Node
+ * @see org.jboss.cache.CacheSPI
* @since 2.0.0
*/
public interface NodeSPI extends Node
@@ -129,6 +150,10 @@
/**
* Functionally the same as {@link #getChildren()} 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
+ * {@link org.jboss.cache.lock.LockingException} will be thrown.
+ * <p/>
*
* @return set of child nodes.
* @see #getChildren()
@@ -137,6 +162,10 @@
/**
* Retrieves children (directly), optionally including any marked as deleted.
+ * <p/>
+ * The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a
+ * {@link org.jboss.cache.lock.LockingException} will be thrown.
+ * <p/>
*
* @param includeMarkedAsDeleted if true, even nodes marked as deleted will be returned.
* @return a set of nodes
@@ -146,6 +175,10 @@
/**
* Functionally the same as {@link #getChild(Object)} 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
+ * {@link org.jboss.cache.lock.LockingException} will be thrown.
+ * <p/>
*
* @param childName
* @return child node
@@ -156,6 +189,10 @@
/**
* Functionally the same as {@link #addChild(Fqn)} 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
+ * {@link org.jboss.cache.lock.LockingException} will be thrown.
+ * <p/>
*
* @param childName
* @return child node
@@ -166,6 +203,10 @@
/**
* Functionally the same as {@link #getChild(Fqn)} 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
+ * {@link org.jboss.cache.lock.LockingException} will be thrown.
+ * <p/>
*
* @param childName
* @return child node
@@ -176,6 +217,10 @@
/**
* Functionally the same as {@link #removeChild(Fqn)} 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
+ * {@link org.jboss.cache.lock.LockingException} will be thrown.
+ * <p/>
*
* @param fqn of child.
* @see #removeChild(Fqn)
@@ -185,6 +230,10 @@
/**
* Functionally the same as {@link #removeChild(Object)} 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
+ * {@link org.jboss.cache.lock.LockingException} will be thrown.
+ * <p/>
*
* @param childName of child.
* @see #removeChild(Object)
@@ -195,6 +244,10 @@
/**
* Functionally the same as {@link #remove(Object)} 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
+ * {@link org.jboss.cache.lock.LockingException} will be thrown.
+ * <p/>
*
* @param key to remove
* @return the old data contained under the key
@@ -205,6 +258,10 @@
/**
* Functionally the same as {@link #put(Object,Object)} 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
+ * {@link org.jboss.cache.lock.LockingException} will be thrown.
+ * <p/>
*
* @param key of data
* @param value of data
@@ -215,6 +272,10 @@
/**
* Functionally the same as {@link #put(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
+ * {@link org.jboss.cache.lock.LockingException} will be thrown.
+ * <p/>
*
* @param data to put
* @see #put(Map)
@@ -228,6 +289,10 @@
* Note that this returns a reference to access the node's data.
* This data should only be modified by the cache itself.
* This method should never return null.
+ * <p/>
+ * The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a
+ * {@link org.jboss.cache.lock.LockingException} will be thrown.
+ * <p/>
*
* @see #getData()
*/
@@ -236,6 +301,10 @@
/**
* Functionally the same as {@link #get(Object)} 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
+ * {@link org.jboss.cache.lock.LockingException} will be thrown.
+ * <p/>
*
* @param key data to get
* @see #get(Object)
@@ -246,6 +315,10 @@
/**
* Functionally the same as {@link #clearData()} 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
+ * {@link org.jboss.cache.lock.LockingException} will be thrown.
+ * <p/>
*
* @see #clearData()
*/
@@ -255,6 +328,10 @@
/**
* Functionally the same as {@link #getKeys()} 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
+ * {@link org.jboss.cache.lock.LockingException} will be thrown.
+ * <p/>
*
* @return set of keys
* @see #getKeys()
@@ -264,6 +341,10 @@
/**
* Functionally the same as {@link #getChildrenNames()} 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
+ * {@link org.jboss.cache.lock.LockingException} will be thrown.
+ * <p/>
*
* @return set of children names
* @see #getChildrenNames()
1.12 +12 -6 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.11
retrieving revision 1.12
diff -u -b -r1.11 -r1.12
--- UnversionedNode.java 4 Jan 2007 17:03:54 -0000 1.11
+++ UnversionedNode.java 5 Jan 2007 08:58:37 -0000 1.12
@@ -109,10 +109,6 @@
{
if (mapSafe)
{
- if (data.getClass().getName().startsWith("java.util.Collections"))
- {
- throw new IllegalArgumentException("What's this crap? " + data);
- }
this.data = data;// ? is this safe
}
else
@@ -211,6 +207,8 @@
public synchronized Object getDirect(Object key)
{
+ if (!getLock().getReaderOwners().contains(Thread.currentThread())) throw new CacheException();
+
return data == null ? null : data.get(key);
}
@@ -421,7 +419,14 @@
}
else
{
- throw new UnsupportedOperationException("Cannot directly retrieve children which aren't directly under the current node.");
+ NodeSPI currentNode = this;
+ for (int i = 0; i < fqn.size(); i++)
+ {
+ Object nextChildName = fqn.get(i);
+ currentNode = currentNode.getChildDirect(nextChildName);
+ if (currentNode == null) return null;
+ }
+ return currentNode;
}
}
@@ -488,7 +493,8 @@
}
else
{
- throw new UnsupportedOperationException("Cannot directly remove children which aren't directly under the current node.");
+ NodeSPI child = getChildDirect(f);
+ if (child != null) child.getParent().removeChildDirect(f.getLastElement());
}
}
More information about the jboss-cvs-commits
mailing list