Cache


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.config.Configuration;
10  import org.jgroups.Address;
11  
12  import java.util.List  ;
13  import java.util.Map  ;
14  import java.util.Set  ;
15  
16  /**
17   * Along with {@link Node}, this is the central construct and basic client API of JBoss Cache and is used for
18   * cache-wide operations.
19   * <p/>
20   * The cache is constructed using a {@link org.jboss.cache.factories.CacheFactory}.
21   * <p/>
22   *
23   * @author <a HREF="mailto:manik@jboss.org">Manik Surtani (manik@jboss.org)</a>
24   * @see Node
25   * @see org.jboss.cache.factories.CacheFactory
26   * @since 2.0.0
27   */
28  public interface Cache
29  {
30     /**
31      * Retrieves the configuration of this cache.
32      *
33      * @return the configuration.
34      */
35     Configuration getConfiguration();
36  
37     /**
38      * Convenience method to return the default root as a {@link Node}.  The default root, represented by this
39      * {@link Cache} instance, is a {@link Node} anyway though.
40      *
41      * @return the current {@link Cache} instance, as a {@link Node}
42      */
43     Node getRoot();
44  
45     /**
46      * Adds a {@link CacheListener} to the entire cache
47      *
48      * @param l listener to add
49      */
50     void addCacheListener(CacheListener l);
51  
52     /**
53      * Adds a {@link CacheListener} to a given region.
54      *
55      * @param region
56      * @param l
57      */
58     void addCacheListener(Fqn region, CacheListener l);
59  
60     /**
61      * Removes a {@link CacheListener} from the cache
62      *
63      * @param l listener to remove
64      */
65     void removeCacheListener(CacheListener l);
66  
67     /**
68      * Removes a {@link CacheListener} from a given region.
69      *
70      * @param region
71      * @param l
72      */
73     void removeCacheListener(Fqn region, CacheListener l);
74  
75     /**
76      * Retrieves an immutable {@link List} of {@link CacheListener}s attached to the cache.
77      *
78      * @return an immutable {@link List} of {@link CacheListener}s attached to the cache.
79      */
80     Set  <CacheListener> getCacheListeners();
81  
82     /**
83      * Retrieves an immutable {@link List} of {@link CacheListener}s attached to a specific region.
84      *
85      * @return an immutable {@link List} of {@link CacheListener}s attached to a specific region.
86      */
87     Set  <CacheListener> getCacheListeners(Fqn region);
88  
89     /**
90      * Convenience method that allows for direct access to the data in a {@link Node}.
91      *
92      * @param fqn   <b><i>absolute</i></b> {@link Fqn} to the {@link Node} to be accessed.
93      * @param key
94      * @param value
95      * @return Returns the old value contained under this key.  Null if key doesn't exist.
96      */
97     Object   put(Fqn fqn, Object   key, Object   value);
98  
99     /**
100     * For use cases that have an external representation and storage of data objects, doing a put() in the cache
101     * should not have as strong a set of semantics as though when the cache is in itself the main form of storing data.
102     * <p/>
103     * In these cases, a putForExternalRead() should be used instead of a put() - the key differences being:
104     * <p/>
105     * <ul>
106     * <li> Ongoing transactions are suspended before this call, so failures here will not affect any ongoing transactions.</li>
107     * <li> Errors and exceptions are 'silent' - logged at a muhc lower level than normal, and this method does not throw exceptions</li>
108     * <li> Lock acquisition timeouts are dropped to 0 to improve performance</li>
109     * <li> If pessimistic locking is used, write locks are not obtained here - even though this is a write.  Instead, read locks are used.<li>
110     * </ul>
111     *
112     * @param fqn
113     * @param key
114     * @param value
115     */
116    void putForExternalRead(Fqn fqn, Object   key, Object   value);
117 
118    /**
119     * Convenience method that allows for direct access to the data in a {@link Node}.
120     *
121     * @param fqn
122     * @param data
123     */
124    void put(Fqn fqn, Map   data);
125 
126    /**
127     * Convenience method that allows for direct access to the data in a {@link Node}.
128     *
129     * @param fqn <b><i>absolute</i></b> {@link Fqn} to the {@link Node} to be accessed.
130     * @param key
131     * @return Returns the old value contained under this key.  Null if key doesn't exist.
132     */
133    Object   remove(Fqn fqn, Object   key);
134 
135    /**
136     * Removes a node based on the (absolute) Fqn passed in.
137     */
138    void removeNode(Fqn fqn);
139 
140    /**
141     * Convenience method that allows for direct access to the data in a {@link Node}.
142     *
143     * @param fqn <b><i>absolute</i></b> {@link Fqn} to the {@link Node} to be accessed.
144     * @param key
145     */
146    Object   get(Fqn fqn, Object   key);
147 
148    /**
149     * Eviction call that evicts the specified {@link Node} from memory.
150     *
151     * @param fqn       <b><i>absolute</i></b> {@link Fqn} to the {@link Node} to be evicted.
152     * @param recursive evicts children as well
153     */
154    void evict(Fqn fqn, boolean recursive);
155 
156    /**
157     * Retrieves a {@link Region} for a given {@link Fqn}.  If the region does not exist,
158     * and <li>createIfAbsent</li> is true, then one is created.
159     * <p/>
160     * If not, parent Fqns will be consulted in turn for registered regions, gradually working up to
161     * Fqn.ROOT.  If no regions are defined in any of the parents either, a null is returned.
162     *
163     * @param fqn            Fqn that is contained in a region.
164     * @param createIfAbsent If true, will create a new associated region if not found.
165     * @return a MarshRegion. Null if none is found.
166     * @throws UnsupportedOperationException if the region cannot be defined.
167     * @see Region
168     */
169    Region getRegion(Fqn fqn, boolean createIfAbsent);
170 
171    /**
172     * Lifecycle method
173     */
174    void create() throws Exception  ;
175 
176    /**
177     * Lifecycle method
178     */
179    void start() throws Exception  ;
180 
181    /**
182     * Lifecycle method
183     */
184    void stop();
185 
186    /**
187     * Lifecycle method
188     */
189    void destroy();
190 
191    /**
192     * Retrieves the current invocation context for the current invocation and cache instance.
193     *
194     * @see org.jboss.cache.InvocationContext
195     */
196    InvocationContext getInvocationContext();
197 
198    /**
199     * Sets the passed in {@link org.jboss.cache.InvocationContext} as current.
200     *
201     * @param ctx
202     */
203    void setInvocationContext(InvocationContext ctx);
204 
205    /**
206     * @return the local address of this cache in a cluster.  Null if running in local mode.
207     */
208    Address getLocalAddress();
209 
210    /**
211     * @return a {@link List} of members in the cluster.  Null if running in local mode.
212     */
213    List  <Address> getMembers();
214 
215    /**
216     * Moves a part of the cache to a different subtree.
217     * <p/>
218     * E.g.:
219     * <p/>
220     * assume a cache structure such as:
221     * <p/>
222     * <pre>
223     *  /a/b/c
224     *  /a/b/d
225     *  /a/b/e
226     * <p/>
227     * <p/>
228     *  Fqn f1 = Fqn.fromString("/a/b/c");
229     *  Fqn f2 = Fqn.fromString("/a/b/d");
230     * <p/>
231     *  cache.move(f1, f2);
232     * </pre>
233     * <p/>
234     * Will result in:
235     * <pre>
236     * <p/>
237     * /a/b/d/c
238     * /a/b/e
239     * <p/>
240     * </pre>
241     * <p/>
242     * and now
243     * <p/>
244     * <pre>
245     *  Fqn f3 = Fqn.fromString("/a/b/e");
246     *  Fqn f4 = Fqn.fromString("/a");
247     *  cache.move(f3, f4);
248     * </pre>
249     * <p/>
250     * will result in:
251     * <pre>
252     * /a/b/d/c
253     * /a/e
254     * </pre>
255     * No-op if the node to be moved is the root node.
256     *
257     * @param nodeToMove the Fqn of the node to move.
258     * @param newParent  new location under which to attach the node being moved.
259     * @throws NodeNotExistsException may throw one of these if the target node does not exist or if a different thread has moved this node elsewhere already.
260     */
261    void move(Fqn nodeToMove, Fqn newParent) throws NodeNotExistsException;
262 
263    /**
264     * @return the version string of the cache.
265     */
266    String   getVersion();
267 }
268
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags