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.search.Attribute;
23 import net.sf.ehcache.search.Results;
24 import net.sf.ehcache.search.SearchException;
25 import net.sf.ehcache.search.attribute.AttributeExtractor;
26 import net.sf.ehcache.terracotta.TerracottaNotRunningException;
27 import net.sf.ehcache.writer.CacheWriterManager;
28
29 import java.io.IOException;
30 import java.util.Collection;
31 import java.util.List;
32 import java.util.Map;
33
34 /***
35 * This is the interface for all stores. A store is a physical counterpart to a cache, which
36 * is a logical concept.
37 *
38 * @author Greg Luck
39 * @version $Id: Store.html 13146 2011-08-01 17:12:39Z oletizi $
40 */
41 public interface Store {
42
43 /***
44 * clusterCoherent property
45 */
46 static final String CLUSTER_COHERENT = "ClusterCoherent";
47
48
49 /***
50 * nodeCoherent property
51 */
52 static final String NODE_COHERENT = "NodeCoherent";
53
54 /***
55 * Add a listener to the store.
56 * @param listener
57 */
58 void addStoreListener(StoreListener listener);
59
60 /***
61 * Remove listener from store.
62 * @param listener
63 */
64 void removeStoreListener(StoreListener listener);
65
66 /***
67 * Puts an item into the store.
68 * @return true if this is a new put for the key or element is null. Returns false if it was an update.
69 */
70 boolean put(Element element) throws CacheException;
71
72 /***
73 * Puts a collection of elements into the store.
74 * @param elements Collection of elements to be put in the store
75 */
76 void putAll(Collection<Element> elements) throws CacheException;
77
78 /***
79 * Puts an item into the store and the cache writer manager in an atomic operation
80 * @return true if this is a new put for the key or element is null. Returns false if it was an update.
81 */
82 boolean putWithWriter(Element element, CacheWriterManager writerManager) throws CacheException;
83
84 /***
85 * Gets an item from the cache.
86 */
87 Element get(Object key);
88
89 /***
90 * Gets an {@link Element} from the Store, without updating statistics
91 *
92 * @return The element
93 */
94 Element getQuiet(Object key);
95
96 /***
97 * Gets an Array of the keys for all elements in the disk store.
98 *
99 * @return An List of {@link java.io.Serializable} keys
100 */
101 List getKeys();
102
103 /***
104 * Removes an item from the cache.
105 *
106 * @since signature changed in 1.2 from boolean to Element to support notifications
107 */
108 Element remove(Object key);
109
110 /***
111 * Removes a collection of elements from the cache.
112 */
113 void removeAll(Collection<Object> keys);
114
115 /***
116 * Removes an item from the store and the cache writer manager in an atomic operation.
117 */
118 Element removeWithWriter(Object key, CacheWriterManager writerManager) throws CacheException;
119
120 /***
121 * Remove all of the elements from the store.
122 * <p/>
123 * If there are registered <code>CacheEventListener</code>s they are notified of the expiry or removal
124 * of the <code>Element</code> as each is removed.
125 */
126 void removeAll() throws CacheException;
127
128 /***
129 * Put an element in the store if no element is currently mapped to the elements key.
130 *
131 * @param element element to be added
132 * @return the element previously cached for this key, or null if none.
133 *
134 * @throws NullPointerException if the element is null, or has a null key
135 */
136 Element putIfAbsent(Element element) throws NullPointerException;
137
138 /***
139 * Remove the Element mapped to the key for the supplied element if the value of the supplied Element
140 * is equal to the value of the cached Element. This is a CAS operation. It is consistent even against
141 * a distributed cache that is not coherent. If the old value is stale when this operation is attempted
142 * the remove does not take place.
143 *
144 * @param element Element to be removed
145 * @param comparator ElementValueComparator to use to compare elements
146 * @return the Element removed or null if no Element was removed
147 *
148 * @throws NullPointerException if the element is null, or has a null key
149 */
150 Element removeElement(Element element, ElementValueComparator comparator) throws NullPointerException;
151
152 /***
153 * Replace the cached element only if the value of the current Element is equal to the value of the
154 * supplied old Element.
155 *
156 * @param old Element to be test against
157 * @param element Element to be cached
158 * @param comparator ElementValueComparator to use to compare elements
159 * @return true is the Element was replaced
160 * @throws NullPointerException if the either Element is null or has a null key
161 * @throws IllegalArgumentException if the two Element keys are non-null but not equal
162 */
163 boolean replace(Element old, Element element, ElementValueComparator comparator) throws NullPointerException, IllegalArgumentException;
164
165 /***
166 * Replace the cached element only if an Element is currently cached for this key
167 * @param element Element to be cached
168 * @return the Element previously cached for this key, or null if no Element was cached
169 * @throws NullPointerException if the Element is null or has a null key
170 */
171 Element replace(Element element) throws NullPointerException;
172
173 /***
174 * Prepares for shutdown.
175 */
176 void dispose();
177
178 /***
179 * Returns the current local store size
180 * @return the count of the Elements in the Store on the local machine
181 */
182 int getSize();
183
184 /***
185 * Returns the current local in-memory store size
186 * @return the count of the Elements in the Store and in-memory on the local machine
187 */
188 int getInMemorySize();
189
190 /***
191 * Returns the current local off-heap store size
192 * @return the count of the Elements in the Store and off-heap on the local machine
193 */
194 int getOffHeapSize();
195
196 /***
197 * Returns the current local on-disk store size
198 * @return the count of the Elements in the Store and on-disk on the local machine
199 */
200 int getOnDiskSize();
201
202 /***
203 * Returns the current Terracotta clustered store size
204 * @return the count of the Elements in the Store across the cluster
205 */
206 int getTerracottaClusteredSize();
207
208 /***
209 * Gets the size of the in-memory portion of the store, in bytes.
210 * <p/>
211 * This method may be expensive to run, depending on implementation. Implementers may choose to return
212 * an approximate size.
213 *
214 * @return the approximate in-memory size of the store in bytes
215 */
216 long getInMemorySizeInBytes();
217
218 /***
219 * Gets the size of the off-heap portion of the store, in bytes.
220 *
221 * @return the approximate off-heap size of the store in bytes
222 */
223 long getOffHeapSizeInBytes();
224
225 /***
226 * Gets the size of the on-disk portion of the store, in bytes.
227 *
228 * @return the on-disk size of the store in bytes
229 */
230 long getOnDiskSizeInBytes();
231
232 /***
233 * Returns the cache status.
234 */
235 Status getStatus();
236
237
238 /***
239 * A check to see if a key is in the Store.
240 *
241 * @param key The Element key
242 * @return true if found. No check is made to see if the Element is expired.
243 * 1.2
244 */
245 boolean containsKey(Object key);
246
247 /***
248 * A check to see if a key is in the Store and is currently held on disk.
249 *
250 * @param key The Element key
251 * @return true if found. No check is made to see if the Element is expired.
252 */
253 boolean containsKeyOnDisk(Object key);
254
255 /***
256 * A check to see if a key is in the Store and is currently held off-heap.
257 *
258 * @param key The Element key
259 * @return true if found. No check is made to see if the Element is expired.
260 */
261 boolean containsKeyOffHeap(Object key);
262
263 /***
264 * A check to see if a key is in the Store and is currently held in memory.
265 *
266 * @param key The Element key
267 * @return true if found. No check is made to see if the Element is expired.
268 */
269 boolean containsKeyInMemory(Object key);
270
271 /***
272 * Expire all elements.
273 */
274 public void expireElements();
275
276 /***
277 * Flush elements to persistent store.
278 * @throws IOException if any IO error occurs
279 */
280 void flush() throws IOException;
281
282 /***
283 * Some store types, such as the disk stores can fill their write buffers if puts
284 * come in too fast. The thread will wait for a short time before checking again.
285 * @return true if the store write buffer is backed up.
286 */
287 boolean bufferFull();
288
289 /***
290 * @return the current eviction policy. This may not be the configured policy, if it has been
291 * dynamically set.
292 * @see #setInMemoryEvictionPolicy(Policy)
293 */
294 Policy getInMemoryEvictionPolicy();
295
296 /***
297 * Sets the eviction policy strategy. The Store will use a policy at startup. The store may allow changing
298 * the eviction policy strategy dynamically. Otherwise implementations will throw an exception if this method
299 * is called.
300 *
301 * @param policy the new policy
302 */
303 void setInMemoryEvictionPolicy(Policy policy);
304
305 /***
306 * This should not be used, and will generally return null
307 * @return some internal context (probably null)
308 */
309 Object getInternalContext();
310
311 /***
312 * Indicates whether this store provides a coherent view of all the elements
313 * in a cache.
314 *
315 * Note that this is same as calling {@link #isClusterCoherent()} (introduced since 2.0)
316 * Use {@link #isNodeCoherent()} to find out if the cache is coherent in the current node in the cluster
317 *
318 * @return {@code true} if the store is coherent; or {@code false} if the
319 * store potentially splits the cache storage with another store or
320 * isn't internally coherent
321 * @since 1.7
322 */
323 boolean isCacheCoherent();
324
325 /***
326 * Returns true if the cache is in coherent mode cluster-wide. Returns false otherwise.
327 * <p />
328 * It applies to coherent clustering mechanisms only e.g. Terracotta
329 *
330 * @return true if the cache is in coherent mode cluster-wide, false otherwise
331 * @since 2.0
332 */
333 public boolean isClusterCoherent() throws TerracottaNotRunningException;
334
335 /***
336 * Returns true if the cache is in coherent mode for the current node. Returns false otherwise.
337 * <p />
338 * It applies to coherent clustering mechanisms only e.g. Terracotta
339 *
340 * @return true if the cache is in coherent mode cluster-wide, false otherwise
341 * @since 2.0
342 */
343 public boolean isNodeCoherent() throws TerracottaNotRunningException;
344
345 /***
346 * Sets the cache in coherent or incoherent mode for the current node depending on the parameter.
347 * Calling {@code setNodeCoherent(true)} when the cache is already in coherent mode or
348 * calling {@code setNodeCoherent(false)} when already in incoherent mode will be a no-op.
349 * <p />
350 * It applies to coherent clustering mechanisms only e.g. Terracotta
351 *
352 * @param coherent
353 * true transitions to coherent mode, false to incoherent mode
354 * @throws UnsupportedOperationException if this store does not support cache coherence, like RMI replication
355 * @since 2.0
356 */
357 public void setNodeCoherent(boolean coherent) throws UnsupportedOperationException, TerracottaNotRunningException;
358
359 /***
360 * 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
361 * immediately
362 * <p />
363 * It applies to coherent clustering mechanisms only e.g. Terracotta
364 * @throws UnsupportedOperationException if this store does not support cache coherence, like RMI replication
365 * @throws InterruptedException
366 * @since 2.0
367 */
368 public void waitUntilClusterCoherent() throws UnsupportedOperationException, TerracottaNotRunningException, InterruptedException;
369
370 /***
371 * Optional implementation specific MBean exposed by the store.
372 *
373 * @return implementation specific management bean
374 */
375 public Object getMBean();
376
377 /***
378 * Inform this store of the configured attribute extractors. Stores that will not invoke extractors are free to ignore this call
379 *
380 * @param extractors
381 */
382 public void setAttributeExtractors(Map<String, AttributeExtractor> extractors);
383
384 /***
385 * Execute the given query on this store
386 *
387 * @param query query to execute
388 * @return query results
389 */
390 public Results executeQuery(StoreQuery query) throws SearchException;
391
392 /***
393 * Retrieve the given named search attribute
394 *
395 * @param <T> type of the attribute
396 * @param attributeName the name of the attribute to retrieve
397 * @return the search attribute or null if non-existent
398 */
399 public <T> Attribute<T> getSearchAttribute(String attributeName);
400 }