Node


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 java.util.Map  ;
10  import java.util.Set  ;
11  
12  /**
13   * Along with {@link Cache}, this is a central construct in the cache structure of JBoss Cache.
14   * <p/>
15   * A Node represents a point in the cache.  A Node has references to it's children, parent
16   * (each Node has a single parent) and data contained within the Node (key value pairs).
17   *
18   * @author <a HREF="mailto:manik@jboss.org">Manik Surtani (manik@jboss.org)</a>
19   * @see Cache
20   * @since 2.0.0
21   */
22  public interface Node
23  {
24     /**
25      * @return the parent node.  If the current node is a root node, this call returns null.
26      */
27     Node getParent();
28  
29     /**
30      * @return an immutable {@link Set} of child nodes.  Empty {@link Set} if there aren't any children.
31      */
32     Set  <Node> getChildren();
33  
34     /**
35      * @return an immutable {@link Set} of child node names.  Empty {@link Set} if there aren't any children.
36      */
37     Set  <Object  > getChildrenNames();
38  
39     /**
40      * @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.
41      */
42     Map  <Object  , Object  > getData();
43  
44     /**
45      * @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.
46      */
47     Set  <Object  > getKeys();
48  
49     /**
50      * @return The {@link Fqn} which represents the location of this {@link Node} in the cache structure.  The {@link Fqn} returned is absolute.
51      */
52     Fqn getFqn();
53  
54     /**
55      * Adds a child node with the given {@link Fqn} under the current node.  Returns the newly created node.
56      * <p/>
57      * If the child exists returns the child node anyway.  Guaranteed to return a non-null node.
58      * <p/>
59      * The {@link Fqn} passed in is relative to the current node.  The new child node will have an absolute fqn
60      * calculated as follows: <pre>new Fqn(getFqn(), f)</pre>.  See {@link Fqn} for the operation of this constructor.
61      *
62      * @param f {@link Fqn} of the child node, relative to the current node.
63      * @return the newly created node, or the existing node if one already exists.
64      */
65     Node addChild(Fqn f);
66  
67     /**
68      * Removes a child node specified by the given relative {@link Fqn}.
69      * <p/>
70      * If you wish to remove children based on absolute {@link Fqn}s, use the {@link Cache} interface instead.
71      *
72      * @param f {@link Fqn} of the child node, relative to the current node.
73      */
74     void removeChild(Fqn f);
75  
76     /**
77      * Removes a child node specified by the given name.
78      *
79      * @param childName name of the child node, directly under the current node.
80      */
81     void removeChild(Object   childName);
82  
83  
84     /**
85      * Returns the child node
86      *
87      * @param f {@link Fqn} of the child node
88      * @return null if the child does not exist.
89      */
90     Node getChild(Fqn f);
91  
92     /**
93      * Returns a direct child of the current node.
94      */
95     Node getChild(Object   name);
96  
97     /**
98      * Puts a key and a value into the current node's data map.
99      * Overwrites if the key already exists.
100     *
101     * @param k
102     * @param v
103     * @return Returns the old value contained under this key.  Null if key doesn't exist.
104     */
105    Object   put(Object   k, Object   v);
106 
107    /**
108     * Puts a key and a value into the current node's data map if nothing exists under the key.
109     * Does nothing if the key already exists.
110     *
111     * @param k
112     * @param v
113     */
114    void putIfAbsent(Object   k, Object   v);
115 
116    /**
117     * Puts an entire map of key-value pairs into the current node's data map.  If any data exists, existing
118     * keys are overwritten with the keys in the new map.  Basically, does
119     * <pre>
120     *   data.addAll(m);
121     * </pre>
122     * Forms a union of the 2 data sets with the new data set taking precedence.
123     *
124     * @param m
125     */
126    void put(Map  <Object  , Object  > m);
127 
128    /**
129     * Puts an entire map of key-value pairs into the current node's data map.  If any data exists, existing
130     * keys are not overwritten with the keys in the new map.
131     * <p/>
132     * Forms a union of the 2 data sets with the old data set taking precedence.
133     *
134     * @param m
135     */
136    void putIfAbsent(Map  <Object  , Object  > m);
137 
138    /**
139     * Gets data stored in the current node under key k
140     *
141     * @param k key of the data to return
142     * @return arbitrary object stored under the key in this node, null if there is no data under the given key.
143     */
144    Object   get(Object   k);
145 
146    /**
147     * Removes data stored under the given key.
148     *
149     * @param k
150     * @return Returns the old value contained under this key.  Null if key doesn't exist.
151     */
152    Object   remove(Object   k);
153 
154    /**
155     * Empties the data map.
156     */
157    void clearData();
158 
159    /**
160     * @param f {@link Fqn} relative to the current node of the child you are testing the existence of.
161     * @return Returns true if the child node denoted by the {@link Fqn} passed in exists.
162     */
163    boolean hasChild(Fqn f);
164 }
165
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags