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.extension;
18
19 import net.sf.ehcache.CacheException;
20 import net.sf.ehcache.Ehcache;
21 import net.sf.ehcache.Status;
22
23 /***
24 * This is a general purpose mechanism to allow generic extensions to a Cache.
25 * <p/>
26 * CacheExtensions are tied into the Cache lifecycle. For that reason this interface has the
27 * lifecycle methods.
28 * <p/>
29 * CacheExtensions are created using the CacheExtensionFactory which has a
30 * <code>createCacheCacheExtension()</code> method which takes as a parameter a Cache and
31 * properties. It can thus call back into any public method on Cache, including, of course,
32 * the load methods.
33 * <p/>
34 * CacheExtensions are suitable for timing services, where you want to create a timer to
35 * perform cache operations. The other way of adding Cache behaviour is to decorate a cache.
36 * See {@link net.sf.ehcache.constructs.blocking.BlockingCache} for an example of how to do
37 * this.
38 * <p/>
39 * Because a CacheExtension holds a reference to a Cache, the CacheExtension can do things
40 * such as registering a CacheEventListener or even a CacheManagerEventListener, all from
41 * within a CacheExtension, creating more opportunities for customisation.
42 *
43 * @author <a href="mailto:gluck@gregluck.com">Greg Luck</a>
44 * @version $Id: CacheExtension.html 13146 2011-08-01 17:12:39Z oletizi $
45 */
46 public interface CacheExtension {
47
48 /***
49 * Notifies providers to initialise themselves.
50 * <p/>
51 * This method is called during the Cache's initialise method after it has changed it's
52 * status to alive. Cache operations are legal in this method.
53 *
54 * @throws CacheException
55 */
56 void init();
57
58 /***
59 * Providers may be doing all sorts of exotic things and need to be able to clean up on
60 * dispose.
61 * <p/>
62 * Cache operations are illegal when this method is called. The cache itself is partly
63 * disposed when this method is called.
64 *
65 * @throws CacheException
66 */
67 void dispose() throws CacheException;
68
69 /***
70 * Creates a clone of this extension. This method will only be called by ehcache before a
71 * cache is initialized.
72 * <p/>
73 * Implementations should throw CloneNotSupportedException if they do not support clone
74 * but that will stop them from being used with defaultCache.
75 *
76 * @param cache the cache extended
77 * @return a clone
78 * @throws CloneNotSupportedException if the extension could not be cloned.
79 */
80 public CacheExtension clone(Ehcache cache) throws CloneNotSupportedException;
81
82
83 /***
84 * @return the status of the extension
85 */
86 public Status getStatus();
87 }