KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jboss > cache > 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 JavaDoc;
13 import java.util.Map JavaDoc;
14 import java.util.Set JavaDoc;
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 JavaDoc<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 JavaDoc<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 JavaDoc put(Fqn fqn, Object JavaDoc key, Object JavaDoc 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 JavaDoc key, Object JavaDoc 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 JavaDoc 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 JavaDoc remove(Fqn fqn, Object JavaDoc 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 JavaDoc get(Fqn fqn, Object JavaDoc 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 JavaDoc;
175
176    /**
177     * Lifecycle method
178     */

179    void start() throws Exception JavaDoc;
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 JavaDoc<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 JavaDoc getVersion();
267 }
268
Popular Tags