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;
18
19 import java.beans.PropertyChangeListener;
20 import java.io.Serializable;
21 import java.util.Collection;
22 import java.util.List;
23 import java.util.Map;
24
25 import net.sf.ehcache.bootstrap.BootstrapCacheLoader;
26 import net.sf.ehcache.config.CacheConfiguration;
27 import net.sf.ehcache.config.NonstopConfiguration;
28 import net.sf.ehcache.event.RegisteredEventListeners;
29 import net.sf.ehcache.exceptionhandler.CacheExceptionHandler;
30 import net.sf.ehcache.extension.CacheExtension;
31 import net.sf.ehcache.loader.CacheLoader;
32 import net.sf.ehcache.search.Attribute;
33 import net.sf.ehcache.search.Query;
34 import net.sf.ehcache.statistics.CacheUsageListener;
35 import net.sf.ehcache.statistics.LiveCacheStatistics;
36 import net.sf.ehcache.statistics.sampled.SampledCacheStatistics;
37 import net.sf.ehcache.terracotta.TerracottaNotRunningException;
38 import net.sf.ehcache.transaction.manager.TransactionManagerLookup;
39 import net.sf.ehcache.writer.CacheWriter;
40 import net.sf.ehcache.writer.CacheWriterManager;
41
42 /***
43 * An interface for Ehcache.
44 * <p/>
45 * Ehcache is the central interface. Caches have {@link Element}s and are managed
46 * by the {@link CacheManager}. The Cache performs logical actions. It delegates physical
47 * implementations to its {@link net.sf.ehcache.store.Store}s.
48 * <p/>
49 * A reference to an EhCache can be obtained through the {@link CacheManager}. An Ehcache thus obtained
50 * is guaranteed to have status {@link Status#STATUS_ALIVE}. This status is checked for any method which
51 * throws {@link IllegalStateException} and the same thrown if it is not alive. This would normally
52 * happen if a call is made after {@link CacheManager#shutdown} is invoked.
53 * <p/>
54 * Statistics on cache usage are collected and made available through public methods.
55 *
56 * @author Greg Luck
57 * @version $Id: Ehcache.html 13146 2011-08-01 17:12:39Z oletizi $
58 */
59 public interface Ehcache extends Cloneable {
60 /***
61 * Put an element in the cache.
62 * <p/>
63 * Resets the access statistics on the element, which would be the case if it has previously been
64 * gotten from a cache, and is now being put back.
65 * <p/>
66 * Also notifies the CacheEventListener that:
67 * <ul>
68 * <li>the element was put, but only if the Element was actually put.
69 * <li>if the element exists in the cache, that an update has occurred, even if the element would be expired
70 * if it was requested
71 * </ul>
72 *
73 * @param element An object. If Serializable it can fully participate in replication and the DiskStore.
74 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
75 * @throws IllegalArgumentException if the element is null
76 * @throws CacheException
77 */
78 void put(Element element) throws IllegalArgumentException, IllegalStateException,
79 CacheException;
80
81
82 /***
83 * Puts a collection of elements in the cache. Throws a NullPointerException if any element in the
84 * collection is null. Also notifies the CacheEventListener that:
85 * <ul>
86 * <li>the elements were put. The puts{@link net.sf.ehcache.Ehcache#put(net.sf.ehcache.Element)} happen in batches and the notifications are thrown for every put in the
87 * batch irrespective of whether the element is present in the cache or not i.e this method consider
88 * each element as new entry.
89 * </li>
90 * </ul>
91 * This operation is partially completed if any element or any key is null
92 * @param elements a collection of elements to be put in the cache.
93 * If elements are Serializable it can fully participate in replication and the DiskStore.
94 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
95 * @throws CacheException
96 */
97 void putAll(Collection<Element> elements) throws IllegalArgumentException, IllegalStateException,
98 CacheException;
99
100 /***
101 * Put an element in the cache.
102 * <p/>
103 * Resets the access statistics on the element, which would be the case if it has previously been
104 * gotten from a cache, and is now being put back.
105 * <p/>
106 * Also notifies the CacheEventListener that:
107 * <ul>
108 * <li>the element was put, but only if the Element was actually put.
109 * <li>if the element exists in the cache, that an update has occurred, even if the element would be expired
110 * if it was requested
111 * </ul>
112 *
113 * @param element An object. If Serializable it can fully participate in replication and the DiskStore.
114 * @param doNotNotifyCacheReplicators whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a
115 * further notification to doNotNotifyCacheReplicators cache peers
116 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
117 * @throws IllegalArgumentException if the element is null
118 */
119 void put(Element element, boolean doNotNotifyCacheReplicators) throws IllegalArgumentException,
120 IllegalStateException,
121 CacheException;
122
123 /***
124 * Put an element in the cache, without updating statistics, or updating listeners. This is meant to be used
125 * in conjunction with {@link #getQuiet}
126 *
127 * @param element An object. If Serializable it can fully participate in replication and the DiskStore.
128 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
129 * @throws IllegalArgumentException if the element is null
130 */
131 void putQuiet(Element element) throws IllegalArgumentException, IllegalStateException,
132 CacheException;
133
134 /***
135 * Put an element in the cache writing through a CacheWriter. If no CacheWriter has been registered for the cache,
136 * then this method throws an exception.
137 * <p/>
138 * Resets the access statistics on the element, which would be the case if it has previously been
139 * gotten from a cache, and is now being put back.
140 * <p/>
141 * Also notifies the CacheEventListener, if the writer operation succeeds, that:
142 * <ul>
143 * <li>the element was put, but only if the Element was actually put.
144 * <li>if the element exists in the cache, that an update has occurred, even if the element would be expired
145 * if it was requested
146 * </ul>
147 *
148 * @param element An object. If Serializable it can fully participate in replication and the DiskStore.
149 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
150 * @throws IllegalArgumentException if the element is null
151 * @throws CacheException if no CacheWriter was registered
152 */
153 void putWithWriter(Element element) throws IllegalArgumentException, IllegalStateException, CacheException;
154
155 /***
156 * Put an element in the cache if no element is currently mapped to the elements key.
157 *
158 * @param element element to be added
159 * @return the element previously cached for this key, or null if none.
160 *
161 * @throws NullPointerException if the element is null, or has a null key
162 */
163 Element putIfAbsent(Element element) throws NullPointerException;
164
165 /***
166 * Remove the Element mapped to the key for the supplied element if the value of the supplied Element
167 * is equal to the value of the cached Element.
168 *
169 * @param element Element to be removed
170 * @return true if the value was removed
171 *
172 * @throws NullPointerException if the element is null, or has a null key
173 */
174 boolean removeElement(Element element) throws NullPointerException;
175
176 /***
177 * Replace the cached element only if the current Element is equal to the supplied old Element.
178 *
179 * @param old Element to be test against
180 * @param element Element to be cached
181 * @return true is the Element was replaced
182 * @throws NullPointerException if the either Element is null or has a null key
183 * @throws IllegalArgumentException if the two Element keys are non-null but not equal
184 */
185 boolean replace(Element old, Element element) throws NullPointerException, IllegalArgumentException;
186
187 /***
188 * Replace the cached element only if an Element is currently cached for this key
189 * @param element Element to be cached
190 * @return the Element previously cached for this key, or null if no Element was cached
191 * @throws NullPointerException if the Element is null or has a null key
192 */
193 Element replace(Element element) throws NullPointerException;
194
195 /***
196 * Gets an element from the cache. Updates Element Statistics
197 * <p/>
198 * Note that the Element's lastAccessTime is always the time of this get.
199 * Use {@link #getQuiet(Object)} to peak into the Element to see its last access time with get
200 *
201 * @param key a serializable value
202 * @return the element, or null, if it does not exist.
203 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
204 * @see #isExpired
205 */
206 Element get(Serializable key) throws IllegalStateException, CacheException;
207
208 /***
209 * Gets an element from the cache. Updates Element Statistics
210 * <p/>
211 * Note that the Element's lastAccessTime is always the time of this get.
212 * Use {@link #getQuiet(Object)} to peek into the Element to see its last access time with get
213 *
214 * @param key an Object value
215 * @return the element, or null, if it does not exist.
216 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
217 * @see #isExpired
218 * @since 1.2
219 */
220 Element get(Object key) throws IllegalStateException, CacheException;
221
222 /***
223 * Gets all the elements from the cache for the keys provided. Updates Element Statistics
224 * Throws a NullPointerException if any key in the collection is null
225 * <p/>
226 * Note that the Element's lastAccessTime is always the time of this get.
227 * Use {@link #getQuiet(Object)} to peek into the Element to see its last access time with get
228 *
229 * @param keys a collection of keys for which value is to be fetched
230 * @return Map of key and elements for the provided keys, value will be null for the keys which do not exist
231 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
232 * @throws NullPointerException if any key is null in the collection
233 * @see #isExpired
234 */
235 Map<Object, Element> getAll(Collection<Object> keys) throws IllegalStateException, CacheException, NullPointerException;
236
237 /***
238 * Gets an element from the cache, without updating Element statistics. Cache statistics are
239 * still updated.
240 * <p/>
241 *
242 * @param key a serializable value
243 * @return the element, or null, if it does not exist.
244 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
245 * @see #isExpired
246 * @since 2.5
247 */
248 Element getQuiet(Serializable key) throws IllegalStateException, CacheException;
249
250 /***
251 * Gets an element from the cache, without updating Element statistics. Cache statistics are
252 * also not updated.
253 * <p/>
254 *
255 * @param key a serializable value
256 * @return the element, or null, if it does not exist.
257 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
258 * @see #isExpired
259 * @since 1.2
260 */
261 Element getQuiet(Object key) throws IllegalStateException, CacheException;
262
263 /***
264 * Returns a list of all elements in the cache, whether or not they are expired.
265 * <p/>
266 * The returned keys are unique and can be considered a set.
267 * <p/>
268 * The List returned is not live. It is a copy.
269 * <p/>
270 * The time taken is O(n). On a single cpu 1.8Ghz P4, approximately 8ms is required
271 * for each 1000 entries.
272 *
273 * @return a list of {@link Object} keys
274 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
275 */
276 List getKeys() throws IllegalStateException, CacheException;
277
278 /***
279 * Returns a list of all elements in the cache. Only keys of non-expired
280 * elements are returned.
281 * <p/>
282 * The returned keys are unique and can be considered a set.
283 * <p/>
284 * The List returned is not live. It is a copy.
285 * <p/>
286 * The time taken is O(n), where n is the number of elements in the cache. On
287 * a 1.8Ghz P4, the time taken is approximately 200ms per 1000 entries. This method
288 * is not synchronized, because it relies on a non-live list returned from {@link #getKeys()}
289 * , which is synchronised, and which takes 8ms per 1000 entries. This way
290 * cache liveness is preserved, even if this method is very slow to return.
291 * <p/>
292 * Consider whether your usage requires checking for expired keys. Because
293 * this method takes so long, depending on cache settings, the list could be
294 * quite out of date by the time you get it.
295 *
296 * @return a list of {@link Object} keys
297 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
298 */
299 List getKeysWithExpiryCheck() throws IllegalStateException, CacheException;
300
301 /***
302 * Returns a list of all elements in the cache, whether or not they are expired.
303 * <p/>
304 * The returned keys are not unique and may contain duplicates. If the cache is only
305 * using the memory store, the list will be unique. If the disk store is being used
306 * as well, it will likely contain duplicates, because of the internal store design.
307 * <p/>
308 * The List returned is not live. It is a copy.
309 * <p/>
310 * The time taken is O(log n). On a single cpu 1.8Ghz P4, approximately 6ms is required
311 * for 1000 entries and 36 for 50000.
312 * <p/>
313 * This is the fastest getKeys method
314 *
315 * @return a list of {@link Object} keys
316 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
317 */
318 List getKeysNoDuplicateCheck() throws IllegalStateException;
319
320 /***
321 * Removes an {@link net.sf.ehcache.Element} from the Cache. This also removes it from any
322 * stores it may be in.
323 * <p/>
324 * Also notifies the CacheEventListener after the element was removed.
325 *
326 * @param key
327 * @return true if the element was removed, false if it was not found in the cache
328 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
329 */
330 boolean remove(Serializable key) throws IllegalStateException;
331
332 /***
333 * Removes an {@link net.sf.ehcache.Element} from the Cache. This also removes it from any
334 * stores it may be in.
335 * <p/>
336 * Also notifies the CacheEventListener after the element was removed, but only if an Element
337 * with the key actually existed.
338 *
339 * @param key
340 * @return true if the element was removed, false if it was not found in the cache
341 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
342 * @since 1.2
343 */
344 boolean remove(Object key) throws IllegalStateException;
345
346 /***
347 * Removes given set of {@link net.sf.ehcache.Element} from the Cache. This also removes them from any
348 * stores it may be in. Throws a NullPointerException if any key in the collection is null
349 * <p/>
350 * Also notifies the CacheEventListener after the elements were removed.
351 * Notification is sent for every key irrespective of whether the key was present in the cache or not
352 * This operation is partially completed if any element or any key is null
353 * @param keys a collection of keys to operate on
354 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
355 * @throws NullPointerException if any key is null in the collection
356 */
357 void removeAll(Collection<Object> keys) throws IllegalStateException, NullPointerException;
358
359 /***
360 * Removes all cached items.
361 * <p />
362 * When using Terracotta clustered caches with nonstop enabled, the timeout used by this method is
363 * {@link NonstopConfiguration#getBulkOpsTimeoutMultiplyFactor()} times the timeout value in the nonstop config.
364 *
365 * @param doNotNotifyCacheReplicators whether the put is coming from a doNotNotifyCacheReplicators cache peer,
366 * in which case this put should not initiate a further notification to doNotNotifyCacheReplicators cache peers
367 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
368 */
369 void removeAll(Collection<Object> keys, boolean doNotNotifyCacheReplicators) throws IllegalStateException, NullPointerException;
370
371 /***
372 * Removes an {@link net.sf.ehcache.Element} from the Cache. This also removes it from any
373 * stores it may be in.
374 * <p/>
375 * Also notifies the CacheEventListener after the element was removed, but only if an Element
376 * with the key actually existed.
377 *
378 * @param key
379 * @param doNotNotifyCacheReplicators whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a
380 * further notification to doNotNotifyCacheReplicators cache peers
381 * @return true if the element was removed, false if it was not found in the cache
382 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
383 */
384 boolean remove(Serializable key, boolean doNotNotifyCacheReplicators) throws IllegalStateException;
385
386 /***
387 * Removes an {@link net.sf.ehcache.Element} from the Cache. This also removes it from any
388 * stores it may be in.
389 * <p/>
390 * Also notifies the CacheEventListener after the element was removed, but only if an Element
391 * with the key actually existed.
392 *
393 * @param key
394 * @param doNotNotifyCacheReplicators whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a
395 * further notification to doNotNotifyCacheReplicators cache peers
396 * @return true if the element was removed, false if it was not found in the cache
397 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
398 */
399 boolean remove(Object key, boolean doNotNotifyCacheReplicators) throws IllegalStateException;
400
401 /***
402 * Removes an {@link net.sf.ehcache.Element} from the Cache, without notifying listeners. This also removes it from any
403 * stores it may be in.
404 * <p/>
405 *
406 * @param key
407 * @return true if the element was removed, false if it was not found in the cache
408 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
409 */
410 boolean removeQuiet(Serializable key) throws IllegalStateException;
411
412 /***
413 * Removes an {@link net.sf.ehcache.Element} from the Cache, without notifying listeners. This also removes it from any
414 * stores it may be in.
415 * <p/>
416 *
417 * @param key
418 * @return true if the element was removed, false if it was not found in the cache
419 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
420 * @since 1.2
421 */
422 boolean removeQuiet(Object key) throws IllegalStateException;
423
424 /***
425 * Removes an {@link net.sf.ehcache.Element} from the Cache and any stores it might be in. This also removes through
426 * to a CacheWriter. If no CacheWriter has been registered for the cache, then this method throws an exception.
427 * <p/>
428 * Also notifies the CacheEventListener after the element was removed, but only if an Element
429 * with the key actually existed.
430 *
431 * @param key
432 * @return true if the element was removed, false if it was not found in the cache
433 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
434 * @throws CacheException if no CacheWriter was registered
435 * @since 2.0
436 */
437 boolean removeWithWriter(Object key) throws IllegalStateException, CacheException;
438
439 /***
440 * Removes all cached items.
441 * <p />
442 * When using Terracotta clustered caches with nonstop enabled, the timeout used by this method is
443 * {@link NonstopConfiguration#getBulkOpsTimeoutMultiplyFactor()} times the timeout value in the nonstop config.
444 *
445 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
446 */
447 void removeAll() throws IllegalStateException, CacheException;
448
449 /***
450 * Removes all cached items.
451 * <p />
452 * When using Terracotta clustered caches with nonstop enabled, the timeout used by this method is
453 * {@link NonstopConfiguration#getBulkOpsTimeoutMultiplyFactor()} times the timeout value in the nonstop config.
454 *
455 * @param doNotNotifyCacheReplicators whether the put is coming from a doNotNotifyCacheReplicators cache peer,
456 * in which case this put should not initiate a further notification to doNotNotifyCacheReplicators cache peers
457 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
458 */
459 void removeAll(boolean doNotNotifyCacheReplicators) throws IllegalStateException, CacheException;
460
461 /***
462 * Flushes all cache items from memory to the disk store, and from the DiskStore to disk.
463 *
464 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
465 */
466 void flush() throws IllegalStateException, CacheException;
467
468 /***
469 * Gets the size of the cache. This is a subtle concept. See below.
470 * <p/>
471 * The size is the number of {@link net.sf.ehcache.Element}s in the {@link net.sf.ehcache.store.MemoryStore} plus
472 * the number of {@link net.sf.ehcache.Element}s in the {@link net.sf.ehcache.store.disk.DiskStore}.
473 * <p/>
474 * This number is the actual number of elements, including expired elements that have
475 * not been removed.
476 * <p/>
477 * Expired elements are removed from the the memory store when
478 * getting an expired element, or when attempting to spool an expired element to
479 * disk.
480 * <p/>
481 * Expired elements are removed from the disk store when getting an expired element,
482 * or when the expiry thread runs, which is once every five minutes.
483 * <p/>
484 * To get an exact size, which would exclude expired elements, use {@link #getKeysWithExpiryCheck()}.size(),
485 * although see that method for the approximate time that would take.
486 * <p/>
487 * To get a very fast result, use {@link #getKeysNoDuplicateCheck()}.size(). If the disk store
488 * is being used, there will be some duplicates.
489 * <p/>
490 * Note:getSize() is a very expensive operation in off-heap, disk and Terracotta implementations.
491 *
492 * @return The size value
493 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
494 */
495 int getSize() throws IllegalStateException, CacheException;
496
497 /***
498 * Accurately measuring statistics can be expensive. Returns the size of the
499 * cache based on the accuracy setting
500 *
501 * @param statisticsAccuracy
502 * one of {@link Statistics#STATISTICS_ACCURACY_BEST_EFFORT},
503 * {@link Statistics#STATISTICS_ACCURACY_GUARANTEED},
504 * {@link Statistics#STATISTICS_ACCURACY_NONE}
505 * @return the size of the cache based on the current accuracy setting
506 * @throws IllegalArgumentException
507 * if the statisticsAccuracy is not one of the above
508 * @throws IllegalStateException
509 * if the cache is not
510 * {@link net.sf.ehcache.Status#STATUS_ALIVE}
511 */
512 int getSizeBasedOnAccuracy(int statisticsAccuracy)
513 throws IllegalArgumentException, IllegalStateException,
514 CacheException;
515
516 /***
517 * Gets the size of the memory store for this cache
518 * <p/>
519 * Warning: This method can be very expensive to run. Allow approximately 1 second
520 * per 1MB of entries. Running this method could create liveness problems
521 * because the object lock is held for a long period
522 * <p/>
523 *
524 * @return the approximate size of the memory store in bytes
525 * @throws IllegalStateException
526 */
527 long calculateInMemorySize() throws IllegalStateException, CacheException;
528
529 /***
530 * Gets the size of the off-heap store for this cache
531 *
532 * @return the size of the off-heap store in bytes
533 * @throws IllegalStateException
534 */
535 long calculateOffHeapSize() throws IllegalStateException, CacheException;
536
537 /***
538 * Gets the size of the on-disk store for this cache
539 *
540 * @return the size of the on-disk store in bytes
541 * @throws IllegalStateException
542 */
543 long calculateOnDiskSize() throws IllegalStateException, CacheException;
544
545 /***
546 * Returns the number of elements in the memory store.
547 *
548 * @return the number of elements in the memory store
549 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
550 */
551 long getMemoryStoreSize() throws IllegalStateException;
552
553 /***
554 * Returns the number of elements in the off-heap store.
555 *
556 * @return the number of elements in the off-heap store
557 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
558 */
559 long getOffHeapStoreSize() throws IllegalStateException;
560
561 /***
562 * Returns the number of elements in the disk store.
563 *
564 * @return the number of elements in the disk store.
565 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
566 */
567 int getDiskStoreSize() throws IllegalStateException;
568
569 /***
570 * Gets the status attribute of the Cache.
571 *
572 * @return The status value from the Status enum class
573 */
574 Status getStatus();
575
576 /***
577 * Gets the cache name.
578 */
579 String getName();
580
581 /***
582 * Sets the cache name which will name.
583 *
584 * @param name the name of the cache. Should not be null.
585 */
586 void setName(String name);
587
588 /***
589 * Returns a {@link String} representation of {@link net.sf.ehcache.Cache}.
590 */
591 String toString();
592
593 /***
594 * Checks whether this cache element has expired.
595 * <p/>
596 * The element is expired if:
597 * <ol>
598 * <li> the idle time is non-zero and has elapsed, unless the cache is eternal; or
599 * <li> the time to live is non-zero and has elapsed, unless the cache is eternal; or
600 * <li> the value of the element is null.
601 * </ol>
602 *
603 * @param element the element to check
604 * @return true if it has expired
605 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
606 * @throws NullPointerException if the element is null
607 */
608 boolean isExpired(Element element) throws IllegalStateException, NullPointerException;
609
610 /***
611 * Clones a cache. This is only legal if the cache has not been
612 * initialized. At that point only primitives have been set and no
613 * {@link net.sf.ehcache.store.MemoryStore} or {@link net.sf.ehcache.store.disk.DiskStore} has been created.
614 * <p/>
615 * A new, empty, RegisteredEventListeners is created on clone.
616 * <p/>
617 *
618 * @return an object of type {@link net.sf.ehcache.Cache}
619 * @throws CloneNotSupportedException
620 */
621 Object clone() throws CloneNotSupportedException;
622
623
624 /***
625 * Use this to access the service in order to register and unregister listeners
626 *
627 * @return the RegisteredEventListeners instance for this cache.
628 */
629 RegisteredEventListeners getCacheEventNotificationService();
630
631 /***
632 * Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.
633 * <p>
634 * Since no assertions are made about the state of the Element it is possible that the
635 * Element is expired, but this method still returns true.
636 *
637 * @return true if an element matching the key is found in memory
638 */
639 boolean isElementInMemory(Serializable key);
640
641 /***
642 * Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.
643 * <p>
644 * Since no assertions are made about the state of the Element it is possible that the
645 * Element is expired, but this method still returns true.
646 *
647 * @return true if an element matching the key is found in memory
648 * @since 1.2
649 */
650 boolean isElementInMemory(Object key);
651
652 /***
653 * Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.
654 * <p>
655 * Since no assertions are made about the state of the Element it is possible that the
656 * Element is expired, but this method still returns true.
657 *
658 * @return true if an element matching the key is found in the diskStore
659 */
660 boolean isElementOnDisk(Serializable key);
661
662 /***
663 * Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.
664 * <p>
665 * Since no assertions are made about the state of the Element it is possible that the
666 * Element is expired, but this method still returns true.
667 *
668 * @return true if an element matching the key is found in the diskStore
669 * @since 1.2
670 */
671 boolean isElementOnDisk(Object key);
672
673 /***
674 * The GUID for this cache instance can be used to determine whether two cache instance references
675 * are pointing to the same cache.
676 *
677 * @return the globally unique identifier for this cache instance. This is guaranteed to be unique.
678 * @since 1.2
679 */
680 String getGuid();
681
682 /***
683 * Gets the CacheManager managing this cache. For a newly created cache this will be null until
684 * it has been added to a CacheManager.
685 *
686 * @return the manager or null if there is none
687 */
688 CacheManager getCacheManager();
689
690 /***
691 * Resets statistics counters back to 0.
692 */
693 void clearStatistics();
694
695 /***
696 * Accurately measuring statistics can be expensive. Returns the current accuracy setting.
697 *
698 * @return one of {@link Statistics#STATISTICS_ACCURACY_BEST_EFFORT}, {@link Statistics#STATISTICS_ACCURACY_GUARANTEED}, {@link Statistics#STATISTICS_ACCURACY_NONE}
699 */
700 public int getStatisticsAccuracy();
701
702
703 /***
704 * Sets the statistics accuracy.
705 *
706 * @param statisticsAccuracy one of {@link Statistics#STATISTICS_ACCURACY_BEST_EFFORT}, {@link Statistics#STATISTICS_ACCURACY_GUARANTEED}, {@link Statistics#STATISTICS_ACCURACY_NONE}
707 */
708 public void setStatisticsAccuracy(int statisticsAccuracy);
709
710
711 /***
712 * Causes all elements stored in the Cache to be synchronously checked for expiry, and if expired, evicted.
713 */
714 void evictExpiredElements();
715
716 /***
717 * An inexpensive check to see if the key exists in the cache.
718 * <p>
719 * Since no assertions are made about the state of the Element it is possible that the
720 * Element is expired, but this method still returns true.
721 *
722 * @param key the key to check for
723 * @return true if an Element matching the key is found in the cache. No assertions are made about the state of the Element.
724 */
725 boolean isKeyInCache(Object key);
726
727 /***
728 * An extremely expensive check to see if the value exists in the cache.
729 *
730 * @param value to check for
731 * @return true if an Element matching the key is found in the cache. No assertions are made about the state of the Element.
732 */
733 boolean isValueInCache(Object value);
734
735 /***
736 * Gets an immutable Statistics object representing the Cache statistics at the time. How the statistics are calculated
737 * depends on the statistics accuracy setting. The only aspect of statistics sensitive to the accuracy setting is
738 * object size. How that is calculated is discussed below.
739 * <h3>Best Effort Size</h3>
740 * This result is returned when the statistics accuracy setting is {@link Statistics#STATISTICS_ACCURACY_BEST_EFFORT}.
741 * <p/>
742 * The size is the number of {@link Element}s in the {@link net.sf.ehcache.store.MemoryStore} plus
743 * the number of {@link Element}s in the {@link net.sf.ehcache.store.disk.DiskStore}.
744 * <p/>
745 * This number is the actual number of elements, including expired elements that have
746 * not been removed. Any duplicates between stores are accounted for.
747 * <p/>
748 * Expired elements are removed from the the memory store when
749 * getting an expired element, or when attempting to spool an expired element to
750 * disk.
751 * <p/>
752 * Expired elements are removed from the disk store when getting an expired element,
753 * or when the expiry thread runs, which is once every five minutes.
754 * <p/>
755 * <h3>Guaranteed Accuracy Size</h3>
756 * This result is returned when the statistics accuracy setting is {@link Statistics#STATISTICS_ACCURACY_GUARANTEED}.
757 * <p/>
758 * This method accounts for elements which might be expired or duplicated between stores. It take approximately
759 * 200ms per 1000 elements to execute.
760 * <h3>Fast but non-accurate Size</h3>
761 * This result is returned when the statistics accuracy setting is {@link Statistics#STATISTICS_ACCURACY_NONE}.
762 * <p/>
763 * The number given may contain expired elements. In addition if the DiskStore is used it may contain some double
764 * counting of elements. It takes 6ms for 1000 elements to execute. Time to execute is O(log n). 50,000 elements take
765 * 36ms.
766 * @return the number of elements in the ehcache, with a varying degree of accuracy, depending on accuracy setting.
767 * @throws IllegalStateException if the cache is not {@link Status#STATUS_ALIVE}
768 */
769 Statistics getStatistics() throws IllegalStateException;
770
771 /***
772 * This is different from {@link #getStatistics()} in the way that values
773 * returned from {@link LiveCacheStatistics} will reflect the current state
774 * of the cache (and not a snapshot of the cache when the api's were called
775 * like {@link #getStatistics()})
776 *
777 * @return The {@link LiveCacheStatistics} associated with this cache
778 * @throws IllegalStateException
779 * @since 1.7
780 */
781 LiveCacheStatistics getLiveCacheStatistics() throws IllegalStateException;
782
783 /***
784 * Registers a {@link CacheUsageListener} which will be notified of the
785 * cache
786 * usage.
787 * Implementations of {@link CacheUsageListener} should override the
788 * {@link Object#equals(Object)} and {@link Object#hashCode()} methods as it is used for
789 * equality check
790 *
791 * @throws IllegalStateException
792 * @since 1.7
793 */
794 void registerCacheUsageListener(CacheUsageListener cacheUsageListener)
795 throws IllegalStateException;
796
797 /***
798 * Remove an already registered {@link CacheUsageListener}, if any.
799 * Depends on the {@link Object#equals(Object)} method.
800 *
801 * @throws IllegalStateException
802 * @since 1.7
803 */
804 void removeCacheUsageListener(CacheUsageListener cacheUsageListener)
805 throws IllegalStateException;
806
807 /***
808 * Sets the CacheManager
809 *
810 * @param cacheManager the CacheManager for this cache to use.
811 */
812 void setCacheManager(CacheManager cacheManager);
813
814
815 /***
816 * Accessor for the BootstrapCacheLoader associated with this cache. For testing purposes.
817 *
818 * @return the BootstrapCacheLoader to use
819 */
820 BootstrapCacheLoader getBootstrapCacheLoader();
821
822 /***
823 * Sets the bootstrap cache loader.
824 *
825 * @param bootstrapCacheLoader the loader to be used
826 * @throws CacheException if this method is called after the cache is initialized
827 */
828 void setBootstrapCacheLoader(BootstrapCacheLoader bootstrapCacheLoader) throws CacheException;
829
830
831 /***
832 * DiskStore paths can conflict between CacheManager instances. This method allows the path to be changed.
833 *
834 * @param diskStorePath the new path to be used.
835 * @throws CacheException if this method is called after the cache is initialized
836 */
837 void setDiskStorePath(String diskStorePath) throws CacheException;
838
839 /***
840 * Newly created caches do not have a {@link net.sf.ehcache.store.MemoryStore} or a {@link net.sf.ehcache.store.disk.DiskStore}.
841 * <p/>
842 * This method creates those and makes the cache ready to accept elements
843 */
844 void initialise();
845
846 /***
847 * Bootstrap command. This must be called after the Cache is intialised, during
848 * CacheManager initialisation. If loads are synchronous, they will complete before the CacheManager
849 * initialise completes, otherwise they will happen in the background.
850 */
851 void bootstrap();
852
853 /***
854 * Flushes all cache items from memory to auxilliary caches and close the auxilliary caches.
855 * <p/>
856 * Should be invoked only by CacheManager.
857 *
858 * @throws IllegalStateException if the cache is not {@link Status#STATUS_ALIVE}
859 */
860 public void dispose() throws IllegalStateException;
861
862 /***
863 * Gets the cache configuration this cache was created with.
864 * <p/>
865 * Things like listeners that are added dynamically are excluded.
866 */
867 CacheConfiguration getCacheConfiguration();
868
869 /***
870 * Register a {@link CacheExtension} with the cache. It will then be tied into the cache lifecycle.
871 * <p/>
872 * If the CacheExtension is not initialised, initialise it.
873 */
874 public void registerCacheExtension(CacheExtension cacheExtension);
875
876 /***
877 * Unregister a {@link CacheExtension} with the cache. It will then be detached from the cache lifecycle.
878 */
879 public void unregisterCacheExtension(CacheExtension cacheExtension);
880
881 /***
882 *
883 * @return the cache extensions as a live list
884 */
885 public List<CacheExtension> getRegisteredCacheExtensions();
886
887 /***
888 * The average get time in ms.
889 */
890 public float getAverageGetTime();
891
892 /***
893 * Sets an ExceptionHandler on the Cache. If one is already set, it is overwritten.
894 */
895 public void setCacheExceptionHandler(CacheExceptionHandler cacheExceptionHandler);
896
897 /***
898 * Sets an ExceptionHandler on the Cache. If one is already set, it is overwritten.
899 */
900 public CacheExceptionHandler getCacheExceptionHandler();
901
902 /***
903 * Register a {@link CacheLoader} with the cache. It will then be tied into the cache lifecycle.
904 * <p/>
905 * If the CacheLoader is not initialised, initialise it.
906 *
907 * @param cacheLoader A Cache Loader to register
908 */
909 public void registerCacheLoader(CacheLoader cacheLoader);
910
911 /***
912 * Unregister a {@link CacheLoader} with the cache. It will then be detached from the cache lifecycle.
913 *
914 * @param cacheLoader A Cache Loader to unregister
915 */
916 public void unregisterCacheLoader(CacheLoader cacheLoader);
917
918 /***
919 *
920 * @return the cache loaders as a live list
921 */
922 public List<CacheLoader> getRegisteredCacheLoaders();
923
924 /***
925 * Register the {@link CacheWriter} for this cache. It will then be tied into the cache lifecycle.
926 * <p/>
927 * If the {@code CacheWriter} is not initialised, initialise it.
928 *
929 * @param cacheWriter A CacheWriter to register
930 */
931 public void registerCacheWriter(CacheWriter cacheWriter);
932
933 /***
934 * Unregister the {@link CacheWriter} from the cache. It will then be detached from the cache lifecycle.
935 * <p/>
936 * If not {@code CacheWriter} was registered beforehand this operation has no effect.
937 */
938 public void unregisterCacheWriter();
939
940 /***
941 * Retrieves the {@link CacheWriter} that was registered for this cache.
942 *
943 * @return the registered {@code CacheWriter}; or {@code null} if none was registered before
944 */
945 public CacheWriter getRegisteredCacheWriter();
946
947 /***
948 * This method will return, from the cache, the object associated with
949 * the argument "key".
950 * <p/>
951 * If the object is not in the cache, the associated
952 * cache loader will be called. That is either the CacheLoader passed in, or if null, the one associated with the cache.
953 * If both are null, no load is performed and null is returned.
954 * <p/>
955 * Because this method may take a long time to complete, it is not synchronized. The underlying cache operations
956 * are synchronized.
957 *
958 * @param key key whose associated value is to be returned.
959 * @param loader the override loader to use. If null, the cache's default loader will be used
960 * @param loaderArgument an argument to pass to the CacheLoader.
961 * @return an element if it existed or could be loaded, otherwise null
962 * @throws CacheException
963 */
964 public Element getWithLoader(Object key, CacheLoader loader, Object loaderArgument) throws CacheException;
965
966 /***
967 * The getAll method will return, from the cache, a Map of the objects associated with the Collection of keys in argument "keys".
968 * If the objects are not in the cache, the associated cache loader will be called. If no loader is associated with an object,
969 * a null is returned. If a problem is encountered during the retrieving or loading of the objects, an exception will be thrown.
970 * If the "arg" argument is set, the arg object will be passed to the CacheLoader.loadAll method. The cache will not dereference
971 * the object. If no "arg" value is provided a null will be passed to the loadAll method. The storing of null values in the cache
972 * is permitted, however, the get method will not distinguish returning a null stored in the cache and not finding the object in
973 * the cache. In both cases a null is returned.
974 * <p/>
975 * <p/>
976 * Note. If the getAll exceeds the maximum cache size, the returned map will necessarily be less than the number specified.
977 * <p/>
978 * Because this method may take a long time to complete, it is not synchronized. The underlying cache operations
979 * are synchronized.
980 * <p/>
981 * The constructs package provides similar functionality using the
982 * decorator {@link net.sf.ehcache.constructs.blocking.SelfPopulatingCache}
983 * @param keys a collection of keys to be returned/loaded
984 * @param loaderArgument an argument to pass to the CacheLoader.
985 * @return a Map populated from the Cache. If there are no elements, an empty Map is returned.
986 * @throws CacheException
987 */
988 public Map getAllWithLoader(Collection keys, Object loaderArgument) throws CacheException;
989
990
991 /***
992 * The load method provides a means to "pre load" the cache. This method will, asynchronously, load the specified
993 * object into the cache using the associated cacheloader. If the object already exists in the cache, no action is
994 * taken. If no loader is associated with the object, no object will be loaded into the cache. If a problem is
995 * encountered during the retrieving or loading of the object, an exception should be logged. If the "arg" argument
996 * is set, the arg object will be passed to the CacheLoader.load method. The cache will not dereference the object.
997 * If no "arg" value is provided a null will be passed to the load method. The storing of null values in the cache
998 * is permitted, however, the get method will not distinguish returning a null stored in the cache and not finding
999 * the object in the cache. In both cases a null is returned.
1000 * <p/>
1001 * The Ehcache native API provides similar functionality to loaders using the
1002 * decorator {@link net.sf.ehcache.constructs.blocking.SelfPopulatingCache}
1003 *
1004 * @param key key whose associated value to be loaded using the associated cacheloader if this cache doesn't contain it.
1005 * @throws CacheException
1006 */
1007 public void load(final Object key) throws CacheException;
1008
1009
1010 /***
1011 * The loadAll method provides a means to "pre load" objects into the cache. This method will, asynchronously, load
1012 * the specified objects into the cache using the associated cache loader. If the an object already exists in the
1013 * cache, no action is taken. If no loader is associated with the object, no object will be loaded into the cache.
1014 * If a problem is encountered during the retrieving or loading of the objects, an exception (to be defined)
1015 * should be logged. The getAll method will return, from the cache, a Map of the objects associated with the
1016 * Collection of keys in argument "keys". If the objects are not in the cache, the associated cache loader will be
1017 * called. If no loader is associated with an object, a null is returned. If a problem is encountered during the
1018 * retrieving or loading of the objects, an exception (to be defined) will be thrown. If the "arg" argument is set,
1019 * the arg object will be passed to the CacheLoader.loadAll method. The cache will not dereference the object.
1020 * If no "arg" value is provided a null will be passed to the loadAll method.
1021 * <p/>
1022 * keys - collection of the keys whose associated values to be loaded into this cache by using the associated
1023 * cacheloader if this cache doesn't contain them.
1024 * <p/>
1025 * The Ehcache native API provides similar functionality to loaders using the
1026 * decorator {@link net.sf.ehcache.constructs.blocking.SelfPopulatingCache}
1027 */
1028 public void loadAll(final Collection keys, final Object argument) throws CacheException;
1029
1030
1031
1032 /***
1033 * Whether this cache is disabled. "Disabled" means:
1034 * <ol>
1035 * <li>bootstrap is disabled
1036 * <li>puts are discarded
1037 * <li>putQuites are discarded
1038 * </ol>
1039 * In all other respects the cache continues as it is.
1040 * <p/>
1041 * You can disable and enable a cache programmatically through the {@link #setDisabled(boolean)} method.
1042 * <p/>
1043 * @return true if the cache is disabled.
1044 */
1045 public boolean isDisabled();
1046
1047 /***
1048 * Disables or enables this cache. This call overrides the previous value of disabled.
1049 * <p/>
1050 * @param disabled true if you wish to disable, false to enable
1051 * @see #isDisabled()
1052 */
1053 public void setDisabled(boolean disabled);
1054
1055 /***
1056 * Returns true if statistics collection is enabled
1057 *
1058 * @return true if statistics is enabled, false otherwise
1059 */
1060 public boolean isStatisticsEnabled();
1061
1062 /***
1063 * Enable/disable statistics collection.
1064 * Enabling statistics does not have any effect on sampled statistics. To
1065 * enable sampled statistics, use
1066 * {@link #setSampledStatisticsEnabled(boolean)} with
1067 * parameter <tt>true</tt>.
1068 * Disabling statistics also disables the sampled statistics collection if
1069 * it is enabled
1070 *
1071 * @param enableStatistics
1072 */
1073 public void setStatisticsEnabled(boolean enableStatistics);
1074
1075 /***
1076 * Returns sampled statistics for this cache.
1077 *
1078 * @return The sampled cache statistics
1079 */
1080 public SampledCacheStatistics getSampledCacheStatistics();
1081
1082 /***
1083 * Enable/disable sampled statistics collection.
1084 * Enabling sampled statistics also enables the normal statistics collection if its not already enabled.
1085 * Disabling sampled statistics does not have any effect on normal statistics.
1086 *
1087 * @param enableStatistics
1088 */
1089 public void setSampledStatisticsEnabled(boolean enableStatistics);
1090
1091 /***
1092 * Returns if sampled statistics collection is enabled or disabled
1093 *
1094 * @return true if sampled statistics is enabled, false otherwise
1095 */
1096 public boolean isSampledStatisticsEnabled();
1097
1098 /***
1099 * This should not be used
1100 * return some internal context (generally will be null)
1101 */
1102 Object getInternalContext();
1103
1104 /***
1105 * Disables dynamic configuration and disable/enable for this cache.
1106 * <p>
1107 * This is a one time operation. Once an Ehcache instance has had its dynamic operations disabled they cannot be
1108 * re-enabled.
1109 */
1110 public void disableDynamicFeatures();
1111
1112 /***
1113 * Obtain the writer manager that's used by this cache instance.
1114 *
1115 * @return the writer manager that's set up for this cache
1116 */
1117 public CacheWriterManager getWriterManager();
1118
1119 /***
1120 * Returns true if the cache is in coherent mode cluster-wide. Returns false otherwise.
1121 * <p />
1122 * It applies to coherent clustering mechanisms only e.g. Terracotta
1123 *
1124 * @return true if the cache is in coherent mode cluster-wide, false otherwise
1125 * @deprecated Use {@link #isClusterBulkLoadEnabled()} instead
1126 */
1127 @Deprecated
1128 public boolean isClusterCoherent() throws TerracottaNotRunningException;
1129
1130 /***
1131 * Returns true if the cache is in coherent mode for the current node. Returns false otherwise.
1132 * <p />
1133 * It applies to coherent clustering mechanisms only e.g. Terracotta
1134 *
1135 * @return true if the cache is in coherent mode cluster-wide, false otherwise
1136 * @deprecated Use {@link #isNodeBulkLoadEnabled()} instead
1137 */
1138 @Deprecated
1139 public boolean isNodeCoherent() throws TerracottaNotRunningException;
1140
1141 /***
1142 * Sets the cache in coherent or incoherent mode depending on the parameter on this node.
1143 * Calling {@code setNodeCoherent(true)} when the cache is already in coherent mode or
1144 * calling {@code setNodeCoherent(false)} when already in incoherent mode will be a no-op.
1145 * <p />
1146 * It applies to coherent clustering mechanisms only e.g. Terracotta
1147 * <p />
1148 * When using Terracotta clustered caches with nonstop enabled, the timeout used by this method is
1149 * {@link NonstopConfiguration#getBulkOpsTimeoutMultiplyFactor()} times the timeout value in the config.
1150 *
1151 * @param coherent
1152 * true transitions to coherent mode, false to incoherent mode
1153 * @throws UnsupportedOperationException if this cache does not support coherence, like RMI replication
1154 * @deprecated Use {@link #setNodeBulkLoadEnabled(boolean)} instead
1155 */
1156 @Deprecated
1157 public void setNodeCoherent(boolean coherent) throws UnsupportedOperationException, TerracottaNotRunningException;
1158
1159 /***
1160 * This method waits until the cache is in coherent mode in all the connected nodes.
1161 * If the cache is already in coherent mode it returns immediately
1162 * <p />
1163 * It applies to coherent clustering mechanisms only e.g. Terracotta
1164 * @throws UnsupportedOperationException if this cache does not support coherence, like RMI replication
1165 * @deprecated Use {@link #waitUntilClusterBulkLoadComplete()} instead
1166 */
1167 @Deprecated
1168 public void waitUntilClusterCoherent() throws UnsupportedOperationException, TerracottaNotRunningException;
1169
1170 /***
1171 * This class is used to access the transaction manager used during XA.
1172 * @param transactionManagerLookup
1173 */
1174 public void setTransactionManagerLookup(TransactionManagerLookup transactionManagerLookup);
1175
1176 /***
1177 * Add a PropertyChangeListener.
1178 *
1179 * @param listener
1180 */
1181 public void addPropertyChangeListener(PropertyChangeListener listener);
1182
1183 /***
1184 * Remove a PropertyChangeListener.
1185 *
1186 * @param listener
1187 */
1188 public void removePropertyChangeListener(PropertyChangeListener listener);
1189
1190 /***
1191 * Retrieve the given named search attribute
1192 *
1193 * @param <T>
1194 * type of the attribute
1195 * @param attributeName
1196 * the name of the attribute to retrieve
1197 * @throws CacheException
1198 * if no such attribute is defined for the given name
1199 * @return the search attribute
1200 */
1201 public <T> Attribute<T> getSearchAttribute(String attributeName) throws CacheException;
1202
1203 /***
1204 * Create a new query builder for this cache
1205 *
1206 * @return a new query builder
1207 */
1208 public Query createQuery();
1209
1210 /***
1211 * Is this cache searchable?
1212 *
1213 * @return true if this cache is searchable
1214 */
1215 public boolean isSearchable();
1216
1217 /***
1218 * Get the average search execution time (in millis) for searches that have completed in the last sample period
1219 */
1220 public long getAverageSearchTime();
1221
1222 /***
1223 * Get the number of search executions that have completed in the last second
1224 */
1225 public long getSearchesPerSecond();
1226
1227 /***
1228 * Acquires the proper read lock for a given cache key
1229 *
1230 * @param key - The key that retrieves a value that you want to protect via locking
1231 */
1232 public void acquireReadLockOnKey(Object key);
1233
1234 /***
1235 * Acquires the proper write lock for a given cache key
1236 *
1237 * @param key - The key that retrieves a value that you want to protect via locking
1238 */
1239 public void acquireWriteLockOnKey(Object key);
1240
1241 /***
1242 * Try to get a read lock on a given key. If can't get it in timeout millis then
1243 * return a boolean telling that it didn't get the lock
1244 *
1245 * @param key - The key that retrieves a value that you want to protect via locking
1246 * @param timeout - millis until giveup on getting the lock
1247 * @return whether the lock was awarded
1248 * @throws InterruptedException
1249 */
1250 public boolean tryReadLockOnKey(Object key, long timeout) throws InterruptedException;
1251
1252 /***
1253 * Try to get a write lock on a given key. If can't get it in timeout millis then
1254 * return a boolean telling that it didn't get the lock
1255 *
1256 * @param key - The key that retrieves a value that you want to protect via locking
1257 * @param timeout - millis until giveup on getting the lock
1258 * @return whether the lock was awarded
1259 * @throws InterruptedException
1260 */
1261 public boolean tryWriteLockOnKey(Object key, long timeout) throws InterruptedException;
1262
1263 /***
1264 * Release a held read lock for the passed in key
1265 *
1266 * @param key - The key that retrieves a value that you want to protect via locking
1267 */
1268 public void releaseReadLockOnKey(Object key);
1269
1270 /***
1271 * Release a held write lock for the passed in key
1272 *
1273 * @param key - The key that retrieves a value that you want to protect via locking
1274 */
1275 public void releaseWriteLockOnKey(Object key);
1276
1277 /***
1278 * Returns true if a read lock for the key is held by the current thread
1279 *
1280 * @param key
1281 * @return true if a read lock for the key is held by the current thread
1282 */
1283 boolean isReadLockedByCurrentThread(Object key);
1284
1285 /***
1286 * Returns true if a write lock for the key is held by the current thread
1287 *
1288 * @param key
1289 * @return true if a write lock for the key is held by the current thread
1290 */
1291 boolean isWriteLockedByCurrentThread(Object key);
1292
1293 /***
1294 * Returns true if at least one node in the cluster is in bulk-load mode. Returns false otherwise.
1295 * <p />
1296 * NOTE: if {@link #isNodeBulkLoadEnabled()} returns true, this method will always return true.
1297 * Applies to caches clustered with Terracotta only.
1298 *
1299 * @throws UnsupportedOperationException if the cache is not clustered with Terracotta
1300 * @return true if the cache is in bulk-load mode cluster-wide, false otherwise
1301 */
1302 public boolean isClusterBulkLoadEnabled() throws UnsupportedOperationException, TerracottaNotRunningException;
1303
1304 /***
1305 * Returns true if the current node is in bulk-load mode. Returns false otherwise.
1306 * <p />
1307 * NOTE: if this method returns true, {@link #isClusterBulkLoadEnabled()} method will always return true.
1308 * Applies to caches clustered with Terracotta only.
1309 *
1310 * @throws UnsupportedOperationException if the cache is not clustered with Terracotta
1311 * @return true if the cache is in coherent mode cluster-wide, false otherwise
1312 */
1313 public boolean isNodeBulkLoadEnabled() throws UnsupportedOperationException, TerracottaNotRunningException;
1314
1315 /***
1316 * Enable/disable bulk-load mode in this node for this cache.
1317 * Calling {@code setBulkLoadEnabled(true)} when the cache is already in bulk-load mode or
1318 * calling {@code setBulkLoadEnabled(false)} when already NOT in bulk-load mode will be a no-op.
1319 * <p />
1320 * Applies to caches clustered with Terracotta only.
1321 * <p />
1322 * When using Terracotta clustered caches with nonstop enabled, the timeout used by this method is
1323 * {@link NonstopConfiguration#getBulkOpsTimeoutMultiplyFactor()} times the timeout value in the nonstop config.
1324 *
1325 * @param enabledBulkLoad
1326 * true enables bulk-load, false disables it if not already disabled
1327 * @throws UnsupportedOperationException if the cache is not clustered with Terracotta
1328 */
1329 public void setNodeBulkLoadEnabled(boolean enabledBulkLoad) throws UnsupportedOperationException, TerracottaNotRunningException;
1330
1331 /***
1332 * This method waits until all the connected nodes have disabled bulk-load. Or in other words, calling this method
1333 * will block until all connected nodes in the cluster disables bulk-load. If none of the nodes did not enable bulk-load
1334 * this method will return immediately
1335 * <p />
1336 * Applies to caches clustered with Terracotta only.
1337 * @throws UnsupportedOperationException if the cache is not clustered with Terracotta
1338 */
1339 public void waitUntilClusterBulkLoadComplete() throws UnsupportedOperationException, TerracottaNotRunningException;
1340
1341 }