NodeSPI


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 org.jboss.cache.lock.NodeLock;
10  import org.jboss.cache.optimistic.DataVersion;
11  
12  import java.util.Map  ;
13  import java.util.Set  ;
14  
15  /**
16   * A more detailed interface to {@link Node}, which is used when writing plugins for or extending JBoss Cache.
17   * <p/>
18   * <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>
19   * <p/>
20   * This interface contains overridden method signatures of some methods from {@link Node}, overridden to ensure return
21   * types of {@link Node} are replaced with {@link NodeSPI}.
22   * <p/>
23   * <b><i>An important note</i></b> on the xxxDirect() methods below.  These methods are counterparts to similarly named
24   * methods in {@link Node} - e.g., {@link NodeSPI#getDirect(Object)} is a direct access counterpart to {@link Node#get(Object)},
25   * the difference being that:
26   * <p/>
27   * <ul>
28   * <li>{@link Node#get(Object)} - Passes the call up the interceptor stack, applies all aspects including node locking, cache loading, passivation, etc etc.</li>
29   * <li>{@link NodeSPI#get(Object)} - directly works on the underlying data in the node.</li>
30   * </ul>
31   * <p/>
32   * The big difference with the direct access methods are that it is the onus of the caller to ensure proper locks are obtained
33   * prior to the call.  A proper call should have gone through a locking-capable interceptor first and based on the cache
34   * configuration's locking policy, an appropriate lock should be obtained prior to the call.  These direct access methods will
35   * throw {@link org.jboss.cache.lock.LockingException}s if appropriate locks haven't been obtained by the caller.
36   * <p/>
37   * It is important to node that the direct <b>read</b> methods, such as getDataDirect(), return unmodifiable collections.
38   * In addition to being unmodifiable, they are also defensively copied from the underlying data map to ensure view consistency.
39   * <p/>
40   *
41   * @author <a HREF="mailto:manik@jboss.org">Manik Surtani (manik@jboss.org)</a>
42   * @see Node
43   * @see org.jboss.cache.CacheSPI
44   * @since 2.0.0
45   */
46  public interface NodeSPI extends Node
47  {
48     /**
49      * @return true if the children of this node were loaded from a cache loader.
50      */
51     boolean getChildrenLoaded();
52  
53     /**
54      * Sets if the children of this node were loaded from a cache loader.
55      *
56      * @param loaded true if loaded, false otherwise
57      */
58     void setChildrenLoaded(boolean loaded);
59  
60     /**
61      * @return true if the data was loaded from the cache loader.
62      */
63     public boolean getDataLoaded();
64  
65     /**
66      * Sets if the data was loaded from the cache loader.
67      *
68      * @param dataLoaded true if loaded, false otherwise
69      */
70     public void setDataLoaded(boolean dataLoaded);
71  
72     /**
73      * Returns a map to access the raw children.
74      * This method will never return null.
75      *
76      * @return Map, keyed by child name, values Nodes.
77      */
78     Map  <Object  , Node> getChildrenMapDirect();
79  
80     /**
81      * Sets the node's children explictly.
82      * This method will remove all children currently associated with this node and add all the children passed in.
83      *
84      * @param children cannot be null
85      */
86     void setChildrenMapDirect(Map  <Object  , Node> children);
87  
88     /**
89      * Returns an existing child or creates a new one using a global transaction.
90      *
91      * @return newly created node
92      */
93     NodeSPI getOrCreateChild(Object   name, GlobalTransaction tx);
94  
95     /**
96      * Returns a lock for this node.
97      *
98      * @return node lock
99      */
100    NodeLock getLock();
101 
102    /**
103     * Sets the FQN of this node and resets the names of all children as well.
104     */
105    void setFqn(Fqn f);
106 
107    /**
108     * @return true if the instance has been deleted in the current transaction.
109     */
110    boolean isDeleted();
111 
112    /**
113     * Marks the node as being deleted (or not) in the current transaction.  This is not recursive, child nodes are not affected.
114     *
115     * @param marker true if the node has been deleted, false if not.
116     */
117    void markAsDeleted(boolean marker);
118 
119    /**
120     * Same as {@link #markAsDeleted(boolean)} except that the option to recurse into children is provided.
121     *
122     * @param marker    true if the node has been deleted, false if not.
123     * @param recursive if true, child nodes (and their children) are marked as well.
124     */
125    void markAsDeleted(boolean marker, boolean recursive);
126 
127    void addChild(Object   nodeName, Node nodeToAdd);
128 
129    /**
130     * Prints details of this node to the StringBuffer passed in.
131     *
132     * @param sb     StringBuffer to print to
133     * @param indent depth of this node in the tree.  Used to indent details by prepending spaces.
134     */
135    void printDetails(StringBuffer   sb, int indent);
136 
137    /**
138     * Prints basic information of this node to the StringBuffer passed in.
139     *
140     * @param sb     StringBuffer to print to
141     * @param indent depth of this node in the tree.  Used to indent details by prepending spaces.
142     */
143 
144    void print(StringBuffer   sb, int indent);
145 
146    // versioning
147    /**
148     * May throw UnsupportedOperationException if versioning is not used.  Otherwise, sets the data version of this node.
149     *
150     * @param version a {@link org.jboss.cache.optimistic.DataVersion} implementation.
151     */
152    void setVersion(DataVersion version);
153 
154    /**
155     * May throw UnsupportedOperationException if versioning is not used.  Otherwise, retrieves the data version of the node.
156     *
157     * @return A data version
158     */
159    DataVersion getVersion();
160 
161 
162    // ------- these XXXDirect() methods work directly on the node and bypass the interceptor chain.
163    /**
164     * Functionally the same as {@link #getChildren()} except that it operates directly on the node and bypasses the
165     * interceptor chain.
166     * <p/>
167     * The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a
168     * {@link org.jboss.cache.lock.LockingException} will be thrown.
169     * <p/>
170     *
171     * @return set of child nodes.
172     * @see #getChildren()
173     */
174    Set  <NodeSPI> getChildrenDirect();
175 
176    /**
177     * Directly removes all children for this node.  The only direct method that does not have a non-direct counterpart.
178     */
179    void removeChildrenDirect();
180 
181 
182    /**
183     * Retrieves children (directly), optionally including any marked as deleted.
184     * <p/>
185     * The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a
186     * {@link org.jboss.cache.lock.LockingException} will be thrown.
187     * <p/>
188     *
189     * @param includeMarkedAsDeleted if true, even nodes marked as deleted will be returned.
190     * @return a set of nodes
191     */
192    Set  <NodeSPI> getChildrenDirect(boolean includeMarkedAsDeleted);
193 
194    /**
195     * Functionally the same as {@link #getChild(Object)} except that it operates directly on the node and bypasses the
196     * interceptor chain.
197     * <p/>
198     * The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a
199     * {@link org.jboss.cache.lock.LockingException} will be thrown.
200     * <p/>
201     *
202     * @param childName
203     * @return child node
204     * @see #getChild(Object)
205     */
206    NodeSPI getChildDirect(Object   childName);
207 
208    /**
209     * Functionally the same as {@link #addChild(Fqn)} except that it operates directly on the node and bypasses the
210     * interceptor chain.
211     * <p/>
212     * The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a
213     * {@link org.jboss.cache.lock.LockingException} will be thrown.
214     * <p/>
215     *
216     * @param childName
217     * @return child node
218     * @see #addChild(Fqn)
219     */
220    NodeSPI addChildDirect(Fqn childName);
221 
222    /**
223     * Functionally the same as {@link #getChild(Fqn)} except that it operates directly on the node and bypasses the
224     * interceptor chain.
225     * <p/>
226     * The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a
227     * {@link org.jboss.cache.lock.LockingException} will be thrown.
228     * <p/>
229     *
230     * @param childName
231     * @return child node
232     * @see #getChild(Fqn)
233     */
234    NodeSPI getChildDirect(Fqn childName);
235 
236    /**
237     * Functionally the same as {@link #removeChild(Fqn)} except that it operates directly on the node and bypasses the
238     * interceptor chain.
239     * <p/>
240     * The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a
241     * {@link org.jboss.cache.lock.LockingException} will be thrown.
242     * <p/>
243     *
244     * @param fqn of child.
245     * @see #removeChild(Fqn)
246     */
247    void removeChildDirect(Fqn fqn);
248 
249    /**
250     * Functionally the same as {@link #removeChild(Object)} except that it operates directly on the node and bypasses the
251     * interceptor chain.
252     * <p/>
253     * The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a
254     * {@link org.jboss.cache.lock.LockingException} will be thrown.
255     * <p/>
256     *
257     * @param childName of child.
258     * @see #removeChild(Object)
259     */
260    void removeChildDirect(Object   childName);
261 
262 
263    /**
264     * Functionally the same as {@link #remove(Object)} except that it operates directly on the node and bypasses the
265     * interceptor chain.
266     * <p/>
267     * The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a
268     * {@link org.jboss.cache.lock.LockingException} will be thrown.
269     * <p/>
270     *
271     * @param key to remove
272     * @return the old data contained under the key
273     * @see #remove(Object)
274     */
275    Object   removeDirect(Object   key);
276 
277    /**
278     * Functionally the same as {@link #put(Object,Object)} except that it operates directly on the node and bypasses the
279     * interceptor chain.
280     * <p/>
281     * The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a
282     * {@link org.jboss.cache.lock.LockingException} will be thrown.
283     * <p/>
284     *
285     * @param key   of data
286     * @param value of data
287     * @see #put(Object,Object)
288     */
289    Object   putDirect(Object   key, Object   value);
290 
291    /**
292     * Functionally the same as {@link #put(Map)} except that it operates directly on the node and bypasses the
293     * interceptor chain.
294     * <p/>
295     * The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a
296     * {@link org.jboss.cache.lock.LockingException} will be thrown.
297     * <p/>
298     *
299     * @param data to put
300     * @see #put(Map)
301     */
302    void putDirect(Map  <Object  , Object  > data);
303 
304    /**
305     * Functionally the same as {@link #getData()}  except that it operates directly on the node and bypasses the
306     * interceptor chain.
307     * <p/>
308     * Note that this returns a reference to access the node's data.
309     * This data should only be modified by the cache itself.
310     * This method should never return null.
311     * <p/>
312     * The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a
313     * {@link org.jboss.cache.lock.LockingException} will be thrown.
314     * <p/>
315     *
316     * @see #getData()
317     */
318    Map  <Object  , Object  > getDataDirect();
319 
320    /**
321     * Functionally the same as {@link #get(Object)}   except that it operates directly on the node and bypasses the
322     * interceptor chain.
323     * <p/>
324     * The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a
325     * {@link org.jboss.cache.lock.LockingException} will be thrown.
326     * <p/>
327     *
328     * @param key data to get
329     * @see #get(Object)
330     */
331    Object   getDirect(Object   key);
332 
333 
334    /**
335     * Functionally the same as {@link #clearData()}  except that it operates directly on the node and bypasses the
336     * interceptor chain.
337     * <p/>
338     * The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a
339     * {@link org.jboss.cache.lock.LockingException} will be thrown.
340     * <p/>
341     *
342     * @see #clearData()
343     */
344    void clearDataDirect();
345 
346 
347    /**
348     * Functionally the same as {@link #getKeys()} except that it operates directly on the node and bypasses the
349     * interceptor chain.
350     * <p/>
351     * The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a
352     * {@link org.jboss.cache.lock.LockingException} will be thrown.
353     * <p/>
354     *
355     * @return set of keys
356     * @see #getKeys()
357     */
358    Set  <Object  > getKeysDirect();
359 
360    /**
361     * Functionally the same as {@link #getChildrenNames()}  except that it operates directly on the node and bypasses the
362     * interceptor chain.
363     * <p/>
364     * The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a
365     * {@link org.jboss.cache.lock.LockingException} will be thrown.
366     * <p/>
367     *
368     * @return set of children names
369     * @see #getChildrenNames()
370     */
371    Set  <Object  > getChildrenNamesDirect();
372 
373    /**
374     * Retrieves a reference to the cache in which this Node resides.
375     *
376     * @return a cache
377     */
378    CacheSPI getCache();
379 
380    // ----------- these methods override their corresponding methods in Node, so that the return types are NodeSPI rather than Node.
381 
382    /**
383     * Overrides {@link #getParent()} in {@link Node} so it returns a {@link NodeSPI} instead.  Otherwise identical.
384     *
385     * @return parent node
386     * @see Node#getParent()
387     */
388    NodeSPI getParent();
389 }
390
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags