001: /*
002: * Copyright (c) 2002-2003 by OpenSymphony
003: * All rights reserved.
004: */
005: package com.opensymphony.oscache.general;
006:
007: import com.opensymphony.oscache.base.*;
008:
009: import org.apache.commons.logging.Log;
010: import org.apache.commons.logging.LogFactory;
011:
012: import java.util.Date;
013: import java.util.Properties;
014:
015: /**
016: * A GeneralCacheAdministrator creates, flushes and administers the cache.
017: *
018: * EXAMPLES :
019: * <pre><code>
020: * // ---------------------------------------------------------------
021: * // Typical use with fail over
022: * // ---------------------------------------------------------------
023: * String myKey = "myKey";
024: * String myValue;
025: * int myRefreshPeriod = 1000;
026: * try {
027: * // Get from the cache
028: * myValue = (String) admin.getFromCache(myKey, myRefreshPeriod);
029: * } catch (NeedsRefreshException nre) {
030: * try {
031: * // Get the value (probably by calling an EJB)
032: * myValue = "This is the content retrieved.";
033: * // Store in the cache
034: * admin.putInCache(myKey, myValue);
035: * } catch (Exception ex) {
036: * // We have the current content if we want fail-over.
037: * myValue = (String) nre.getCacheContent();
038: * // It is essential that cancelUpdate is called if the
039: * // cached content is not rebuilt
040: * admin.cancelUpdate(myKey);
041: * }
042: * }
043: *
044: *
045: *
046: * // ---------------------------------------------------------------
047: * // Typical use without fail over
048: * // ---------------------------------------------------------------
049: * String myKey = "myKey";
050: * String myValue;
051: * int myRefreshPeriod = 1000;
052: * try {
053: * // Get from the cache
054: * myValue = (String) admin.getFromCache(myKey, myRefreshPeriod);
055: * } catch (NeedsRefreshException nre) {
056: * try {
057: * // Get the value (probably by calling an EJB)
058: * myValue = "This is the content retrieved.";
059: * // Store in the cache
060: * admin.putInCache(myKey, myValue);
061: * updated = true;
062: * } finally {
063: * if (!updated) {
064: * // It is essential that cancelUpdate is called if the
065: * // cached content could not be rebuilt
066: * admin.cancelUpdate(myKey);
067: * }
068: * }
069: * }
070: * // ---------------------------------------------------------------
071: * // ---------------------------------------------------------------
072: * </code></pre>
073: *
074: * @version $Revision: 254 $
075: * @author <a href="mailto:fbeauregard@pyxis-tech.com">Francois Beauregard</a>
076: * @author <a href="mailto:abergevin@pyxis-tech.com">Alain Bergevin</a>
077: */
078: public class GeneralCacheAdministrator extends
079: AbstractCacheAdministrator {
080: private static transient final Log log = LogFactory
081: .getLog(GeneralCacheAdministrator.class);
082:
083: /**
084: * Application cache
085: */
086: private Cache applicationCache = null;
087:
088: /**
089: * Create the cache administrator.
090: */
091: public GeneralCacheAdministrator() {
092: this (null);
093: }
094:
095: /**
096: * Create the cache administrator with the specified properties
097: */
098: public GeneralCacheAdministrator(Properties p) {
099: super (p);
100: log.info("Constructed GeneralCacheAdministrator()");
101: createCache();
102: }
103:
104: /**
105: * Grabs a cache
106: *
107: * @return The cache
108: */
109: public Cache getCache() {
110: return applicationCache;
111: }
112:
113: /**
114: * Remove an object from the cache
115: *
116: * @param key The key entered by the user.
117: */
118: public void removeEntry(String key) {
119: getCache().removeEntry(key);
120: }
121:
122: /**
123: * Get an object from the cache
124: *
125: * @param key The key entered by the user.
126: * @return The object from cache
127: * @throws NeedsRefreshException when no cache entry could be found with the
128: * supplied key, or when an entry was found but is considered out of date. If
129: * the cache entry is a new entry that is currently being constructed this method
130: * will block until the new entry becomes available. Similarly, it will block if
131: * a stale entry is currently being rebuilt by another thread and cache blocking is
132: * enabled (<code>cache.blocking=true</code>).
133: */
134: public Object getFromCache(String key) throws NeedsRefreshException {
135: return getCache().getFromCache(key);
136: }
137:
138: /**
139: * Get an object from the cache
140: *
141: * @param key The key entered by the user.
142: * @param refreshPeriod How long the object can stay in cache in seconds. To
143: * allow the entry to stay in the cache indefinitely, supply a value of
144: * {@link CacheEntry#INDEFINITE_EXPIRY}
145: * @return The object from cache
146: * @throws NeedsRefreshException when no cache entry could be found with the
147: * supplied key, or when an entry was found but is considered out of date. If
148: * the cache entry is a new entry that is currently being constructed this method
149: * will block until the new entry becomes available. Similarly, it will block if
150: * a stale entry is currently being rebuilt by another thread and cache blocking is
151: * enabled (<code>cache.blocking=true</code>).
152: */
153: public Object getFromCache(String key, int refreshPeriod)
154: throws NeedsRefreshException {
155: return getCache().getFromCache(key, refreshPeriod);
156: }
157:
158: /**
159: * Get an object from the cache
160: *
161: * @param key The key entered by the user.
162: * @param refreshPeriod How long the object can stay in cache in seconds. To
163: * allow the entry to stay in the cache indefinitely, supply a value of
164: * {@link CacheEntry#INDEFINITE_EXPIRY}
165: * @param cronExpression A cron expression that the age of the cache entry
166: * will be compared to. If the entry is older than the most recent match for the
167: * cron expression, the entry will be considered stale.
168: * @return The object from cache
169: * @throws NeedsRefreshException when no cache entry could be found with the
170: * supplied key, or when an entry was found but is considered out of date. If
171: * the cache entry is a new entry that is currently being constructed this method
172: * will block until the new entry becomes available. Similarly, it will block if
173: * a stale entry is currently being rebuilt by another thread and cache blocking is
174: * enabled (<code>cache.blocking=true</code>).
175: */
176: public Object getFromCache(String key, int refreshPeriod,
177: String cronExpression) throws NeedsRefreshException {
178: return getCache().getFromCache(key, refreshPeriod,
179: cronExpression);
180: }
181:
182: /**
183: * Cancels a pending cache update. This should only be called by a thread
184: * that received a {@link NeedsRefreshException} and was unable to generate
185: * some new cache content.
186: *
187: * @param key The cache entry key to cancel the update of.
188: */
189: public void cancelUpdate(String key) {
190: getCache().cancelUpdate(key);
191: }
192:
193: /**
194: * Shuts down the cache administrator.
195: */
196: public void destroy() {
197: finalizeListeners(applicationCache);
198: }
199:
200: // METHODS THAT DELEGATES TO THE CACHE ---------------------
201:
202: /**
203: * Flush the entire cache immediately.
204: */
205: public void flushAll() {
206: getCache().flushAll(new Date());
207: }
208:
209: /**
210: * Flush the entire cache at the given date.
211: *
212: * @param date The time to flush
213: */
214: public void flushAll(Date date) {
215: getCache().flushAll(date);
216: }
217:
218: /**
219: * Flushes a single cache entry.
220: */
221: public void flushEntry(String key) {
222: getCache().flushEntry(key);
223: }
224:
225: /**
226: * Flushes all items that belong to the specified group.
227: *
228: * @param group The name of the group to flush
229: */
230: public void flushGroup(String group) {
231: getCache().flushGroup(group);
232: }
233:
234: /**
235: * Allows to flush all items that have a specified pattern in the key.
236: *
237: * @param pattern Pattern.
238: * @deprecated For performance and flexibility reasons it is preferable to
239: * store cache entries in groups and use the {@link #flushGroup(String)} method
240: * instead of relying on pattern flushing.
241: */
242: public void flushPattern(String pattern) {
243: getCache().flushPattern(pattern);
244: }
245:
246: /**
247: * Put an object in a cache
248: *
249: * @param key The key entered by the user
250: * @param content The object to store
251: * @param policy Object that implements refresh policy logic
252: */
253: public void putInCache(String key, Object content,
254: EntryRefreshPolicy policy) {
255: Cache cache = getCache();
256: cache.putInCache(key, content, policy);
257: }
258:
259: /**
260: * Put an object in a cache
261: *
262: * @param key The key entered by the user
263: * @param content The object to store
264: */
265: public void putInCache(String key, Object content) {
266: putInCache(key, content, (EntryRefreshPolicy) null);
267: }
268:
269: /**
270: * Puts an object in a cache
271: *
272: * @param key The unique key for this cached object
273: * @param content The object to store
274: * @param groups The groups that this object belongs to
275: */
276: public void putInCache(String key, Object content, String[] groups) {
277: getCache().putInCache(key, content, groups);
278: }
279:
280: /**
281: * Puts an object in a cache
282: *
283: * @param key The unique key for this cached object
284: * @param content The object to store
285: * @param groups The groups that this object belongs to
286: * @param policy The refresh policy to use
287: */
288: public void putInCache(String key, Object content, String[] groups,
289: EntryRefreshPolicy policy) {
290: getCache().putInCache(key, content, groups, policy, null);
291: }
292:
293: /**
294: * Sets the cache capacity (number of items). If the cache contains
295: * more than <code>capacity</code> items then items will be removed
296: * to bring the cache back down to the new size.
297: *
298: * @param capacity The new capacity of the cache
299: */
300: public void setCacheCapacity(int capacity) {
301: super .setCacheCapacity(capacity);
302: getCache().setCapacity(capacity);
303: }
304:
305: /**
306: * Creates a cache in this admin
307: */
308: private void createCache() {
309: log.info("Creating new cache");
310:
311: applicationCache = new Cache(isMemoryCaching(),
312: isUnlimitedDiskCache(), isOverflowPersistence(),
313: isBlocking(), algorithmClass, cacheCapacity);
314:
315: configureStandardListeners(applicationCache);
316: }
317: }
|