1 /**
2 * Copyright 2003-2007 Greg Luck
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 net.sf.ehcache.event.RegisteredEventListeners;
20 import net.sf.ehcache.store.MemoryStoreEvictionPolicy;
21 import net.sf.ehcache.bootstrap.BootstrapCacheLoader;
22 import net.sf.ehcache.config.CacheConfiguration;
23
24 import java.io.Serializable;
25 import java.util.List;
26
27 /**
28 * An interface for Ehcache.
29 * <p/>
30 * Ehcache is the central interface. Caches have {@link Element}s and are managed
31 * by the {@link CacheManager}. The Cache performs logical actions. It delegates physical
32 * implementations to its {@link net.sf.ehcache.store.Store}s.
33 * <p/>
34 * A reference to an EhCache can be obtained through the {@link CacheManager}. An Ehcache thus obtained
35 * is guaranteed to have status {@link Status#STATUS_ALIVE}. This status is checked for any method which
36 * throws {@link IllegalStateException} and the same thrown if it is not alive. This would normally
37 * happen if a call is made after {@link CacheManager#shutdown} is invoked.
38 * <p/>
39 * Statistics on cache usage are collected and made available through public methods.
40 *
41 * @author Greg Luck
42 * @version $Id: Ehcache.java 512 2007-07-10 09:18:45Z gregluck $
43 */
44 public interface Ehcache extends Cloneable {
45 /**
46 * Put an element in the cache.
47 * <p/>
48 * Resets the access statistics on the element, which would be the case if it has previously been
49 * gotten from a cache, and is now being put back.
50 * <p/>
51 * Also notifies the CacheEventListener that:
52 * <ul>
53 * <li>the element was put, but only if the Element was actually put.
54 * <li>if the element exists in the cache, that an update has occurred, even if the element would be expired
55 * if it was requested
56 * </ul>
57 *
58 * @param element An object. If Serializable it can fully participate in replication and the DiskStore.
59 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
60 * @throws IllegalArgumentException if the element is null
61 * @throws CacheException
62 */
63 void put(Element element) throws IllegalArgumentException, IllegalStateException,
64 CacheException;
65
66 /**
67 * Put an element in the cache.
68 * <p/>
69 * Resets the access statistics on the element, which would be the case if it has previously been
70 * gotten from a cache, and is now being put back.
71 * <p/>
72 * Also notifies the CacheEventListener that:
73 * <ul>
74 * <li>the element was put, but only if the Element was actually put.
75 * <li>if the element exists in the cache, that an update has occurred, even if the element would be expired
76 * if it was requested
77 * </ul>
78 *
79 * @param element An object. If Serializable it can fully participate in replication and the DiskStore.
80 * @param doNotNotifyCacheReplicators whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a
81 * further notification to doNotNotifyCacheReplicators cache peers
82 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
83 * @throws IllegalArgumentException if the element is null
84 */
85 void put(Element element, boolean doNotNotifyCacheReplicators) throws IllegalArgumentException,
86 IllegalStateException,
87 CacheException;
88
89 /**
90 * Put an element in the cache, without updating statistics, or updating listeners. This is meant to be used
91 * in conjunction with {@link #getQuiet}
92 *
93 * @param element An object. If 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 IllegalArgumentException if the element is null
96 */
97 void putQuiet(Element element) throws IllegalArgumentException, IllegalStateException,
98 CacheException;
99
100 /**
101 * Gets an element from the cache. Updates Element Statistics
102 * <p/>
103 * Note that the Element's lastAccessTime is always the time of this get.
104 * Use {@link #getQuiet(Object)} to peak into the Element to see its last access time with get
105 *
106 * @param key a serializable value
107 * @return the element, or null, if it does not exist.
108 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
109 * @see #isExpired
110 */
111 Element get(Serializable key) throws IllegalStateException, CacheException;
112
113 /**
114 * Gets an element from the cache. Updates Element Statistics
115 * <p/>
116 * Note that the Element's lastAccessTime is always the time of this get.
117 * Use {@link #getQuiet(Object)} to peak into the Element to see its last access time with get
118 *
119 * @param key an Object value
120 * @return the element, or null, if it does not exist.
121 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
122 * @see #isExpired
123 * @since 1.2
124 */
125 Element get(Object key) throws IllegalStateException, CacheException;
126
127 /**
128 * Gets an element from the cache, without updating Element statistics. Cache statistics are
129 * still updated.
130 * <p/>
131 *
132 * @param key a serializable value
133 * @return the element, or null, if it does not exist.
134 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
135 * @see #isExpired
136 */
137 Element getQuiet(Serializable key) throws IllegalStateException, CacheException;
138
139 /**
140 * Gets an element from the cache, without updating Element statistics. Cache statistics are
141 * also not updated.
142 * <p/>
143 *
144 * @param key a serializable value
145 * @return the element, or null, if it does not exist.
146 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
147 * @see #isExpired
148 * @since 1.2
149 */
150 Element getQuiet(Object key) throws IllegalStateException, CacheException;
151
152 /**
153 * Returns a list of all elements in the cache, whether or not they are expired.
154 * <p/>
155 * The returned keys are unique and can be considered a set.
156 * <p/>
157 * The List returned is not live. It is a copy.
158 * <p/>
159 * The time taken is O(n). On a single cpu 1.8Ghz P4, approximately 8ms is required
160 * for each 1000 entries.
161 *
162 * @return a list of {@link Object} keys
163 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
164 */
165 List getKeys() throws IllegalStateException, CacheException;
166
167 /**
168 * Returns a list of all elements in the cache. Only keys of non-expired
169 * elements are returned.
170 * <p/>
171 * The returned keys are unique and can be considered a set.
172 * <p/>
173 * The List returned is not live. It is a copy.
174 * <p/>
175 * The time taken is O(n), where n is the number of elements in the cache. On
176 * a 1.8Ghz P4, the time taken is approximately 200ms per 1000 entries. This method
177 * is not synchronized, because it relies on a non-live list returned from {@link #getKeys()}
178 * , which is synchronised, and which takes 8ms per 1000 entries. This way
179 * cache liveness is preserved, even if this method is very slow to return.
180 * <p/>
181 * Consider whether your usage requires checking for expired keys. Because
182 * this method takes so long, depending on cache settings, the list could be
183 * quite out of date by the time you get it.
184 *
185 * @return a list of {@link Object} keys
186 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
187 */
188 List getKeysWithExpiryCheck() throws IllegalStateException, CacheException;
189
190 /**
191 * Returns a list of all elements in the cache, whether or not they are expired.
192 * <p/>
193 * The returned keys are not unique and may contain duplicates. If the cache is only
194 * using the memory store, the list will be unique. If the disk store is being used
195 * as well, it will likely contain duplicates, because of the internal store design.
196 * <p/>
197 * The List returned is not live. It is a copy.
198 * <p/>
199 * The time taken is O(log n). On a single cpu 1.8Ghz P4, approximately 6ms is required
200 * for 1000 entries and 36 for 50000.
201 * <p/>
202 * This is the fastest getKeys method
203 *
204 * @return a list of {@link Object} keys
205 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
206 */
207 List getKeysNoDuplicateCheck() throws IllegalStateException;
208
209 /**
210 * Removes an {@link net.sf.ehcache.Element} from the Cache. This also removes it from any
211 * stores it may be in.
212 * <p/>
213 * Also notifies the CacheEventListener after the element was removed, but only if an Element
214 * with the key actually existed.
215 *
216 * @param key
217 * @return true if the element was removed, false if it was not found in the cache
218 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
219 */
220 boolean remove(Serializable key) throws IllegalStateException;
221
222 /**
223 * Removes an {@link net.sf.ehcache.Element} from the Cache. This also removes it from any
224 * stores it may be in.
225 * <p/>
226 * Also notifies the CacheEventListener after the element was removed, but only if an Element
227 * with the key actually existed.
228 *
229 * @param key
230 * @return true if the element was removed, false if it was not found in the cache
231 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
232 * @since 1.2
233 */
234 boolean remove(Object key) throws IllegalStateException;
235
236 /**
237 * Removes an {@link net.sf.ehcache.Element} from the Cache. This also removes it from any
238 * stores it may be in.
239 * <p/>
240 * Also notifies the CacheEventListener after the element was removed, but only if an Element
241 * with the key actually existed.
242 *
243 * @param key
244 * @param doNotNotifyCacheReplicators whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a
245 * further notification to doNotNotifyCacheReplicators cache peers
246 * @return true if the element was removed, false if it was not found in the cache
247 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
248 * @noinspection SameParameterValue
249 */
250 boolean remove(Serializable key, boolean doNotNotifyCacheReplicators) throws IllegalStateException;
251
252 /**
253 * Removes an {@link net.sf.ehcache.Element} from the Cache. This also removes it from any
254 * stores it may be in.
255 * <p/>
256 * Also notifies the CacheEventListener after the element was removed, but only if an Element
257 * with the key actually existed.
258 *
259 * @param key
260 * @param doNotNotifyCacheReplicators whether the put is coming from a doNotNotifyCacheReplicators cache peer, in which case this put should not initiate a
261 * further notification to doNotNotifyCacheReplicators cache peers
262 * @return true if the element was removed, false if it was not found in the cache
263 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
264 */
265 boolean remove(Object key, boolean doNotNotifyCacheReplicators) throws IllegalStateException;
266
267 /**
268 * Removes an {@link net.sf.ehcache.Element} from the Cache, without notifying listeners. This also removes it from any
269 * stores it may be in.
270 * <p/>
271 *
272 * @param key
273 * @return true if the element was removed, false if it was not found in the cache
274 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
275 */
276 boolean removeQuiet(Serializable key) throws IllegalStateException;
277
278 /**
279 * Removes an {@link net.sf.ehcache.Element} from the Cache, without notifying listeners. This also removes it from any
280 * stores it may be in.
281 * <p/>
282 *
283 * @param key
284 * @return true if the element was removed, false if it was not found in the cache
285 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
286 * @since 1.2
287 */
288 boolean removeQuiet(Object key) throws IllegalStateException;
289
290 /**
291 * Removes all cached items.
292 *
293 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
294 */
295 void removeAll() throws IllegalStateException, CacheException;
296
297 /**
298 * Removes all cached items.
299 * @param doNotNotifyCacheReplicators whether the put is coming from a doNotNotifyCacheReplicators cache peer,
300 * in which case this put should not initiate a further notification to doNotNotifyCacheReplicators cache peers
301 *
302 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
303 */
304 void removeAll(boolean doNotNotifyCacheReplicators) throws IllegalStateException, CacheException;
305
306 /**
307 * Flushes all cache items from memory to the disk store, and from the DiskStore to disk.
308 *
309 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
310 */
311 void flush() throws IllegalStateException, CacheException;
312
313 /**
314 * Gets the size of the cache. This is a subtle concept. See below.
315 * <p/>
316 * The size is the number of {@link net.sf.ehcache.Element}s in the {@link net.sf.ehcache.store.MemoryStore} plus
317 * the number of {@link net.sf.ehcache.Element}s in the {@link net.sf.ehcache.store.DiskStore}.
318 * <p/>
319 * This number is the actual number of elements, including expired elements that have
320 * not been removed.
321 * <p/>
322 * Expired elements are removed from the the memory store when
323 * getting an expired element, or when attempting to spool an expired element to
324 * disk.
325 * <p/>
326 * Expired elements are removed from the disk store when getting an expired element,
327 * or when the expiry thread runs, which is once every five minutes.
328 * <p/>
329 * To get an exact size, which would exclude expired elements, use {@link #getKeysWithExpiryCheck()}.size(),
330 * although see that method for the approximate time that would take.
331 * <p/>
332 * To get a very fast result, use {@link #getKeysNoDuplicateCheck()}.size(). If the disk store
333 * is being used, there will be some duplicates.
334 *
335 * @return The size value
336 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
337 */
338 int getSize() throws IllegalStateException, CacheException;
339
340 /**
341 * Gets the size of the memory store for this cache
342 * <p/>
343 * Warning: This method can be very expensive to run. Allow approximately 1 second
344 * per 1MB of entries. Running this method could create liveness problems
345 * because the object lock is held for a long period
346 * <p/>
347 *
348 * @return the approximate size of the memory store in bytes
349 * @throws IllegalStateException
350 */
351 long calculateInMemorySize() throws IllegalStateException, CacheException;
352
353 /**
354 * Returns the number of elements in the memory store.
355 *
356 * @return the number of elements in the memory store
357 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
358 */
359 long getMemoryStoreSize() throws IllegalStateException;
360
361 /**
362 * Returns the number of elements in the disk store.
363 *
364 * @return the number of elements in the disk store.
365 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
366 */
367 int getDiskStoreSize() throws IllegalStateException;
368
369 /**
370 * Gets the status attribute of the Cache.
371 *
372 * @return The status value from the Status enum class
373 */
374 Status getStatus();
375
376 /**
377 * Gets the cache name.
378 */
379 String getName();
380
381 /**
382 * Sets the cache name which will name.
383 *
384 * @param name the name of the cache. Should not be null.
385 */
386 void setName(String name);
387
388 /**
389 * Gets timeToIdleSeconds.
390 */
391 long getTimeToIdleSeconds();
392
393 /**
394 * Gets timeToLiveSeconds.
395 */
396 long getTimeToLiveSeconds();
397
398 /**
399 * Are elements eternal.
400 */
401 boolean isEternal();
402
403 /**
404 * Does the overflow go to disk.
405 */
406 boolean isOverflowToDisk();
407
408 /**
409 * Gets the maximum number of elements to hold in memory.
410 */
411 int getMaxElementsInMemory();
412
413 /**
414 * Gets the maximum number of elements to hold on Disk.
415 */
416 int getMaxElementsOnDisk();
417
418 /**
419 * The policy used to evict elements from the {@link net.sf.ehcache.store.MemoryStore}.
420 * This can be one of:
421 * <ol>
422 * <li>LRU - least recently used
423 * <li>LFU - least frequently used
424 * <li>FIFO - first in first out, the oldest element by creation time
425 * </ol>
426 * The default value is LRU
427 *
428 * @since 1.2
429 */
430 MemoryStoreEvictionPolicy getMemoryStoreEvictionPolicy();
431
432 /**
433 * Returns a {@link String} representation of {@link net.sf.ehcache.Cache}.
434 */
435 String toString();
436
437 /**
438 * Checks whether this cache element has expired.
439 * <p/>
440 * The element is expired if:
441 * <ol>
442 * <li> the idle time is non-zero and has elapsed, unless the cache is eternal; or
443 * <li> the time to live is non-zero and has elapsed, unless the cache is eternal; or
444 * <li> the value of the element is null.
445 * </ol>
446 *
447 * @param element the element to check
448 * @return true if it has expired
449 * @throws IllegalStateException if the cache is not {@link net.sf.ehcache.Status#STATUS_ALIVE}
450 * @throws NullPointerException if the element is null
451 */
452 boolean isExpired(Element element) throws IllegalStateException, NullPointerException;
453
454 /**
455 * Clones a cache. This is only legal if the cache has not been
456 * initialized. At that point only primitives have been set and no
457 * {@link net.sf.ehcache.store.MemoryStore} or {@link net.sf.ehcache.store.DiskStore} has been created.
458 * <p/>
459 * A new, empty, RegisteredEventListeners is created on clone.
460 * <p/>
461 *
462 * @return an object of type {@link net.sf.ehcache.Cache}
463 * @throws CloneNotSupportedException
464 */
465 Object clone() throws CloneNotSupportedException;
466
467 /**
468 * @return true if the cache overflows to disk and the disk is persistent between restarts
469 */
470 boolean isDiskPersistent();
471
472 /**
473 * @return the interval between runs
474 * of the expiry thread, where it checks the disk store for expired elements. It is not the
475 * the timeToLiveSeconds.
476 */
477 long getDiskExpiryThreadIntervalSeconds();
478
479 /**
480 * Use this to access the service in order to register and unregister listeners
481 *
482 * @return the RegisteredEventListeners instance for this cache.
483 */
484 RegisteredEventListeners getCacheEventNotificationService();
485
486 /**
487 * Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.
488 *
489 * @return true if an element matching the key is found in memory
490 */
491 boolean isElementInMemory(Serializable key);
492
493 /**
494 * Whether an Element is stored in the cache in Memory, indicating a very low cost of retrieval.
495 *
496 * @return true if an element matching the key is found in memory
497 * @since 1.2
498 */
499 boolean isElementInMemory(Object key);
500
501 /**
502 * Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.
503 *
504 * @return true if an element matching the key is found in the diskStore
505 */
506 boolean isElementOnDisk(Serializable key);
507
508 /**
509 * Whether an Element is stored in the cache on Disk, indicating a higher cost of retrieval.
510 *
511 * @return true if an element matching the key is found in the diskStore
512 * @since 1.2
513 */
514 boolean isElementOnDisk(Object key);
515
516 /**
517 * The GUID for this cache instance can be used to determine whether two cache instance references
518 * are pointing to the same cache.
519 *
520 * @return the globally unique identifier for this cache instance. This is guaranteed to be unique.
521 * @since 1.2
522 */
523 String getGuid();
524
525 /**
526 * Gets the CacheManager managing this cache. For a newly created cache this will be null until
527 * it has been added to a CacheManager.
528 *
529 * @return the manager or null if there is none
530 */
531 CacheManager getCacheManager();
532
533 /**
534 * Resets statistics counters back to 0.
535 */
536 void clearStatistics();
537
538 /**
539 * Accurately measuring statistics can be expensive. Returns the current accuracy setting.
540 *
541 * @return one of {@link Statistics#STATISTICS_ACCURACY_BEST_EFFORT}, {@link Statistics#STATISTICS_ACCURACY_GUARANTEED}, {@link Statistics#STATISTICS_ACCURACY_NONE}
542 */
543 public int getStatisticsAccuracy();
544
545
546 /**
547 * Sets the statistics accuracy.
548 *
549 * @param statisticsAccuracy one of {@link Statistics#STATISTICS_ACCURACY_BEST_EFFORT}, {@link Statistics#STATISTICS_ACCURACY_GUARANTEED}, {@link Statistics#STATISTICS_ACCURACY_NONE}
550 */
551 public void setStatisticsAccuracy(int statisticsAccuracy);
552
553
554 /**
555 * Causes all elements stored in the Cache to be synchronously checked for expiry, and if expired, evicted.
556 */
557 void evictExpiredElements();
558
559 /**
560 * An inexpensive check to see if the key exists in the cache.
561 *
562 * @param key the key to check for
563 * @return true if an Element matching the key is found in the cache. No assertions are made about the state of the Element.
564 */
565 boolean isKeyInCache(Object key);
566
567 /**
568 * An extremely expensive check to see if the value exists in the cache.
569 *
570 * @param value to check for
571 * @return true if an Element matching the key is found in the cache. No assertions are made about the state of the Element.
572 */
573 boolean isValueInCache(Object value);
574
575 /**
576 * Gets an immutable Statistics object representing the Cache statistics at the time. How the statistics are calculated
577 * depends on the statistics accuracy setting. The only aspect of statistics sensitive to the accuracy setting is
578 * object size. How that is calculated is discussed below.
579 * <h3>Best Effort Size</h3>
580 * This result is returned when the statistics accuracy setting is {@link Statistics#STATISTICS_ACCURACY_BEST_EFFORT}.
581 * <p/>
582 * The size is the number of {@link Element}s in the {@link net.sf.ehcache.store.MemoryStore} plus
583 * the number of {@link Element}s in the {@link net.sf.ehcache.store.DiskStore}.
584 * <p/>
585 * This number is the actual number of elements, including expired elements that have
586 * not been removed. Any duplicates between stores are accounted for.
587 * <p/>
588 * Expired elements are removed from the the memory store when
589 * getting an expired element, or when attempting to spool an expired element to
590 * disk.
591 * <p/>
592 * Expired elements are removed from the disk store when getting an expired element,
593 * or when the expiry thread runs, which is once every five minutes.
594 * <p/>
595 * <h3>Guaranteed Accuracy Size</h3>
596 * This result is returned when the statistics accuracy setting is {@link Statistics#STATISTICS_ACCURACY_GUARANTEED}.
597 * <p/>
598 * This method accounts for elements which might be expired or duplicated between stores. It take approximately
599 * 200ms per 1000 elements to execute.
600 * <h3>Fast but non-accurate Size</h3>
601 * This result is returned when the statistics accuracy setting is {@link Statistics#STATISTICS_ACCURACY_NONE}.
602 * <p/>
603 * The number given may contain expired elements. In addition if the DiskStore is used it may contain some double
604 * counting of elements. It takes 6ms for 1000 elements to execute. Time to execute is O(log n). 50,000 elements take
605 * 36ms.
606 *
607 * @return the number of elements in the ehcache, with a varying degree of accuracy, depending on accuracy setting.
608 * @throws IllegalStateException if the cache is not {@link Status#STATUS_ALIVE}
609 */
610 Statistics getStatistics() throws IllegalStateException;
611
612
613 /**
614 * Sets the CacheManager
615 *
616 * @param cacheManager the CacheManager for this cache to use.
617 */
618 void setCacheManager(CacheManager cacheManager);
619
620
621 /**
622 * Accessor for the BootstrapCacheLoader associated with this cache. For testing purposes.
623 * @return the BootstrapCacheLoader to use
624 */
625 BootstrapCacheLoader getBootstrapCacheLoader();
626
627 /**
628 * Sets the bootstrap cache loader.
629 *
630 * @param bootstrapCacheLoader the loader to be used
631 * @throws CacheException if this method is called after the cache is initialized
632 */
633 void setBootstrapCacheLoader(BootstrapCacheLoader bootstrapCacheLoader) throws CacheException;
634
635
636 /**
637 * DiskStore paths can conflict between CacheManager instances. This method allows the path to be changed.
638 *
639 * @param diskStorePath the new path to be used.
640 * @throws CacheException if this method is called after the cache is initialized
641 */
642 void setDiskStorePath(String diskStorePath) throws CacheException;
643
644 /**
645 * Newly created caches do not have a {@link net.sf.ehcache.store.MemoryStore} or a {@link net.sf.ehcache.store.DiskStore}.
646 * <p/>
647 * This method creates those and makes the cache ready to accept elements
648 */
649 void initialise();
650
651 /**
652 * Bootstrap command. This must be called after the Cache is intialised, during
653 * CacheManager initialisation. If loads are synchronous, they will complete before the CacheManager
654 * initialise completes, otherwise they will happen in the background.
655 */
656 void bootstrap();
657
658 /**
659 * Flushes all cache items from memory to auxilliary caches and close the auxilliary caches.
660 * <p/>
661 * Should be invoked only by CacheManager.
662 *
663 * @throws IllegalStateException if the cache is not {@link Status#STATUS_ALIVE}
664 */
665 public void dispose() throws IllegalStateException;
666
667 /**
668 * Gets the cache configuration this cache was created with.
669 * <p/>
670 * Things like listeners that are added dynamically are excluded.
671 */
672 CacheConfiguration getCacheConfiguration();
673 }