KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > opensymphony > oscache > general > GeneralCacheAdministrator


1 /*
2  * Copyright (c) 2002-2003 by OpenSymphony
3  * All rights reserved.
4  */
5 package com.opensymphony.oscache.general;
6
7 import com.opensymphony.oscache.base.*;
8
9 import org.apache.commons.logging.Log;
10 import org.apache.commons.logging.LogFactory;
11
12 import java.util.Date JavaDoc;
13 import java.util.Properties JavaDoc;
14
15 /**
16  * A GeneralCacheAdministrator creates, flushes and administers the cache.
17  *
18  * EXAMPLES :
19  * <pre><code>
20  * // ---------------------------------------------------------------
21  * // Typical use with fail over
22  * // ---------------------------------------------------------------
23  * String myKey = "myKey";
24  * String myValue;
25  * int myRefreshPeriod = 1000;
26  * try {
27  * // Get from the cache
28  * myValue = (String) admin.getFromCache(myKey, myRefreshPeriod);
29  * } catch (NeedsRefreshException nre) {
30  * try {
31  * // Get the value (probably by calling an EJB)
32  * myValue = "This is the content retrieved.";
33  * // Store in the cache
34  * admin.putInCache(myKey, myValue);
35  * } catch (Exception ex) {
36  * // We have the current content if we want fail-over.
37  * myValue = (String) nre.getCacheContent();
38  * // It is essential that cancelUpdate is called if the
39  * // cached content is not rebuilt
40  * admin.cancelUpdate(myKey);
41  * }
42  * }
43  *
44  *
45  *
46  * // ---------------------------------------------------------------
47  * // Typical use without fail over
48  * // ---------------------------------------------------------------
49  * String myKey = "myKey";
50  * String myValue;
51  * int myRefreshPeriod = 1000;
52  * try {
53  * // Get from the cache
54  * myValue = (String) admin.getFromCache(myKey, myRefreshPeriod);
55  * } catch (NeedsRefreshException nre) {
56  * try {
57  * // Get the value (probably by calling an EJB)
58  * myValue = "This is the content retrieved.";
59  * // Store in the cache
60  * admin.putInCache(myKey, myValue);
61  * updated = true;
62  * } finally {
63  * if (!updated) {
64  * // It is essential that cancelUpdate is called if the
65  * // cached content could not be rebuilt
66  * admin.cancelUpdate(myKey);
67  * }
68  * }
69  * }
70  * // ---------------------------------------------------------------
71  * // ---------------------------------------------------------------
72  * </code></pre>
73  *
74  * @version $Revision: 1.1 $
75  * @author <a HREF="mailto:fbeauregard@pyxis-tech.com">Francois Beauregard</a>
76  * @author <a HREF="mailto:abergevin@pyxis-tech.com">Alain Bergevin</a>
77  */
78 public class GeneralCacheAdministrator extends AbstractCacheAdministrator {
79     private static transient final Log log = LogFactory.getLog(GeneralCacheAdministrator.class);
80
81     /**
82      * Application cache
83      */
84     private Cache applicationCache = null;
85
86     /**
87      * Create the cache administrator.
88      */
89     public GeneralCacheAdministrator() {
90         this(null);
91     }
92
93     /**
94      * Create the cache administrator with the specified properties
95      */
96     public GeneralCacheAdministrator(Properties JavaDoc p) {
97         super(p);
98         log.info("Constructed GeneralCacheAdministrator()");
99         createCache();
100     }
101
102     /**
103      * Grabs a cache
104      *
105      * @return The cache
106      */
107     public Cache getCache() {
108         return applicationCache;
109     }
110     
111     /**
112      * Remove an object from the cache
113      *
114      * @param key The key entered by the user.
115      */
116     public void removeEntry(String JavaDoc key) {
117         getCache().removeEntry(key);
118     }
119     /**
120      * Get an object from the cache
121      *
122      * @param key The key entered by the user.
123      * @return The object from cache
124      * @throws NeedsRefreshException when no cache entry could be found with the
125      * supplied key, or when an entry was found but is considered out of date. If
126      * the cache entry is a new entry that is currently being constructed this method
127      * will block until the new entry becomes available. Similarly, it will block if
128      * a stale entry is currently being rebuilt by another thread and cache blocking is
129      * enabled (<code>cache.blocking=true</code>).
130      */
131     public Object JavaDoc getFromCache(String JavaDoc key) throws NeedsRefreshException {
132         return getCache().getFromCache(key);
133     }
134
135     /**
136      * Get an object from the cache
137      *
138      * @param key The key entered by the user.
139      * @param refreshPeriod How long the object can stay in cache in seconds. To
140      * allow the entry to stay in the cache indefinitely, supply a value of
141      * {@link CacheEntry#INDEFINITE_EXPIRY}
142      * @return The object from cache
143      * @throws NeedsRefreshException when no cache entry could be found with the
144      * supplied key, or when an entry was found but is considered out of date. If
145      * the cache entry is a new entry that is currently being constructed this method
146      * will block until the new entry becomes available. Similarly, it will block if
147      * a stale entry is currently being rebuilt by another thread and cache blocking is
148      * enabled (<code>cache.blocking=true</code>).
149      */
150     public Object JavaDoc getFromCache(String JavaDoc key, int refreshPeriod) throws NeedsRefreshException {
151         return getCache().getFromCache(key, refreshPeriod);
152     }
153
154     /**
155      * Get an object from the cache
156      *
157      * @param key The key entered by the user.
158      * @param refreshPeriod How long the object can stay in cache in seconds. To
159      * allow the entry to stay in the cache indefinitely, supply a value of
160      * {@link CacheEntry#INDEFINITE_EXPIRY}
161      * @param cronExpression A cron expression that the age of the cache entry
162      * will be compared to. If the entry is older than the most recent match for the
163      * cron expression, the entry will be considered stale.
164      * @return The object from cache
165      * @throws NeedsRefreshException when no cache entry could be found with the
166      * supplied key, or when an entry was found but is considered out of date. If
167      * the cache entry is a new entry that is currently being constructed this method
168      * will block until the new entry becomes available. Similarly, it will block if
169      * a stale entry is currently being rebuilt by another thread and cache blocking is
170      * enabled (<code>cache.blocking=true</code>).
171      */
172     public Object JavaDoc getFromCache(String JavaDoc key, int refreshPeriod, String JavaDoc cronExpression) throws NeedsRefreshException {
173         return getCache().getFromCache(key, refreshPeriod, cronExpression);
174     }
175
176     /**
177      * Cancels a pending cache update. This should only be called by a thread
178      * that received a {@link NeedsRefreshException} and was unable to generate
179      * some new cache content.
180      *
181      * @param key The cache entry key to cancel the update of.
182      */
183     public void cancelUpdate(String JavaDoc key) {
184         getCache().cancelUpdate(key);
185     }
186
187     /**
188      * Shuts down the cache administrator.
189      */
190     public void destroy() {
191         finalizeListeners(applicationCache);
192     }
193
194     // METHODS THAT DELEGATES TO THE CACHE ---------------------
195
196     /**
197      * Flush the entire cache immediately.
198      */
199     public void flushAll() {
200         getCache().flushAll(new Date JavaDoc());
201     }
202
203     /**
204      * Flush the entire cache at the given date.
205      *
206      * @param date The time to flush
207      */
208     public void flushAll(Date JavaDoc date) {
209         getCache().flushAll(date);
210     }
211
212     /**
213      * Flushes a single cache entry.
214      */
215     public void flushEntry(String JavaDoc key) {
216         getCache().flushEntry(key);
217     }
218
219     /**
220      * Flushes all items that belong to the specified group.
221      *
222      * @param group The name of the group to flush
223      */
224     public void flushGroup(String JavaDoc group) {
225         getCache().flushGroup(group);
226     }
227
228     /**
229      * Allows to flush all items that have a specified pattern in the key.
230      *
231      * @param pattern Pattern.
232      * @deprecated For performance and flexibility reasons it is preferable to
233      * store cache entries in groups and use the {@link #flushGroup(String)} method
234      * instead of relying on pattern flushing.
235      */
236     public void flushPattern(String JavaDoc pattern) {
237         getCache().flushPattern(pattern);
238     }
239
240     /**
241      * Put an object in a cache
242      *
243      * @param key The key entered by the user
244      * @param content The object to store
245      * @param policy Object that implements refresh policy logic
246      */
247     public void putInCache(String JavaDoc key, Object JavaDoc content, EntryRefreshPolicy policy) {
248         Cache cache = getCache();
249         cache.putInCache(key, content, policy);
250     }
251
252     /**
253      * Put an object in a cache
254      *
255      * @param key The key entered by the user
256      * @param content The object to store
257      */
258     public void putInCache(String JavaDoc key, Object JavaDoc content) {
259         putInCache(key, content, (EntryRefreshPolicy) null);
260     }
261
262     /**
263      * Puts an object in a cache
264      *
265      * @param key The unique key for this cached object
266      * @param content The object to store
267      * @param groups The groups that this object belongs to
268      */
269     public void putInCache(String JavaDoc key, Object JavaDoc content, String JavaDoc[] groups) {
270         getCache().putInCache(key, content, groups);
271     }
272
273     /**
274      * Puts an object in a cache
275      *
276      * @param key The unique key for this cached object
277      * @param content The object to store
278      * @param groups The groups that this object belongs to
279      * @param policy The refresh policy to use
280      */
281     public void putInCache(String JavaDoc key, Object JavaDoc content, String JavaDoc[] groups, EntryRefreshPolicy policy) {
282         getCache().putInCache(key, content, groups, policy, null);
283     }
284
285     /**
286      * Sets the cache capacity (number of items). If the cache contains
287      * more than <code>capacity</code> items then items will be removed
288      * to bring the cache back down to the new size.
289      *
290      * @param capacity The new capacity of the cache
291      */
292     public void setCacheCapacity(int capacity) {
293         super.setCacheCapacity(capacity);
294         getCache().setCapacity(capacity);
295     }
296
297     /**
298      * Creates a cache in this admin
299      */
300     private void createCache() {
301         log.info("Creating new cache");
302
303         applicationCache = new Cache(isMemoryCaching(), isUnlimitedDiskCache(), isOverflowPersistence(), isBlocking(), algorithmClass, cacheCapacity);
304
305         configureStandardListeners(applicationCache);
306     }
307 }
308
Popular Tags