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.store;
18
19 import net.sf.ehcache.CacheException;
20 import net.sf.ehcache.Element;
21 import net.sf.ehcache.Status;
22 import net.sf.ehcache.writer.CacheWriterManager;
23
24 import java.io.IOException;
25
26 /***
27 * This is the interface for all stores. A store is a physical counterpart to a cache, which
28 * is a logical concept.
29 *
30 * @author Greg Luck
31 * @version $Id: Store.java 2269 2010-04-16 21:30:10Z gkeim $
32 */
33 public interface Store {
34
35 /***
36 * clusterCoherent property
37 */
38 static final String CLUSTER_COHERENT = "ClusterCoherent";
39
40
41 /***
42 * nodeCoherent property
43 */
44 static final String NODE_COHERENT = "NodeCoherent";
45
46 /***
47 * Add a listener to the store.
48 * @param listener
49 */
50 void addStoreListener(StoreListener listener);
51
52 /***
53 * Remove listener from store.
54 * @param listener
55 */
56 void removeStoreListener(StoreListener listener);
57
58 /***
59 * Puts an item into the store.
60 * @return true if this is a new put for the key or element is null. Returns false if it was an update.
61 */
62 boolean put(Element element) throws CacheException;
63
64 /***
65 * Puts an item into the store and the cache writer manager in an atomic operation
66 * @return true if this is a new put for the key or element is null. Returns false if it was an update.
67 */
68 boolean putWithWriter(Element element, CacheWriterManager writerManager) throws CacheException;
69
70 /***
71 * Gets an item from the cache.
72 */
73 Element get(Object key);
74
75 /***
76 * Gets an {@link Element} from the Store, without updating statistics
77 *
78 * @return The element
79 */
80 Element getQuiet(Object key);
81
82 /***
83 * Gets an Array of the keys for all elements in the disk store.
84 *
85 * @return An Object[] of {@link java.io.Serializable} keys
86 */
87 Object[] getKeyArray();
88
89 /***
90 * Removes an item from the cache.
91 *
92 * @since signature changed in 1.2 from boolean to Element to support notifications
93 */
94 Element remove(Object key);
95
96 /***
97 * Removes an item from the store and the cache writer manager in an atomic operation.
98 */
99 Element removeWithWriter(Object key, CacheWriterManager writerManager) throws CacheException;
100
101 /***
102 * Remove all of the elements from the store.
103 * <p/>
104 * If there are registered <code>CacheEventListener</code>s they are notified of the expiry or removal
105 * of the <code>Element</code> as each is removed.
106 */
107 void removeAll() throws CacheException;
108
109 /***
110 * Put an element in the store if no element is currently mapped to the elements key.
111 *
112 * @param element element to be added
113 * @return the element previously cached for this key, or null if none.
114 *
115 * @throws NullPointerException if the element is null, or has a null key
116 */
117 Element putIfAbsent(Element element) throws NullPointerException;
118
119 /***
120 * Remove the Element mapped to the key for the supplied element if the value of the supplied Element
121 * is equal to the value of the cached Element.
122 *
123 * @param element Element to be removed
124 * @return the Element removed or null if no Element was removed
125 *
126 * @throws NullPointerException if the element is null, or has a null key
127 */
128 Element removeElement(Element element) throws NullPointerException;
129
130 /***
131 * Replace the cached element only if the value of the current Element is equal to the value of the
132 * supplied old Element.
133 *
134 * @param old Element to be test against
135 * @param element Element to be cached
136 * @return true is the Element was replaced
137 * @throws NullPointerException if the either Element is null or has a null key
138 * @throws IllegalArgumentException if the two Element keys are non-null but not equal
139 */
140 boolean replace(Element old, Element element) throws NullPointerException, IllegalArgumentException;
141
142 /***
143 * Replace the cached element only if an Element is currently cached for this key
144 * @param element Element to be cached
145 * @return the Element previously cached for this key, or null if no Element was cached
146 * @throws NullPointerException if the Element is null or has a null key
147 */
148 Element replace(Element element) throws NullPointerException;
149
150 /***
151 * Prepares for shutdown.
152 */
153 void dispose();
154
155 /***
156 * Returns the current local store size
157 * @return the count of the Elements in the Store on the local machine
158 */
159 int getSize();
160
161 /***
162 * Returns the current local in-memory store size
163 * @return the count of the Elements in the Store and in-memory on the local machine
164 */
165 int getInMemorySize();
166
167 /***
168 * Returns the current local on-disk store size
169 * @return the count of the Elements in the Store and on-disk on the local machine
170 */
171 int getOnDiskSize();
172
173 /***
174 * Returns the current Terracotta clustered store size
175 * @return the count of the Elements in the Store across the cluster
176 */
177 int getTerracottaClusteredSize();
178
179 /***
180 * Gets the size of the in-memory portion of the store, in bytes.
181 * <p/>
182 * This method may be expensive to run, depending on implementation. Implementers may choose to return
183 * an approximate size.
184 *
185 * @return the approximate in-memory size of the store in bytes
186 */
187 long getInMemorySizeInBytes();
188
189 /***
190 * Gets the size of the on-disk portion of the store, in bytes.
191 *
192 * @return the on-disk size of the store in bytes
193 */
194 long getOnDiskSizeInBytes();
195
196 /***
197 * Returns the cache status.
198 */
199 Status getStatus();
200
201
202 /***
203 * A check to see if a key is in the Store.
204 *
205 * @param key The Element key
206 * @return true if found. No check is made to see if the Element is expired.
207 * 1.2
208 */
209 boolean containsKey(Object key);
210
211 /***
212 * A check to see if a key is in the Store and is currently held on disk.
213 *
214 * @param key The Element key
215 * @return true if found. No check is made to see if the Element is expired.
216 */
217 boolean containsKeyOnDisk(Object key);
218
219 /***
220 * A check to see if a key is in the Store and is currently held in memory.
221 *
222 * @param key The Element key
223 * @return true if found. No check is made to see if the Element is expired.
224 */
225 boolean containsKeyInMemory(Object key);
226
227 /***
228 * Expire all elements.
229 */
230 public void expireElements();
231
232 /***
233 * Flush elements to persistent store.
234 * @throws IOException if any IO error occurs
235 */
236 void flush() throws IOException;
237
238 /***
239 * Some store types, such as the disk stores can fill their write buffers if puts
240 * come in too fast. The thread will wait for a short time before checking again.
241 * @return true if the store write buffer is backed up.
242 */
243 boolean bufferFull();
244
245 /***
246 * @return the current eviction policy. This may not be the configured policy, if it has been
247 * dynamically set.
248 * @see #setInMemoryEvictionPolicy(Policy)
249 */
250 Policy getInMemoryEvictionPolicy();
251
252 /***
253 * Sets the eviction policy strategy. The Store will use a policy at startup. The store may allow changing
254 * the eviction policy strategy dynamically. Otherwise implementations will throw an exception if this method
255 * is called.
256 *
257 * @param policy the new policy
258 */
259 void setInMemoryEvictionPolicy(Policy policy);
260
261 /***
262 * This should not be used, and will generally return null
263 * @return some internal context (probably null)
264 */
265 Object getInternalContext();
266
267 /***
268 * Indicates whether this store provides a coherent view of all the elements
269 * in a cache.
270 *
271 * Note that this is same as calling {@link #isClusterCoherent()} (introduced since 2.0)
272 * Use {@link #isNodeCoherent()} to find out if the cache is coherent in the current node in the cluster
273 *
274 * @return {@code true} if the store is coherent; or {@code false} if the
275 * store potentially splits the cache storage with another store or
276 * isn't internally coherent
277 * @since 1.7
278 */
279 boolean isCacheCoherent();
280
281 /***
282 * Returns true if the cache is in coherent mode cluster-wide. Returns false otherwise.
283 * <p />
284 * It applies to coherent clustering mechanisms only e.g. Terracotta
285 *
286 * @return true if the cache is in coherent mode cluster-wide, false otherwise
287 * @since 2.0
288 */
289 public boolean isClusterCoherent();
290
291 /***
292 * Returns true if the cache is in coherent mode for the current node. Returns false otherwise.
293 * <p />
294 * It applies to coherent clustering mechanisms only e.g. Terracotta
295 *
296 * @return true if the cache is in coherent mode cluster-wide, false otherwise
297 * @since 2.0
298 */
299 public boolean isNodeCoherent();
300
301 /***
302 * Sets the cache in coherent or incoherent mode for the current node depending on the parameter.
303 * Calling {@code setNodeCoherent(true)} when the cache is already in coherent mode or
304 * calling {@code setNodeCoherent(false)} when already in incoherent mode will be a no-op.
305 * <p />
306 * It applies to coherent clustering mechanisms only e.g. Terracotta
307 *
308 * @param coherent
309 * true transitions to coherent mode, false to incoherent mode
310 * @throws UnsupportedOperationException if this store does not support cache coherence, like RMI replication
311 * @since 2.0
312 */
313 public void setNodeCoherent(boolean coherent) throws UnsupportedOperationException;
314
315 /***
316 * This method waits until the cache is in coherent mode in all the connected nodes. If the cache is already in coherent mode it returns
317 * immediately
318 * <p />
319 * It applies to coherent clustering mechanisms only e.g. Terracotta
320 * @throws UnsupportedOperationException if this store does not support cache coherence, like RMI replication
321 * @since 2.0
322 */
323 public void waitUntilClusterCoherent() throws UnsupportedOperationException;
324 }