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  ;
16  import java.io.ObjectOutputStream  ;
17  import java.util.List  ;
18  import java.util.Map  ;
19  import java.util.Set  ;
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  <String  > getChildrenNames(Fqn fqn) throws Exception  ;
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  <Object  , Object  > get(Fqn name) throws Exception  ;
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  ;
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   put(Fqn name, Object   key, Object   value) throws Exception  ;
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  <Object  , Object  > attributes) throws Exception  ;
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  <Modification> modifications) throws Exception  ;
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   remove(Fqn fqn, Object   key) throws Exception  ;
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  ;
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  ;
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   tx, List  <Modification> modifications, boolean one_phase) throws Exception  ;
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   tx) throws Exception  ;
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   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   os) throws Exception  ;
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   is) throws Exception  ;
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   os) throws Exception  ;
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   is) throws Exception  ;
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  ;
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  ;
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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags