|
|||||||||||||||||||
Source file | Conditionals | Statements | Methods | TOTAL | |||||||||||||||
Node.java | - | - | - | - |
|
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 | } |
|