[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