|
|||||||||||||||||||
Source file | Conditionals | Statements | Methods | TOTAL | |||||||||||||||
CacheLoader.java | - | - | - | - |
|
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 net.jcip.annotations.ThreadSafe; | |
10 | import org.jboss.cache.CacheSPI; | |
11 | import org.jboss.cache.Fqn; | |
12 | import org.jboss.cache.Modification; | |
13 | import org.jboss.cache.RegionManager; | |
14 | import org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig; | |
15 | ||
16 | import java.io.ObjectInputStream; | |
17 | import java.io.ObjectOutputStream; | |
18 | import java.util.List; | |
19 | import java.util.Map; | |
20 | import java.util.Set; | |
21 | ||
22 | /** | |
23 | * A {@link org.jboss.cache.loader.CacheLoader} implementation persists and load keys to and from | |
24 | * secondary storage, such as a database or filesystem. Typically, | |
25 | * implementations store a series of keys and values (an entire {@link Map}) | |
26 | * under a single {@link Fqn}. Loading and saving properties of an entire | |
27 | * {@link Map} should be atomic. | |
28 | * <p/> | |
29 | * Lifecycle: First an instance of the loader is created, then the | |
30 | * configuration ({@link #setConfig(org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig)}) and cache ({@link | |
31 | * #setCache(CacheSPI)}) are set. After this, {@link #create()} is called. | |
32 | * Then {@link #start()} is called. When re-deployed, {@link #stop()} will be | |
33 | * called, followed by another {@link #start()}. Finally, when shut down, | |
34 | * {@link #destroy()} is called, after which the loader is unusable. | |
35 | * <p/> | |
36 | * An {@link org.jboss.cache.loader.AbstractCacheLoader} is provided as a convenient starting place | |
37 | * when implementing your own {@link org.jboss.cache.loader.CacheLoader}. | |
38 | * <p/> | |
39 | * It is important to note that all implementations are thread safe, as concurrent reads and writes, potentially even to | |
40 | * the same {@link Fqn}, are possible. | |
41 | * <p/> | |
42 | * | |
43 | * @author <a href="mailto:manik@jboss.org">Manik Surtani (manik@jboss.org)</a> | |
44 | * @see CacheSPI | |
45 | * @see org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig | |
46 | * @see org.jboss.cache.loader.AbstractCacheLoader | |
47 | * @since 2.0.0 | |
48 | */ | |
49 | @ThreadSafe | |
50 | public interface CacheLoader | |
51 | { | |
52 | /** | |
53 | * Sets the configuration. This is called before {@link #create()} and {@link #start()}. | |
54 | * | |
55 | * @param config May be an instance of the {@link org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig} base | |
56 | * class, in which case the cache loader should use the | |
57 | * {@link org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig#getProperties()} | |
58 | * method to find configuration information. Alternatively, | |
59 | * may be a type-specific subclass of {@link org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig}, | |
60 | * if there is one. | |
61 | */ | |
62 | void setConfig(IndividualCacheLoaderConfig config); | |
63 | ||
64 | /** | |
65 | * Gets the configuration. | |
66 | * | |
67 | * @return the configuration, represented by a {@link org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig} object. | |
68 | */ | |
69 | IndividualCacheLoaderConfig getConfig(); | |
70 | ||
71 | /** | |
72 | * Sets the {@link CacheSPI} that is maintaining this CacheLoader. | |
73 | * This method allows this CacheLoader to set a reference to the {@link CacheSPI}. | |
74 | * This method is called be called after the CacheLoader instance has been constructed. | |
75 | * | |
76 | * @param c The cache on which this loader works | |
77 | */ | |
78 | void setCache(CacheSPI c); | |
79 | ||
80 | ||
81 | /** | |
82 | * Returns a set of children node names. | |
83 | * All names are <em>relative</em> to this parent {@link Fqn}. | |
84 | * Returns null if the named node is not found or there are no children. | |
85 | * The returned set must not be modifiable. Implementors can use | |
86 | * {@link java.util.Collections#unmodifiableSet(java.util.Set)} to make the set unmodifiable. | |
87 | * <p/> | |
88 | * Implementors may impose restrictions on the contents of an Fqn (such as Strings-only) and as such, indirectly | |
89 | * impose the same restriction on the contents of a Set returned by getChildrenNames(). | |
90 | * <p/> | |
91 | * | |
92 | * @param fqn The {@link Fqn} of the parent | |
93 | * @return Set a set of children. Returns null if no children nodes are | |
94 | * present, or the parent is not present | |
95 | */ | |
96 | Set<?> getChildrenNames(Fqn fqn) throws Exception; | |
97 | ||
98 | /** | |
99 | * Returns all keys and values from the persistent store, given a {@link org.jboss.cache.Fqn} | |
100 | * | |
101 | * @param name the {@link Fqn} to search for. | |
102 | * @return Map<Object,Object> keys and values for the given node. Returns | |
103 | * null if the node is not found. If the node is found but has no | |
104 | * attributes, this method returns an empty Map. | |
105 | */ | |
106 | Map<Object, Object> get(Fqn name) throws Exception; | |
107 | ||
108 | ||
109 | /** | |
110 | * Returns true if the CacheLoader has a node with a {@link Fqn}. | |
111 | * | |
112 | * @return true if node exists, false otherwise | |
113 | */ | |
114 | boolean exists(Fqn name) throws Exception; | |
115 | ||
116 | ||
117 | /** | |
118 | * Puts a key and value into the attribute map of a given node. If the | |
119 | * node does not exist, all parent nodes from the root down are created | |
120 | * automatically. Returns the old value. | |
121 | */ | |
122 | Object put(Fqn name, Object key, Object value) throws Exception; | |
123 | ||
124 | /** | |
125 | * Puts all entries of the map into the existing map of the given node, | |
126 | * overwriting existing keys, but not clearing the existing map before | |
127 | * insertion. | |
128 | * This is the same behavior as {@link Map#putAll}. | |
129 | * If the node does not exist, all parent nodes from the root down are created automatically | |
130 | * | |
131 | * @param name The fully qualified name of the node | |
132 | * @param attributes A Map of attributes. Can be null | |
133 | */ | |
134 | void put(Fqn name, Map<Object, Object> attributes) throws Exception; | |
135 | ||
136 | /** | |
137 | * Applies all modifications to the backend store. | |
138 | * Changes may be applied in a single operation. | |
139 | * | |
140 | * @param modifications A List<Modification> of modifications | |
141 | */ | |
142 | void put(List<Modification> modifications) throws Exception; | |
143 | ||
144 | /** | |
145 | * Removes the given key and value from the attributes of the given node. | |
146 | * Does nothing if the node doesn't exist | |
147 | * Returns the removed value. | |
148 | */ | |
149 | Object remove(Fqn fqn, Object key) throws Exception; | |
150 | ||
151 | /** | |
152 | * Removes the given node and all its subnodes, does nothing if the node does not exist. | |
153 | * | |
154 | * @param fqn the {@link Fqn} of the node | |
155 | */ | |
156 | void remove(Fqn fqn) throws Exception; | |
157 | ||
158 | ||
159 | /** | |
160 | * Removes all attributes from a given node, but doesn't delete the node | |
161 | * itself or any subnodes. | |
162 | * | |
163 | * @param fqn the {@link Fqn} of the node | |
164 | */ | |
165 | void removeData(Fqn fqn) throws Exception; | |
166 | ||
167 | ||
168 | /** | |
169 | * Prepares a list of modifications. For example, for a DB-based CacheLoader: | |
170 | * <ol> | |
171 | * <li>Create a local (JDBC) transaction | |
172 | * <li>Associate the local transaction with <code>tx</code> (tx is the key) | |
173 | * <li>Execute the corresponding SQL statements against the DB (statements derived from modifications) | |
174 | * </ol> | |
175 | * For non-transactional CacheLoader (e.g. file-based), the implementation could attempt to implement it's own transactional | |
176 | * logic, attempting to write data to a temp location (or memory) and writing it to the proper location upon commit. | |
177 | * | |
178 | * @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) | |
179 | * @param modifications A {@link List} containing {@link org.jboss.cache.Modification}s, for the given transaction | |
180 | * @param one_phase Persist immediately and (for example) commit the local JDBC transaction as well. When true, | |
181 | * we won't get a {@link #commit(Object)} or {@link #rollback(Object)} method call later | |
182 | * @throws Exception | |
183 | */ | |
184 | void prepare(Object tx, List<Modification> modifications, boolean one_phase) throws Exception; | |
185 | ||
186 | /** | |
187 | * Commits the transaction. A DB-based CacheLoader would look up the local | |
188 | * JDBC transaction asociated with <code>tx</code> and commit that | |
189 | * transaction. Non-transactional CacheLoaders could simply write the data | |
190 | * that was previously saved transiently under the given <code>tx</code> | |
191 | * key, to (for example) a file system. | |
192 | * <p/> | |
193 | * <b>Note</b> this only holds if the previous prepare() did not define <pre>one_phase=true</pre> | |
194 | * | |
195 | * @param tx transaction to commit | |
196 | */ | |
197 | void commit(Object tx) throws Exception; | |
198 | ||
199 | /** | |
200 | * Rolls the transaction back. A DB-based CacheLoader would look up the | |
201 | * local JDBC transaction asociated with <code>tx</code> and roll back that | |
202 | * transaction. | |
203 | * | |
204 | * @param tx transaction to roll back | |
205 | */ | |
206 | void rollback(Object tx); | |
207 | ||
208 | /** | |
209 | * Fetches the entire state for this cache from secondary storage (disk, database) | |
210 | * and writes it to a provided ObjectOutputStream. State written to the provided | |
211 | * ObjectOutputStream parameter is used for initialization of a new CacheImpl instance. | |
212 | * When the state gets transferred to the new cache instance its cacheloader calls | |
213 | * {@link #storeEntireState(ObjectInputStream)} | |
214 | * <p/> | |
215 | * Implementations of this method should not catch any exception or close the | |
216 | * given ObjectOutputStream parameter. In order to ensure cacheloader interoperability | |
217 | * contents of the cache are written to the ObjectOutputStream as a sequence of | |
218 | * NodeData objects. | |
219 | * <p/> | |
220 | * Default implementation is provided by {@link AbstractCacheLoader} and ensures cacheloader | |
221 | * interoperability. Implementors are encouraged to consider extending AbstractCacheLoader | |
222 | * prior to implementing completely custom cacheloader. | |
223 | * | |
224 | * @param os ObjectOutputStream to write state | |
225 | * @see AbstractCacheLoader#loadEntireState(ObjectOutputStream) | |
226 | * @see org.jboss.cache.marshall.NodeData | |
227 | */ | |
228 | void loadEntireState(ObjectOutputStream os) throws Exception; | |
229 | ||
230 | /** | |
231 | * Stores the entire state for this cache by reading it from a provided ObjectInputStream. | |
232 | * The state was provided to this cache by calling {@link #loadEntireState(ObjectOutputStream)}} | |
233 | * on some other cache instance. State currently in storage gets overwritten. | |
234 | * <p/> | |
235 | * Implementations of this method should not catch any exception or close the | |
236 | * given ObjectInputStream parameter. In order to ensure cacheloader interoperability | |
237 | * contents of the cache are read from the ObjectInputStream as a sequence of | |
238 | * NodeData objects. | |
239 | * <p/> | |
240 | * Default implementation is provided by {@link AbstractCacheLoader} and ensures cacheloader | |
241 | * interoperability. Implementors are encouraged to consider extending AbstractCacheLoader | |
242 | * prior to implementing completely custom cacheloader. | |
243 | * | |
244 | * @param is ObjectInputStream to read state | |
245 | * @see AbstractCacheLoader#storeEntireState(ObjectInputStream) | |
246 | * @see org.jboss.cache.marshall.NodeData | |
247 | */ | |
248 | void storeEntireState(ObjectInputStream is) throws Exception; | |
249 | ||
250 | /** | |
251 | * Fetches a portion of the state for this cache from secondary storage (disk, database) | |
252 | * and writes it to a provided ObjectOutputStream. State written to the provided | |
253 | * ObjectOutputStream parameter is used for activation of a portion of a new CacheImpl instance. | |
254 | * When the state gets transferred to the new cache instance its cacheloader calls | |
255 | * {@link #storeState(Fqn,ObjectInputStream)}. | |
256 | * <p/> | |
257 | * Implementations of this method should not catch any exception or close the | |
258 | * given ObjectOutputStream parameter. In order to ensure cacheloader interoperability | |
259 | * contents of the cache are written to the ObjectOutputStream as a sequence of | |
260 | * NodeData objects. | |
261 | * <p/> | |
262 | * Default implementation is provided by {@link AbstractCacheLoader} and ensures cacheloader | |
263 | * interoperability. Implementors are encouraged to consider extending AbstractCacheLoader | |
264 | * prior to implementing completely custom cacheloader. | |
265 | * | |
266 | * @param subtree Fqn naming the root (i.e. highest level parent) node of | |
267 | * the subtree for which state is requested. | |
268 | * @param os ObjectOutputStream to write state | |
269 | * @see AbstractCacheLoader#loadState(Fqn,ObjectOutputStream) | |
270 | * @see org.jboss.cache.Region#activate() | |
271 | * @see org.jboss.cache.marshall.NodeData | |
272 | */ | |
273 | void loadState(Fqn subtree, ObjectOutputStream os) throws Exception; | |
274 | ||
275 | /** | |
276 | * Stores the given portion of the cache tree's state in secondary storage. | |
277 | * Overwrite whatever is currently in secondary storage. If the transferred | |
278 | * state has Fqns equal to or children of parameter <code>subtree</code>, | |
279 | * then no special behavior is required. Otherwise, ensure that | |
280 | * the state is integrated under the given <code>subtree</code>. Typically | |
281 | * in the latter case <code>subtree</code> would be the Fqn of the buddy | |
282 | * backup region for | |
283 | * a buddy group; e.g. | |
284 | * <p/> | |
285 | * If the the transferred state had Fqns starting with "/a" and | |
286 | * <code>subtree</code> was "/_BUDDY_BACKUP_/192.168.1.2:5555" then the | |
287 | * state should be stored in the local persistent store under | |
288 | * "/_BUDDY_BACKUP_/192.168.1.2:5555/a" | |
289 | * <p/> | |
290 | * Implementations of this method should not catch any exception or close the | |
291 | * given ObjectInputStream parameter. In order to ensure cacheloader interoperability | |
292 | * contents of the cache are read from the ObjectInputStream as a sequence of | |
293 | * NodeData objects. | |
294 | * <p/> | |
295 | * Default implementation is provided by {@link AbstractCacheLoader} and ensures cacheloader | |
296 | * interoperability. Implementors are encouraged to consider extending AbstractCacheLoader | |
297 | * prior to implementing completely custom cacheloader. | |
298 | * | |
299 | * @param is ObjectInputStream to read state | |
300 | * @param subtree Fqn naming the root (i.e. highest level parent) node of | |
301 | * the subtree included in <code>state</code>. If the Fqns | |
302 | * of the data included in <code>state</code> are not | |
303 | * already children of <code>subtree</code>, then their | |
304 | * Fqns should be altered to make them children of | |
305 | * <code>subtree</code> before they are persisted. | |
306 | * @see AbstractCacheLoader#storeState(Fqn,ObjectInputStream) | |
307 | * @see org.jboss.cache.marshall.NodeData | |
308 | */ | |
309 | void storeState(Fqn subtree, ObjectInputStream is) throws Exception; | |
310 | ||
311 | /** | |
312 | * Sets the {@link org.jboss.cache.RegionManager} this object should use to manage | |
313 | * marshalling/unmarshalling of different regions using different | |
314 | * classloaders. | |
315 | * <p/> | |
316 | * <strong>NOTE:</strong> This method is only intended to be used | |
317 | * by the <code>CacheSPI</code> instance this cache loader is | |
318 | * associated with. | |
319 | * </p> | |
320 | * | |
321 | * @param manager the region manager to use, or <code>null</code>. | |
322 | */ | |
323 | void setRegionManager(RegionManager manager); | |
324 | ||
325 | /** | |
326 | * Lifecycle method, called when the cache loader is created. | |
327 | * | |
328 | * @throws java.lang.Exception | |
329 | */ | |
330 | void create() throws java.lang.Exception; | |
331 | ||
332 | /** | |
333 | * Lifecycle method, called when the cache loader is started. | |
334 | * | |
335 | * @throws java.lang.Exception | |
336 | */ | |
337 | void start() throws java.lang.Exception; | |
338 | ||
339 | /** | |
340 | * Lifecycle method, called when the cache loader is stopped. | |
341 | */ | |
342 | void stop(); | |
343 | ||
344 | /** | |
345 | * Lifecycle method, called when the cache loader is destroyed. | |
346 | */ | |
347 | void destroy(); | |
348 | ||
349 | } |
|