KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jboss > cache > loader > CacheLoader


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.loader;
8
9 import org.jboss.cache.CacheSPI;
10 import org.jboss.cache.Fqn;
11 import org.jboss.cache.Modification;
12 import org.jboss.cache.RegionManager;
13 import org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig;
14
15 import java.io.ObjectInputStream JavaDoc;
16 import java.io.ObjectOutputStream JavaDoc;
17 import java.util.List JavaDoc;
18 import java.util.Map JavaDoc;
19 import java.util.Set JavaDoc;
20
21 /**
22  * A <code>CacheLoader</code> implementation persists and load keys to and from
23  * secondary storage, such as a database or filesystem. Typically,
24  * implementations store a series of keys and values (an entire {@link Map})
25  * under a single {@link Fqn}. Loading and saving properties of an entire
26  * {@link Map} should be atomic.
27  * <p/>
28  * Lifecycle: First an instance of the loader is created, then the
29  * configuration ({@link #setConfig(IndividualCacheLoaderConfig)} ) and cache ({@link
30  * #setCache(CacheSPI)}) are set. After this, {@link #create()} is called.
31  * Then {@link #start()} is called. When re-deployed, {@link #stop()} will be
32  * called, followed by another {@link #start()}. Finally, when shut down,
33  * {@link #destroy()} is called, after which the loader is unusable.
34  *
35  * @author <a HREF="mailto:manik@jboss.org">Manik Surtani (manik@jboss.org)</a>
36  * @see CacheSPI
37  * @see org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig
38  * @since 2.0.0
39  */

