001: /**
002: * Copyright 2003-2007 Luck Consulting Pty Ltd
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */package net.sf.ehcache;
016:
017: import net.sf.ehcache.event.RegisteredEventListeners;
018: import net.sf.ehcache.store.MemoryStoreEvictionPolicy;
019: import net.sf.ehcache.bootstrap.BootstrapCacheLoader;
020: import net.sf.ehcache.config.CacheConfiguration;
021: import net.sf.ehcache.extension.CacheExtension;
022: import net.sf.ehcache.exceptionhandler.CacheExceptionHandler;
023: import net.sf.ehcache.loader.CacheLoader;
024:
025: import java.io.Serializable;
026: import java.util.List;
027: import java.util.Map;
028: import java.util.Collection;
029:
030: /**
031: * An interface for Ehcache.
032: * <p/>
033: * Ehcache is the central interface. Caches have {@link Element}s and are managed
034: * by the {@link CacheManager}. The Cache performs logical actions. It delegates physical
035: * implementations to its {@link net.sf.ehcache.store.Store}s.
036: * <p/>
037: * A reference to an EhCache can be obtained through the {@link CacheManager}. An Ehcache thus obtained
038: * is guaranteed to have status {@link Status#STATUS_ALIVE}. This status is checked for any method which
039: * throws {@link IllegalStateException} and the same thrown if it is not alive. This would normally
040: * happen if a call is made after {@link CacheManager#shutdown} is invoked.
041: * <p/>
042: * Statistics on cache usage are collected and made available through public methods.
043: *
044: * @author Greg Luck
045: * @version $Id: Ehcache.java 581 2008-02-20 10:09:03Z gregluck $
046: */
047: public interface Ehcache extends Cloneable {
048: /**
049: * Put an element in the cache.
050: * <p/>
051: * Resets the access statistics on the element, which would be the case if it has previously been
052: * gotten from a cache, and is now being put back.
053: * <p/>
054: * Also notifies the CacheEventListener that:
055: * <ul>
056: * <li>the element was put, but only if the Element was actually put.
057: * <li>if the element exists in the cache, that an update has occurred, even if the element would be expired
058: * if it was requested
059: * </ul>
060: *
061: * @param element An object. If Serializable it can fully participate in replication and the DiskStore.
062: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
063: * @throws IllegalArgumentException if the element is null
064: * @throws CacheException
065: */
066: void put(Element element) throws IllegalArgumentException,
067: IllegalStateException, CacheException;
068:
069: /**
070: * Put an element in the cache.
071: * <p/>
072: * Resets the access statistics on the element, which would be the case if it has previously been
073: * gotten from a cache, and is now being put back.
074: * <p/>
075: * Also notifies the CacheEventListener that:
076: * <ul>
077: * <li>the element was put, but only if the Element was actually put.
078: * <li>if the element exists in the cache, that an update has occurred, even if the element would be expired
079: * if it was requested
080: * </ul>
081: *
082: * @param element An object. If Serializable it can fully participate in replication and the DiskStore.
083: * @param doNotNotifyCacheReplicators whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a
084: * further notification to doNotNotifyCacheReplicators cache peers
085: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
086: * @throws IllegalArgumentException if the element is null
087: */
088: void put(Element element, boolean doNotNotifyCacheReplicators)
089: throws IllegalArgumentException, IllegalStateException,
090: CacheException;
091:
092: /**
093: * Put an element in the cache, without updating statistics, or updating listeners. This is meant to be used
094: * in conjunction with {@link #getQuiet}
095: *
096: * @param element An object. If Serializable it can fully participate in replication and the DiskStore.
097: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
098: * @throws IllegalArgumentException if the element is null
099: */
100: void putQuiet(Element element) throws IllegalArgumentException,
101: IllegalStateException, CacheException;
102:
103: /**
104: * Gets an element from the cache. Updates Element Statistics
105: * <p/>
106: * Note that the Element's lastAccessTime is always the time of this get.
107: * Use {@link #getQuiet(Object)} to peak into the Element to see its last access time with get
108: *
109: * @param key a serializable value
110: * @return the element, or null, if it does not exist.
111: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
112: * @see #isExpired
113: */
114: Element get(Serializable key) throws IllegalStateException,
115: CacheException;
116:
117: /**
118: * Gets an element from the cache. Updates Element Statistics
119: * <p/>
120: * Note that the Element's lastAccessTime is always the time of this get.
121: * Use {@link #getQuiet(Object)} to peak into the Element to see its last access time with get
122: *
123: * @param key an Object value
124: * @return the element, or null, if it does not exist.
125: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
126: * @see #isExpired
127: * @since 1.2
128: */
129: Element get(Object key) throws IllegalStateException,
130: CacheException;
131:
132: /**
133: * Gets an element from the cache, without updating Element statistics. Cache statistics are
134: * still updated.
135: * <p/>
136: *
137: * @param key a serializable value
138: * @return the element, or null, if it does not exist.
139: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
140: * @see #isExpired
141: */
142: Element getQuiet(Serializable key) throws IllegalStateException,
143: CacheException;
144:
145: /**
146: * Gets an element from the cache, without updating Element statistics. Cache statistics are
147: * also not updated.
148: * <p/>
149: *
150: * @param key a serializable value
151: * @return the element, or null, if it does not exist.
152: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
153: * @see #isExpired
154: * @since 1.2
155: */
156: Element getQuiet(Object key) throws IllegalStateException,
157: CacheException;
158:
159: /**
160: * Returns a list of all elements in the cache, whether or not they are expired.
161: * <p/>
162: * The returned keys are unique and can be considered a set.
163: * <p/>
164: * The List returned is not live. It is a copy.
165: * <p/>
166: * The time taken is O(n). On a single cpu 1.8Ghz P4, approximately 8ms is required
167: * for each 1000 entries.
168: *
169: * @return a list of {@link Object} keys
170: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
171: */
172: List getKeys() throws IllegalStateException, CacheException;
173:
174: /**
175: * Returns a list of all elements in the cache. Only keys of non-expired
176: * elements are returned.
177: * <p/>
178: * The returned keys are unique and can be considered a set.
179: * <p/>
180: * The List returned is not live. It is a copy.
181: * <p/>
182: * The time taken is O(n), where n is the number of elements in the cache. On
183: * a 1.8Ghz P4, the time taken is approximately 200ms per 1000 entries. This method
184: * is not synchronized, because it relies on a non-live list returned from {@link #getKeys()}
185: * , which is synchronised, and which takes 8ms per 1000 entries. This way
186: * cache liveness is preserved, even if this method is very slow to return.
187: * <p/>
188: * Consider whether your usage requires checking for expired keys. Because
189: * this method takes so long, depending on cache settings, the list could be
190: * quite out of date by the time you get it.
191: *
192: * @return a list of {@link Object} keys
193: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
194: */
195: List getKeysWithExpiryCheck() throws IllegalStateException,
196: CacheException;
197:
198: /**
199: * Returns a list of all elements in the cache, whether or not they are expired.
200: * <p/>
201: * The returned keys are not unique and may contain duplicates. If the cache is only
202: * using the memory store, the list will be unique. If the disk store is being used
203: * as well, it will likely contain duplicates, because of the internal store design.
204: * <p/>
205: * The List returned is not live. It is a copy.
206: * <p/>
207: * The time taken is O(log n). On a single cpu 1.8Ghz P4, approximately 6ms is required
208: * for 1000 entries and 36 for 50000.
209: * <p/>
210: * This is the fastest getKeys method
211: *
212: * @return a list of {@link Object} keys
213: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
214: */
215: List getKeysNoDuplicateCheck() throws IllegalStateException;
216:
217: /**
218: * Removes an {@link net.sf.ehcache.Element} from the Cache. This also removes it from any
219: * stores it may be in.
220: * <p/>
221: * Also notifies the CacheEventListener after the element was removed.
222: *
223: * @param key
224: * @return true if the element was removed, false if it was not found in the cache
225: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
226: */
227: boolean remove(Serializable key) throws IllegalStateException;
228:
229: /**
230: * Removes an {@link net.sf.ehcache.Element} from the Cache. This also removes it from any
231: * stores it may be in.
232: * <p/>
233: * Also notifies the CacheEventListener after the element was removed, but only if an Element
234: * with the key actually existed.
235: *
236: * @param key
237: * @return true if the element was removed, false if it was not found in the cache
238: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
239: * @since 1.2
240: */
241: boolean remove(Object key) throws IllegalStateException;
242:
243: /**
244: * Removes an {@link net.sf.ehcache.Element} from the Cache. This also removes it from any
245: * stores it may be in.
246: * <p/>
247: * Also notifies the CacheEventListener after the element was removed, but only if an Element
248: * with the key actually existed.
249: *
250: * @param key
251: * @param doNotNotifyCacheReplicators whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a
252: * further notification to doNotNotifyCacheReplicators cache peers
253: * @return true if the element was removed, false if it was not found in the cache
254: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
255: * @noinspection SameParameterValue
256: */
257: boolean remove(Serializable key, boolean doNotNotifyCacheReplicators)
258: throws IllegalStateException;
259:
260: /**
261: * Removes an {@link net.sf.ehcache.Element} from the Cache. This also removes it from any
262: * stores it may be in.
263: * <p/>
264: * Also notifies the CacheEventListener after the element was removed, but only if an Element
265: * with the key actually existed.
266: *
267: * @param key
268: * @param doNotNotifyCacheReplicators whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a
269: * further notification to doNotNotifyCacheReplicators cache peers
270: * @return true if the element was removed, false if it was not found in the cache
271: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
272: */
273: boolean remove(Object key, boolean doNotNotifyCacheReplicators)
274: throws IllegalStateException;
275:
276: /**
277: * Removes an {@link net.sf.ehcache.Element} from the Cache, without notifying listeners. This also removes it from any
278: * stores it may be in.
279: * <p/>
280: *
281: * @param key
282: * @return true if the element was removed, false if it was not found in the cache
283: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
284: */
285: boolean removeQuiet(Serializable key) throws IllegalStateException;
286:
287: /**
288: * Removes an {@link net.sf.ehcache.Element} from the Cache, without notifying listeners. This also removes it from any
289: * stores it may be in.
290: * <p/>
291: *
292: * @param key
293: * @return true if the element was removed, false if it was not found in the cache
294: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
295: * @since 1.2
296: */
297: boolean removeQuiet(Object key) throws IllegalStateException;
298:
299: /**
300: * Removes all cached items.
301: *
302: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
303: */
304: void removeAll() throws IllegalStateException, CacheException;
305:
306: /**
307: * Removes all cached items.
308: *
309: * @param doNotNotifyCacheReplicators whether the put is coming from a doNotNotifyCacheReplicators cache peer,
310: * in which case this put should not initiate a further notification to doNotNotifyCacheReplicators cache peers
311: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
312: */
313: void removeAll(boolean doNotNotifyCacheReplicators)
314: throws IllegalStateException, CacheException;
315:
316: /**
317: * Flushes all cache items from memory to the disk store, and from the DiskStore to disk.
318: *
319: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
320: */
321: void flush() throws IllegalStateException, CacheException;
322:
323: /**
324: * Gets the size of the cache. This is a subtle concept. See below.
325: * <p/>
326: * The size is the number of {@link net.sf.ehcache.Element}s in the {@link net.sf.ehcache.store.MemoryStore} plus
327: * the number of {@link net.sf.ehcache.Element}s in the {@link net.sf.ehcache.store.DiskStore}.
328: * <p/>
329: * This number is the actual number of elements, including expired elements that have
330: * not been removed.
331: * <p/>
332: * Expired elements are removed from the the memory store when
333: * getting an expired element, or when attempting to spool an expired element to
334: * disk.
335: * <p/>
336: * Expired elements are removed from the disk store when getting an expired element,
337: * or when the expiry thread runs, which is once every five minutes.
338: * <p/>
339: * To get an exact size, which would exclude expired elements, use {@link #getKeysWithExpiryCheck()}.size(),
340: * although see that method for the approximate time that would take.
341: * <p/>
342: * To get a very fast result, use {@link #getKeysNoDuplicateCheck()}.size(). If the disk store
343: * is being used, there will be some duplicates.
344: *
345: * @return The size value
346: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
347: */
348: int getSize() throws IllegalStateException, CacheException;
349:
350: /**
351: * Gets the size of the memory store for this cache
352: * <p/>
353: * Warning: This method can be very expensive to run. Allow approximately 1 second
354: * per 1MB of entries. Running this method could create liveness problems
355: * because the object lock is held for a long period
356: * <p/>
357: *
358: * @return the approximate size of the memory store in bytes
359: * @throws IllegalStateException
360: */
361: long calculateInMemorySize() throws IllegalStateException,
362: CacheException;
363:
364: /**
365: * Returns the number of elements in the memory store.
366: *
367: * @return the number of elements in the memory store
368: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
369: */
370: long getMemoryStoreSize() throws IllegalStateException;
371:
372: /**
373: * Returns the number of elements in the disk store.
374: *
375: * @return the number of elements in the disk store.
376: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
377: */
378: int getDiskStoreSize() throws IllegalStateException;
379:
380: /**
381: * Gets the status attribute of the Cache.
382: *
383: * @return The status value from the Status enum class
384: */
385: Status getStatus();
386:
387: /**
388: * Gets the cache name.
389: */
390: String getName();
391:
392: /**
393: * Sets the cache name which will name.
394: *
395: * @param name the name of the cache. Should not be null.
396: */
397: void setName(String name);
398:
399: /**
400: * Gets timeToIdleSeconds.
401: */
402: long getTimeToIdleSeconds();
403:
404: /**
405: * Gets timeToLiveSeconds.
406: */
407: long getTimeToLiveSeconds();
408:
409: /**
410: * Are elements eternal.
411: */
412: boolean isEternal();
413:
414: /**
415: * Does the overflow go to disk.
416: */
417: boolean isOverflowToDisk();
418:
419: /**
420: * Gets the maximum number of elements to hold in memory.
421: */
422: int getMaxElementsInMemory();
423:
424: /**
425: * Gets the maximum number of elements to hold on Disk.
426: */
427: int getMaxElementsOnDisk();
428:
429: /**
430: * The policy used to evict elements from the {@link net.sf.ehcache.store.MemoryStore}.
431: * This can be one of:
432: * <ol>
433: * <li>LRU - least recently used
434: * <li>LFU - least frequently used
435: * <li>FIFO - first in first out, the oldest element by creation time
436: * </ol>
437: * The default value is LRU
438: *
439: * @since 1.2
440: */
441: MemoryStoreEvictionPolicy getMemoryStoreEvictionPolicy();
442:
443: /**
444: * Returns a {@link String} representation of {@link net.sf.ehcache.Cache}.
445: */
446: String toString();
447:
448: /**
449: * Checks whether this cache element has expired.
450: * <p/>
451: * The element is expired if:
452: * <ol>
453: * <li> the idle time is non-zero and has elapsed, unless the cache is eternal; or
454: * <li> the time to live is non-zero and has elapsed, unless the cache is eternal; or
455: * <li> the value of the element is null.
456: * </ol>
457: *
458: * @param element the element to check
459: * @return true if it has expired
460: * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
461: * @throws NullPointerException if the element is null
462: */
463: boolean isExpired(Element element) throws IllegalStateException,
464: NullPointerException;
465:
466: /**
467: * Clones a cache. This is only legal if the cache has not been
468: * initialized. At that point only primitives have been set and no
469: * {@link net.sf.ehcache.store.MemoryStore} or {@link net.sf.ehcache.store.DiskStore} has been created.
470: * <p/>
471: * A new, empty, RegisteredEventListeners is created on clone.
472: * <p/>
473: *
474: * @return an object of type {@link net.sf.ehcache.Cache}
475: * @throws CloneNotSupportedException
476: */
477: Object clone() throws CloneNotSupportedException;
478:
479: /**
480: * @return true if the cache overflows to disk and the disk is persistent between restarts
481: */
482: boolean isDiskPersistent();
483:
484: /**
485: * @return the interval between runs
486: * of the expiry thread, where it checks the disk store for expired elements. It is not the
487: * the timeToLiveSeconds.
488: */
489: long getDiskExpiryThreadIntervalSeconds();
490:
491: /**
492: * Use this to access the service in order to register and unregister listeners
493: *
494: * @return the RegisteredEventListeners instance for this cache.
495: */
496: RegisteredEventListeners getCacheEventNotificationService();
497:
498: /**
499: * Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.
500: *
501: * @return true if an element matching the key is found in memory
502: */
503: boolean isElementInMemory(Serializable key);
504:
505: /**
506: * Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.
507: *
508: * @return true if an element matching the key is found in memory
509: * @since 1.2
510: */
511: boolean isElementInMemory(Object key);
512:
513: /**
514: * Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.
515: *
516: * @return true if an element matching the key is found in the diskStore
517: */
518: boolean isElementOnDisk(Serializable key);
519:
520: /**
521: * Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.
522: *
523: * @return true if an element matching the key is found in the diskStore
524: * @since 1.2
525: */
526: boolean isElementOnDisk(Object key);
527:
528: /**
529: * The GUID for this cache instance can be used to determine whether two cache instance references
530: * are pointing to the same cache.
531: *
532: * @return the globally unique identifier for this cache instance. This is guaranteed to be unique.
533: * @since 1.2
534: */
535: String getGuid();
536:
537: /**
538: * Gets the CacheManager managing this cache. For a newly created cache this will be null until
539: * it has been added to a CacheManager.
540: *
541: * @return the manager or null if there is none
542: */
543: CacheManager getCacheManager();
544:
545: /**
546: * Resets statistics counters back to 0.
547: */
548: void clearStatistics();
549:
550: /**
551: * Accurately measuring statistics can be expensive. Returns the current accuracy setting.
552: *
553: * @return one of {@link Statistics#STATISTICS_ACCURACY_BEST_EFFORT}, {@link Statistics#STATISTICS_ACCURACY_GUARANTEED}, {@link Statistics#STATISTICS_ACCURACY_NONE}
554: */
555: public int getStatisticsAccuracy();
556:
557: /**
558: * Sets the statistics accuracy.
559: *
560: * @param statisticsAccuracy one of {@link Statistics#STATISTICS_ACCURACY_BEST_EFFORT}, {@link Statistics#STATISTICS_ACCURACY_GUARANTEED}, {@link Statistics#STATISTICS_ACCURACY_NONE}
561: */
562: public void setStatisticsAccuracy(int statisticsAccuracy);
563:
564: /**
565: * Causes all elements stored in the Cache to be synchronously checked for expiry, and if expired, evicted.
566: */
567: void evictExpiredElements();
568:
569: /**
570: * An inexpensive check to see if the key exists in the cache.
571: *
572: * @param key the key to check for
573: * @return true if an Element matching the key is found in the cache. No assertions are made about the state of the Element.
574: */
575: boolean isKeyInCache(Object key);
576:
577: /**
578: * An extremely expensive check to see if the value exists in the cache.
579: *
580: * @param value to check for
581: * @return true if an Element matching the key is found in the cache. No assertions are made about the state of the Element.
582: */
583: boolean isValueInCache(Object value);
584:
585: /**
586: * Gets an immutable Statistics object representing the Cache statistics at the time. How the statistics are calculated
587: * depends on the statistics accuracy setting. The only aspect of statistics sensitive to the accuracy setting is
588: * object size. How that is calculated is discussed below.
589: * <h3>Best Effort Size</h3>
590: * This result is returned when the statistics accuracy setting is {@link Statistics#STATISTICS_ACCURACY_BEST_EFFORT}.
591: * <p/>
592: * The size is the number of {@link Element}s in the {@link net.sf.ehcache.store.MemoryStore} plus
593: * the number of {@link Element}s in the {@link net.sf.ehcache.store.DiskStore}.
594: * <p/>
595: * This number is the actual number of elements, including expired elements that have
596: * not been removed. Any duplicates between stores are accounted for.
597: * <p/>
598: * Expired elements are removed from the the memory store when
599: * getting an expired element, or when attempting to spool an expired element to
600: * disk.
601: * <p/>
602: * Expired elements are removed from the disk store when getting an expired element,
603: * or when the expiry thread runs, which is once every five minutes.
604: * <p/>
605: * <h3>Guaranteed Accuracy Size</h3>
606: * This result is returned when the statistics accuracy setting is {@link Statistics#STATISTICS_ACCURACY_GUARANTEED}.
607: * <p/>
608: * This method accounts for elements which might be expired or duplicated between stores. It take approximately
609: * 200ms per 1000 elements to execute.
610: * <h3>Fast but non-accurate Size</h3>
611: * This result is returned when the statistics accuracy setting is {@link Statistics#STATISTICS_ACCURACY_NONE}.
612: * <p/>
613: * The number given may contain expired elements. In addition if the DiskStore is used it may contain some double
614: * counting of elements. It takes 6ms for 1000 elements to execute. Time to execute is O(log n). 50,000 elements take
615: * 36ms.
616: *
617: * @return the number of elements in the ehcache, with a varying degree of accuracy, depending on accuracy setting.
618: * @throws IllegalStateException if the cache is not {@link Status#STATUS_ALIVE}
619: */
620: Statistics getStatistics() throws IllegalStateException;
621:
622: /**
623: * Sets the CacheManager
624: *
625: * @param cacheManager the CacheManager for this cache to use.
626: */
627: void setCacheManager(CacheManager cacheManager);
628:
629: /**
630: * Accessor for the BootstrapCacheLoader associated with this cache. For testing purposes.
631: *
632: * @return the BootstrapCacheLoader to use
633: */
634: BootstrapCacheLoader getBootstrapCacheLoader();
635:
636: /**
637: * Sets the bootstrap cache loader.
638: *
639: * @param bootstrapCacheLoader the loader to be used
640: * @throws CacheException if this method is called after the cache is initialized
641: */
642: void setBootstrapCacheLoader(
643: BootstrapCacheLoader bootstrapCacheLoader)
644: throws CacheException;
645:
646: /**
647: * DiskStore paths can conflict between CacheManager instances. This method allows the path to be changed.
648: *
649: * @param diskStorePath the new path to be used.
650: * @throws CacheException if this method is called after the cache is initialized
651: */
652: void setDiskStorePath(String diskStorePath) throws CacheException;
653:
654: /**
655: * Newly created caches do not have a {@link net.sf.ehcache.store.MemoryStore} or a {@link net.sf.ehcache.store.DiskStore}.
656: * <p/>
657: * This method creates those and makes the cache ready to accept elements
658: */
659: void initialise();
660:
661: /**
662: * Bootstrap command. This must be called after the Cache is intialised, during
663: * CacheManager initialisation. If loads are synchronous, they will complete before the CacheManager
664: * initialise completes, otherwise they will happen in the background.
665: */
666: void bootstrap();
667:
668: /**
669: * Flushes all cache items from memory to auxilliary caches and close the auxilliary caches.
670: * <p/>
671: * Should be invoked only by CacheManager.
672: *
673: * @throws IllegalStateException if the cache is not {@link Status#STATUS_ALIVE}
674: */
675: public void dispose() throws IllegalStateException;
676:
677: /**
678: * Gets the cache configuration this cache was created with.
679: * <p/>
680: * Things like listeners that are added dynamically are excluded.
681: */
682: CacheConfiguration getCacheConfiguration();
683:
684: /**
685: * Register a {@link CacheExtension} with the cache. It will then be tied into the cache lifecycle.
686: * <p/>
687: * If the CacheExtension is not initialised, initialise it.
688: */
689: public void registerCacheExtension(CacheExtension cacheExtension);
690:
691: /**
692: * Unregister a {@link CacheExtension} with the cache. It will then be detached from the cache lifecycle.
693: */
694: public void unregisterCacheExtension(CacheExtension cacheExtension);
695:
696: /**
697: * The average get time in ms.
698: */
699: public float getAverageGetTime();
700:
701: /**
702: * Sets an ExceptionHandler on the Cache. If one is already set, it is overwritten.
703: */
704: public void setCacheExceptionHandler(
705: CacheExceptionHandler cacheExceptionHandler);
706:
707: /**
708: * Sets an ExceptionHandler on the Cache. If one is already set, it is overwritten.
709: */
710: public CacheExceptionHandler getCacheExceptionHandler();
711:
712: /**
713: * Setter for the CacheLoader. Changing the CacheLoader takes immediate effect.
714: *
715: * @param cacheLoader the loader to dynamically load new cache entries
716: */
717: public void setCacheLoader(CacheLoader cacheLoader);
718:
719: /**
720: * Gets the CacheLoader registered in this cache
721: *
722: * @return the loader, or null if there is none
723: */
724: public CacheLoader getCacheLoader();
725:
726: /**
727: * Warning: This method is related to the JSR107 specification, which is in draft. It is subject to change without notice.
728: * <p/>
729: * This method will return, from the cache, the object associated with
730: * the argument "key".
731: * <p/>
732: * If the object is not in the cache, the associated
733: * cache loader will be called. That is either the CacheLoader passed in, or if null, the one associated with the cache.
734: * If both are null, no load is performed and null is returned.
735: * <p/>
736: * Because this method may take a long time to complete, it is not synchronized. The underlying cache operations
737: * are synchronized.
738: *
739: * @param key key whose associated value is to be returned.
740: * @param loader the override loader to use. If null, the cache's default loader will be used
741: * @param loaderArgument an argument to pass to the CacheLoader.
742: * @return an element if it existed or could be loaded, otherwise null
743: * @throws CacheException
744: */
745: public Element getWithLoader(Object key, CacheLoader loader,
746: Object loaderArgument) throws CacheException;
747:
748: /**
749: * Warning: This method is related to the JSR107 specification, which is in draft. It is subject to change without notice.
750: * <p/>
751: * The getAll method will return, from the cache, a Map of the objects associated with the Collection of keys in argument "keys".
752: * If the objects are not in the cache, the associated cache loader will be called. If no loader is associated with an object,
753: * a null is returned. If a problem is encountered during the retrieving or loading of the objects, an exception will be thrown.
754: * If the "arg" argument is set, the arg object will be passed to the CacheLoader.loadAll method. The cache will not dereference
755: * 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
756: * is permitted, however, the get method will not distinguish returning a null stored in the cache and not finding the object in
757: * the cache. In both cases a null is returned.
758: * <p/>
759: * <p/>
760: * Note. If the getAll exceeds the maximum cache size, the returned map will necessarily be less than the number specified.
761: * <p/>
762: * Because this method may take a long time to complete, it is not synchronized. The underlying cache operations
763: * are synchronized.
764: * <p/>
765: * The constructs package provides similar functionality using the
766: * decorator {@link net.sf.ehcache.constructs.blocking.SelfPopulatingCache}
767: * @param keys a collection of keys to be returned/loaded
768: * @param loaderArgument an argument to pass to the CacheLoader.
769: * @return a Map populated from the Cache. If there are no elements, an empty Map is returned.
770: * @throws CacheException
771: */
772: public Map getAllWithLoader(Collection keys, Object loaderArgument)
773: throws CacheException;
774:
775: /**
776: * Warning: This method is related to the JSR107 specification, which is in draft. It is subject to change without notice.
777: * <p/>
778: * The load method provides a means to "pre load" the cache. This method will, asynchronously, load the specified
779: * object into the cache using the associated cacheloader. If the object already exists in the cache, no action is
780: * taken. If no loader is associated with the object, no object will be loaded into the cache. If a problem is
781: * encountered during the retrieving or loading of the object, an exception should be logged. If the "arg" argument
782: * is set, the arg object will be passed to the CacheLoader.load method. The cache will not dereference the object.
783: * If no "arg" value is provided a null will be passed to the load method. The storing of null values in the cache
784: * is permitted, however, the get method will not distinguish returning a null stored in the cache and not finding
785: * the object in the cache. In both cases a null is returned.
786: * <p/>
787: * The Ehcache native API provides similar functionality to loaders using the
788: * decorator {@link net.sf.ehcache.constructs.blocking.SelfPopulatingCache}
789: *
790: * @param key key whose associated value to be loaded using the associated cacheloader if this cache doesn't contain it.
791: * @throws CacheException
792: */
793: public void load(final Object key) throws CacheException;
794:
795: /**
796: * Warning: This method is related to the JSR107 specification, which is in draft. It is subject to change without notice.
797: * <p/>
798: * The loadAll method provides a means to "pre load" objects into the cache. This method will, asynchronously, load
799: * the specified objects into the cache using the associated cache loader. If the an object already exists in the
800: * cache, no action is taken. If no loader is associated with the object, no object will be loaded into the cache.
801: * If a problem is encountered during the retrieving or loading of the objects, an exception (to be defined)
802: * should be logged. The getAll method will return, from the cache, a Map of the objects associated with the
803: * Collection of keys in argument "keys". If the objects are not in the cache, the associated cache loader will be
804: * called. If no loader is associated with an object, a null is returned. If a problem is encountered during the
805: * retrieving or loading of the objects, an exception (to be defined) will be thrown. If the "arg" argument is set,
806: * the arg object will be passed to the CacheLoader.loadAll method. The cache will not dereference the object.
807: * If no "arg" value is provided a null will be passed to the loadAll method.
808: * <p/>
809: * keys - collection of the keys whose associated values to be loaded into this cache by using the associated
810: * cacheloader if this cache doesn't contain them.
811: * <p/>
812: * The Ehcache native API provides similar functionality to loaders using the
813: * decorator {@link net.sf.ehcache.constructs.blocking.SelfPopulatingCache}
814: */
815: public void loadAll(final Collection keys, final Object argument)
816: throws CacheException;
817:
818: }
|