Clover coverage report -
Coverage timestamp: Thu Jul 5 2007 20:02:32 EDT
file stats: LOC: 263   Methods: 0
NCLOC: 30   Classes: 1
 
 Source file Conditionals Statements Methods TOTAL
Node.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 net.jcip.annotations.ThreadSafe;
 10   
 11    import java.util.Map;
 12    import java.util.Set;
 13   
 14    /**
 15    * A Node is a {@link Fqn named} logical grouping of data in the JBoss {@link Cache}.
 16    * A node should be used to contain data for a single data record, for example
 17    * information about a particular person or account.
 18    * <p/>
 19    * One purpose of grouping cache data into separate nodes is to minimize transaction
 20    * locking interference, and increase concurrency. So for example, when multiple threads or
 21    * possibly distributed caches are acccessing different accounts simultaneously.
 22    * <p/>
 23    * Another is that when making changes to this node, its data might be kept in a single
 24    * database row or file on disk. (Persisted via the use of a {@link org.jboss.cache.loader.CacheLoader}.)
 25    * <p/>
 26    * A node has references to its children, parent (each node except the root - defined by {@link Fqn#ROOT} - has
 27    * a single parent) and data contained within the node (as key/value pairs). The
 28    * data access methods are similar to the collections {@link Map} interface,
 29    * but some are read-only or return copies of the underlying the data.
 30    * <p/>
 31    *
 32    * @author <a href="mailto:manik@jboss.org">Manik Surtani (manik@jboss.org)</a>
 33    * @see Cache
 34    * @since 2.0.0
 35    */
 36    @ThreadSafe
 37    public interface Node<K, V>
 38    {
 39    /**
 40    * Returns the parent node.
 41    * If this is the root node, this method returns <code>null</code>.
 42    *
 43    * @return the parent node, or null if this is the root node
 44    */
 45    Node<K, V> getParent();
 46   
 47    /**
 48    * Returns an immutable set of children nodes.
 49    *
 50    * @return an immutable {@link Set} of child nodes. Empty {@link Set} if there aren't any children.
 51    */
 52    Set<Node<K, V>> getChildren();
 53   
 54    /**
 55    * Returns an immutable set of children node names.
 56    *
 57    * @return an immutable {@link Set} of child node names. Empty {@link Set} if there aren't any children.
 58    */
 59    Set<Object> getChildrenNames();
 60   
 61    /**
 62    * Returns a map containing the data in this {@link Node}.
 63    *
 64    * @return a {@link Map} containing the data in this {@link Node}. If there is no data, an empty {@link Map} is returned. The {@link Map} returned is always immutable.
 65    */
 66    Map<K, V> getData();
 67   
 68    /**
 69    * Returns a {@link Set} containing the data in this {@link Node}.
 70    *
 71    * @return a {@link Set} containing the data in this {@link Node}. If there is no data, an empty {@link Set} is returned. The {@link Set} returned is always immutable.
 72    */
 73    Set<K> getKeys();
 74   
 75    /**
 76    * Returns the {@link Fqn} which represents the location of this {@link Node} in the cache structure. The {@link Fqn} returned is absolute.
 77    *
 78    * @return The {@link Fqn} which represents the location of this {@link Node} in the cache structure. The {@link Fqn} returned is absolute.
 79    */
 80    Fqn getFqn();
 81   
 82    /**
 83    * Adds a child node with the given {@link Fqn} under the current node. Returns the newly created node.
 84    * <p/>
 85    * If the child exists returns the child node anyway. Guaranteed to return a non-null node.
 86    * <p/>
 87    * The {@link Fqn} passed in is relative to the current node. The new child node will have an absolute fqn
 88    * calculated as follows: <pre>new Fqn(getFqn(), f)</pre>. See {@link Fqn} for the operation of this constructor.
 89    *
 90    * @param f {@link Fqn} of the child node, relative to the current node.
 91    * @return the newly created node, or the existing node if one already exists.
 92    */
 93    Node<K, V> addChild(Fqn<?> f);
 94   
 95    /**
 96    * Removes a child node specified by the given relative {@link Fqn}.
 97    * <p/>
 98    * If you wish to remove children based on absolute {@link Fqn}s, use the {@link Cache} interface instead.
 99    *
 100    * @param f {@link Fqn} of the child node, relative to the current node.
 101    * @return true if the node was found and removed, false otherwise
 102    */
 103    boolean removeChild(Fqn<?> f);
 104   
 105    /**
 106    * Removes a child node specified by the given name.
 107    *
 108    * @param childName name of the child node, directly under the current node.
 109    * @return true if the node was found and removed, false otherwise
 110    */
 111    boolean removeChild(Object childName);
 112   
 113   
 114    /**
 115    * Returns the child node
 116    *
 117    * @param f {@link Fqn} of the child node
 118    * @return null if the child does not exist.
 119    */
 120    Node<K, V> getChild(Fqn<?> f);
 121   
 122    /**
 123    * @param name name of the child
 124    * @return a direct child of the current node.
 125    */
 126    Node<K, V> getChild(Object name);
 127   
 128    /**
 129    * Associates the specified value with the specified key for this node.
 130    * If this node previously contained a mapping for this key, the old value is replaced by the specified value.
 131    *
 132    * @param key key with which the specified value is to be associated.
 133    * @param value value to be associated with the specified key.
 134    * @return Returns the old value contained under this key. Null if key doesn't exist.
 135    */
 136    V put(K key, V value);
 137   
 138    /**
 139    * If the specified key is not already associated with a value, associate it with the given value, and returns the
 140    * Object (if any) that occupied the space, or null.
 141    * <p/>
 142    * Equivalent to calling
 143    * <pre>
 144    * if (!node.getKeys().contains(key))
 145    * return node.put(key, value);
 146    * else
 147    * return node.get(key);
 148    * </pre>
 149    * <p/>
 150    * except that this is atomic.
 151    *
 152    * @param key key with which the specified value is to be associated.
 153    * @param value value to be associated with the specified key.
 154    * @return previous value associated with specified key, or null if there was no mapping for key.
 155    */
 156    V putIfAbsent(K key, V value);
 157   
 158    /**
 159    * Replace entry for key only if currently mapped to some value.
 160    * Acts as
 161    * <pre>
 162    * if ((node.getKeys().contains(key))
 163    * {
 164    * return node.put(key, value);
 165    * }
 166    * else
 167    * return null;
 168    * </pre>
 169    * <p/>
 170    * except that this is atomic.
 171    *
 172    * @param key key with which the specified value is associated.
 173    * @param value value to be associated with the specified key.
 174    * @return previous value associated with specified key, or <tt>null</tt>
 175    * if there was no mapping for key.
 176    */
 177    V replace(K key, V value);
 178   
 179    /**
 180    * Replace entry for key only if currently mapped to given value.
 181    * Acts as
 182    * <pre>
 183    * if (node.get(key).equals(oldValue))
 184    * {
 185    * node.putAll(key, newValue);
 186    * return true;
 187    * }
 188    * else
 189    * return false;
 190    * </pre>
 191    * <p/>
 192    * except that this is atomic.
 193    *
 194    * @param key key with which the specified value is associated.
 195    * @param oldValue value expected to be associated with the specified key.
 196    * @param newValue value to be associated with the specified key.
 197    * @return true if the value was replaced
 198    */
 199    boolean replace(K key, V oldValue, V newValue);
 200   
 201   
 202    /**
 203    * Copies all of the mappings from the specified map to this node's map.
 204    * If any data exists, existing keys are overwritten with the keys in the new map.
 205    * The behavior is equivalent to:
 206    * <pre>
 207    * Node node;
 208    * for (Map.Entry me : map.entrySet())
 209    * node.put(me.getKey(), me.getValue());
 210    * </pre>
 211    *
 212    * @param map map to copy from
 213    */
 214    void putAll(Map<K, V> map);
 215   
 216    /**
 217    * Similar to {@link #putAll(java.util.Map)} except that it removes any entries that exists in
 218    * the data map first. Note that this happens atomically, under a single lock. This is the analogous
 219    * to doing a {@link #clearData()} followed by a {@link #putAll(java.util.Map)} in the same transaction.
 220    *
 221    * @param map map to copy from
 222    */
 223    void replaceAll(Map<K, V> map);
 224   
 225   
 226    /**
 227    * Returns the value to which this node maps the specified key.
 228    * Returns <code>null</code> if the node contains no mapping for this key.
 229    *
 230    * @param key key of the data to return
 231    * @return the value to which this node maps the specified key, or <code>null</code> if the map contains no mapping for this key
 232    */
 233    V get(K key);
 234   
 235    /**
 236    * Removes the mapping for this key from this node if it is present.
 237    * Returns the value to which the node previously associated the key,
 238    * or <code>null</code> if the node contained no mapping for this key
 239    *
 240    * @param key key whose mapping is to be removed
 241    * @return previous value associated with specified key, or <code>null</code>
 242    * if there was no mapping for key
 243    */
 244    V remove(K key);
 245   
 246    /**
 247    * Removes all mappings from the node's data map.
 248    */
 249    void clearData();
 250   
 251    /**
 252    * @return the number of elements (key/value pairs) in the node's data map.
 253    */
 254    int dataSize();
 255   
 256    /**
 257    * Returns true if the child node denoted by the relative {@link Fqn} passed in exists.
 258    *
 259    * @param f {@link Fqn} relative to the current node of the child you are testing the existence of.
 260    * @return true if the child node denoted by the relative {@link Fqn} passed in exists.
 261    */
 262    boolean hasChild(Fqn<?> f);
 263    }