40
41 public interface CacheLoader
42 {
43    /**
44     * Sets the configuration. This is called before {@link #create()} and {@link #start()}.
45     *
46     * @param config May be an instance of the {@link org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig} base
47     * class, in which case the cache loader should use the
48     * {@link org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig#getProperties()}
49     * method to find configuration information. Alternatively,
50     * may be a type-specific subclass of {@link org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig},
51     * if there is one.
52     */

53    void setConfig(IndividualCacheLoaderConfig config);
54
55    /**
56     * Gets the configuration.
57     *
58     * @return the configuration, represented by a {@link org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig} object.
59     */

60    IndividualCacheLoaderConfig getConfig();
61
62    /**
63     * Sets the {@link CacheSPI} that is maintaining this CacheLoader.
64     * This method allows this CacheLoader to set a reference to the {@link CacheSPI}.
65     * This method is called be called after the CacheLoader instance has been constructed.
66     *
67     * @param c The cache on which this loader works
68     */

69    void setCache(CacheSPI c);
70
71
72    /**
73     * Returns a set of children node names as Strings.
74     * All names are <em>relative</em> to this parent {@link Fqn}.
75     * Returns null if the named node is not found or there are no children.
76     * The returned set must not be modifiable. Implementors can use
77     * {@link java.util.Collections#unmodifiableSet(java.util.Set)} to make the set unmodifiable.
78     *
79     * @param fqn The {@link Fqn} of the parent
80     * @return Set a set of children. Returns null if no children nodes are
81     * present, or the parent is not present
82     */

83    Set JavaDoc<String JavaDoc> getChildrenNames(Fqn fqn) throws Exception JavaDoc;
84
85    /**
86     * Returns all keys and values from the persistent store, given a {@link org.jboss.cache.Fqn}
87     *
88     * @param name the {@link Fqn} to search for.
89     * @return Map<Object,Object> keys and values for the given node. Returns
90     * null if the node is not found. If the node is found but has no
91     * attributes, this method returns an empty Map.
92     */

93    Map JavaDoc<Object JavaDoc, Object JavaDoc> get(Fqn name) throws Exception JavaDoc;
94
95
96    /**
97     * Returns true if the CacheLoader has a node with a {@link Fqn}.
98     *
99     * @return true if node exists, false otherwise
100     */

101    boolean exists(Fqn name) throws Exception JavaDoc;
102
103
104    /**
105     * Puts a key and value into the attribute map of a given node. If the
106     * node does not exist, all parent nodes from the root down are created
107     * automatically. Returns the old value.
108     */

109    Object JavaDoc put(Fqn name, Object JavaDoc key, Object JavaDoc value) throws Exception JavaDoc;
110
111    /**
112     * Puts all entries of the map into the existing map of the given node,
113     * overwriting existing keys, but not clearing the existing map before
114     * insertion.
115     * This is the same behavior as {@link Map#putAll}.
116     * If the node does not exist, all parent nodes from the root down are created automatically
117     *
118     * @param name The fully qualified name of the node
119     * @param attributes A Map of attributes. Can be null
120     */

121    void put(Fqn name, Map JavaDoc<Object JavaDoc, Object JavaDoc> attributes) throws Exception JavaDoc;
122
123    /**
124     * Applies all modifications to the backend store.
125     * Changes may be applied in a single operation.
126     *
127     * @param modifications A List<Modification> of modifications
128     */

129    void put(List JavaDoc<Modification> modifications) throws Exception JavaDoc;
130
131    /**
132     * Removes the given key and value from the attributes of the given node.
133     * Does nothing if the node doesn't exist
134     * Returns the removed value.
135     */

136    Object JavaDoc remove(Fqn fqn, Object JavaDoc key) throws Exception JavaDoc;
137
138    /**
139     * Removes the given node and all its subnodes, does nothing if the node does not exist.
140     *
141     * @param fqn the {@link Fqn} of the node
142     */

143    void remove(Fqn fqn) throws Exception JavaDoc;
144
145
146    /**
147     * Removes all attributes from a given node, but doesn't delete the node
148     * itself or any subnodes.
149     *
150     * @param fqn the {@link Fqn} of the node
151     */

152    void removeData(Fqn fqn) throws Exception JavaDoc;
153
154
155    /**
156     * Prepares a list of modifications. For example, for a DB-based CacheLoader:
157     * <ol>
158     * <li>Create a local (JDBC) transaction
159     * <li>Associate the local transaction with <code>tx</code> (tx is the key)
160     * <li>Execute the corresponding SQL statements against the DB (statements derived from modifications)
161     * </ol>
162     * For non-transactional CacheLoader (e.g. file-based), the implementation could attempt to implement it's own transactional
163     * logic, attempting to write data to a temp location (or memory) and writing it to the proper location upon commit.
164     *
165     * @param tx The transaction, indended to be used by implementations as an identifier of the transaction (and not necessarily a JTA {@link javax.transaction.Transaction} object)
166     * @param modifications A {@link List} containing {@link org.jboss.cache.Modification}s, for the given transaction
167     * @param one_phase Persist immediately and (for example) commit the local JDBC transaction as well. When true,
168     * we won't get a {@link #commit(Object)} or {@link #rollback(Object)} method call later
169     * @throws Exception
170     */

171    void prepare(Object JavaDoc tx, List JavaDoc<Modification> modifications, boolean one_phase) throws Exception JavaDoc;
172
173    /**
174     * Commits the transaction. A DB-based CacheLoader would look up the local
175     * JDBC transaction asociated with <code>tx</code> and commit that
176     * transaction. Non-transactional CacheLoaders could simply write the data
177     * that was previously saved transiently under the given <code>tx</code>
178     * key, to (for example) a file system.
179     * <p/>
180     * <b>Note</b> this only holds if the previous prepare() did not define <pre>one_phase=true</pre>
181     *
182     * @param tx transaction to commit
183     */

184    void commit(Object JavaDoc tx) throws Exception JavaDoc;
185
186    /**
187     * Rolls the transaction back. A DB-based CacheLoader would look up the
188     * local JDBC transaction asociated with <code>tx</code> and roll back that
189     * transaction.
190     *
191     * @param tx transaction to roll back
192     */

193    void rollback(Object JavaDoc tx);
194
195    /**
196     * Fetches the entire state for this cache from secondary storage (disk, database)
197     * and writes it to a provided ObjectOutputStream. State written to the provided
198     * ObjectOutputStream parameter is used for initialization of a new CacheImpl instance.
199     * When the state gets transferred to the new cache instance its cacheloader calls
200     * {@link #storeEntireState(ObjectInputStream)}
201     * <p/>
202     * Implementations of this method should not catch any exception or close the
203     * given ObjectOutputStream parameter. In order to ensure cacheloader interoperability
204     * contents of the cache are written to the ObjectOutputStream as a sequence of
205     * NodeData objects.
206     * <p/>
207     * Default implementation is provided by {@link AbstractCacheLoader} and ensures cacheloader
208     * interoperability. Implementors are encouraged to consider extending AbstractCacheLoader
209     * prior to implementing completely custom cacheloader.
210     *
211     * @param os ObjectOutputStream to write state
212     * @see AbstractCacheLoader#loadEntireState(ObjectOutputStream)
213     * @see NodeData
214     */

215    void loadEntireState(ObjectOutputStream JavaDoc os) throws Exception JavaDoc;
216
217    /**
218     * Stores the entire state for this cache by reading it from a provided ObjectInputStream.
219     * The state was provided to this cache by calling {@link #loadEntireState(ObjectOutputStream)}}
220     * on some other cache instance. State currently in storage gets overwritten.
221     * <p/>
222     * Implementations of this method should not catch any exception or close the
223     * given ObjectInputStream parameter. In order to ensure cacheloader interoperability
224     * contents of the cache are read from the ObjectInputStream as a sequence of
225     * NodeData objects.
226     * <p/>
227     * Default implementation is provided by {@link AbstractCacheLoader} and ensures cacheloader
228     * interoperability. Implementors are encouraged to consider extending AbstractCacheLoader
229     * prior to implementing completely custom cacheloader.
230     *
231     * @param is ObjectInputStream to read state
232     * @see AbstractCacheLoader#storeEntireState(ObjectInputStream)
233     * @see NodeData
234     */

235    void storeEntireState(ObjectInputStream JavaDoc is) throws Exception JavaDoc;
236
237    /**
238     * Fetches a portion of the state for this cache from secondary storage (disk, database)
239     * and writes it to a provided ObjectOutputStream. State written to the provided
240     * ObjectOutputStream parameter is used for activation of a portion of a new CacheImpl instance.
241     * When the state gets transferred to the new cache instance its cacheloader calls
242     * {@link #storeState(Fqn,ObjectInputStream)}.
243     * <p/>
244     * Implementations of this method should not catch any exception or close the
245     * given ObjectOutputStream parameter. In order to ensure cacheloader interoperability
246     * contents of the cache are written to the ObjectOutputStream as a sequence of
247     * NodeData objects.
248     * <p/>
249     * Default implementation is provided by {@link AbstractCacheLoader} and ensures cacheloader
250     * interoperability. Implementors are encouraged to consider extending AbstractCacheLoader
251     * prior to implementing completely custom cacheloader.
252     *
253     * @param subtree Fqn naming the root (i.e. highest level parent) node of
254     * the subtree for which state is requested.
255     * @param os ObjectOutputStream to write state
256     * @see AbstractCacheLoader#loadState(Fqn,ObjectOutputStream)
257     * @see org.jboss.cache.Region#activate()
258     * @see NodeData
259     */

260    void loadState(Fqn subtree, ObjectOutputStream JavaDoc os) throws Exception JavaDoc;
261
262    /**
263     * Stores the given portion of the cache tree's state in secondary storage.
264     * Overwrite whatever is currently in secondary storage. If the transferred
265     * state has Fqns equal to or children of parameter <code>subtree</code>,
266     * then no special behavior is required. Otherwise, ensure that
267     * the state is integrated under the given <code>subtree</code>. Typically
268     * in the latter case <code>subtree</code> would be the Fqn of the buddy
269     * backup region for
270     * a buddy group; e.g.
271     * <p/>
272     * If the the transferred state had Fqns starting with "/a" and
273     * <code>subtree</code> was "/_BUDDY_BACKUP_/192.168.1.2:5555" then the
274     * state should be stored in the local persistent store under
275     * "/_BUDDY_BACKUP_/192.168.1.2:5555/a"
276     * <p/>
277     * Implementations of this method should not catch any exception or close the
278     * given ObjectInputStream parameter. In order to ensure cacheloader interoperability
279     * contents of the cache are read from the ObjectInputStream as a sequence of
280     * NodeData objects.
281     * <p/>
282     * Default implementation is provided by {@link AbstractCacheLoader} and ensures cacheloader
283     * interoperability. Implementors are encouraged to consider extending AbstractCacheLoader
284     * prior to implementing completely custom cacheloader.
285     *
286     * @param is ObjectInputStream to read state
287     * @param subtree Fqn naming the root (i.e. highest level parent) node of
288     * the subtree included in <code>state</code>. If the Fqns
289     * of the data included in <code>state</code> are not
290     * already children of <code>subtree</code>, then their
291     * Fqns should be altered to make them children of
292     * <code>subtree</code> before they are persisted.
293     * @see AbstractCacheLoader#storeState(Fqn,ObjectInputStream)
294     * @see NodeData
295     */

296    void storeState(Fqn subtree, ObjectInputStream JavaDoc is) throws Exception JavaDoc;
297
298    /**
299     * Sets the {@link org.jboss.cache.RegionManager} this object should use to manage
300     * marshalling/unmarshalling of different regions using different
301     * classloaders.
302     * <p/>
303     * <strong>NOTE:</strong> This method is only intended to be used
304     * by the <code>CacheSPI</code> instance this cache loader is
305     * associated with.
306     * </p>
307     *
308     * @param manager the region manager to use, or <code>null</code>.
309     */

310    void setRegionManager(RegionManager manager);
311
312    /**
313     * Lifecycle method, called when the cache loader is created.
314     *
315     * @throws java.lang.Exception
316     */

317    void create() throws java.lang.Exception JavaDoc;
318
319    /**
320     * Lifecycle method, called when the cache loader is started.
321     *
322     * @throws java.lang.Exception
323     */

324    void start() throws java.lang.Exception JavaDoc;
325
326    /**
327     * Lifecycle method, called when the cache loader is stopped.
328     */

329    void stop();
330
331    /**
332     * Lifecycle method, called when the cache loader is destroyed.
333     */

334    void destroy();
335
336 }
337
Popular Tags