1 /***
2 * Copyright 2003-2010 Terracotta, Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package net.sf.ehcache.loader;
18
19 import net.sf.ehcache.CacheException;
20 import net.sf.ehcache.Ehcache;
21 import net.sf.ehcache.Status;
22
23 import java.util.Collection;
24 import java.util.Map;
25
26 /***
27 * Extends JCache CacheLoader with load methods that take an argument in addition to a key
28 *
29 * This interface has exactly the same interface as in the JCache module.
30 *
31 * @author Greg Luck
32 * @version $Id: CacheLoader.html 13146 2011-08-01 17:12:39Z oletizi $
33 */
34 public interface CacheLoader {
35
36
37 /***
38 * loads an object. Application writers should implement this
39 * method to customize the loading of cache object. This method is called
40 * by the caching service when the requested object is not in the cache.
41 * <P>
42 *
43 * @param key the key identifying the object being loaded
44 *
45 * @return The object that is to be stored in the cache.
46 * @throws CacheException
47 *
48 */
49 public Object load(Object key) throws CacheException;
50
51 /***
52 * loads multiple object. Application writers should implement this
53 * method to customize the loading of cache object. This method is called
54 * by the caching service when the requested object is not in the cache.
55 * <P>
56 *
57 * @param keys a Collection of keys identifying the objects to be loaded
58 *
59 * @return A Map of objects that are to be stored in the cache.
60 * @throws CacheException
61 *
62 */
63 public Map loadAll(Collection keys);
64
65
66 /***
67 * Load using both a key and an argument.
68 * <p/>
69 * JCache will call through to the load(key) method, rather than this method, where the argument is null.
70 *
71 * @param key the key to load the object for
72 * @param argument can be anything that makes sense to the loader
73 * @return the Object loaded
74 * @throws CacheException
75 */
76 Object load(Object key, Object argument);
77
78 /***
79 * Load using both a key and an argument.
80 * <p/>
81 * JCache will use the loadAll(key) method where the argument is null.
82 *
83 * @param keys the keys to load objects for
84 * @param argument can be anything that makes sense to the loader
85 * @return a map of Objects keyed by the collection of keys passed in.
86 * @throws CacheException
87 */
88 Map loadAll(Collection keys, Object argument);
89
90 /***
91 * Gets the name of a CacheLoader
92 *
93 * @return the name of this CacheLoader
94 */
95 String getName();
96
97 /***
98 * Creates a clone of this extension. This method will only be called by ehcache before a
99 * cache is initialized.
100 * <p/>
101 * Implementations should throw CloneNotSupportedException if they do not support clone
102 * but that will stop them from being used with defaultCache.
103 *
104 * @return a clone
105 * @throws CloneNotSupportedException if the extension could not be cloned.
106 */
107 public CacheLoader clone(Ehcache cache) throws CloneNotSupportedException;
108
109
110 /***
111 * Notifies providers to initialise themselves.
112 * <p/>
113 * This method is called during the Cache's initialise method after it has changed it's
114 * status to alive. Cache operations are legal in this method.
115 *
116 * @throws net.sf.ehcache.CacheException
117 */
118 void init();
119
120 /***
121 * Providers may be doing all sorts of exotic things and need to be able to clean up on
122 * dispose.
123 * <p/>
124 * Cache operations are illegal when this method is called. The cache itself is partly
125 * disposed when this method is called.
126 *
127 * @throws net.sf.ehcache.CacheException
128 */
129 void dispose() throws net.sf.ehcache.CacheException;
130
131
132 /***
133 * @return the status of the extension
134 */
135 public Status getStatus();
136 }