KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > sape > carbon > services > cache > total > AbstractTotalCache


1 /*
2  * The contents of this file are subject to the Sapient Public License
3  * Version 1.0 (the "License"); you may not use this file except in compliance
4  * with the License. You may obtain a copy of the License at
5  * http://carbon.sf.net/License.html.
6  *
7  * Software distributed under the License is distributed on an "AS IS" basis,
8  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
9  * the specific language governing rights and limitations under the License.
10  *
11  * The Original Code is The Carbon Component Framework.
12  *
13  * The Initial Developer of the Original Code is Sapient Corporation
14  *
15  * Copyright (C) 2003 Sapient Corporation. All Rights Reserved.
16  */
17
18 package org.sape.carbon.services.cache.total;
19
20 import java.util.Collection JavaDoc;
21 import java.util.Map JavaDoc;
22 import java.util.Set JavaDoc;
23
24 import org.sape.carbon.core.component.lifecycle.Startable;
25 import org.sape.carbon.core.component.lifecycle.Suspendable;
26 import org.sape.carbon.services.cache.Cache;
27 import org.sape.carbon.services.cache.CacheLoadException;
28
29 /**
30  * <p>
31  * This is the base class for caches of data that load all of their contents
32  * into memory. The methods implemented here fulfill the requirements of the
33  * Cache interfact with the exception of refreshAll. It also implements the
34  * Startable and Suspendable interfaces. Refresh and configuration
35  * functionality are left up to extending classes.
36  * </p>
37  *
38  * Copyright 2002 Sapient
39  * @since carbon 1.0
40  * @author Douglas Voet, July 2002
41  * @version $Revision: 1.7 $($Author: dvoet $ / $Date: 2003/05/05 21:21:08 $)
42  */
43 public abstract class AbstractTotalCache
44     implements Cache, Startable, Suspendable {
45
46     /**
47      * Refresh the contents of the cache. First, initialize a holding cache.
48      * Then load the holding cache with new data from the data loader. Finally,
49      * activate the holding cache.
50      *
51      * @throws CacheLoadException when its data loader has failed to load data
52      */
53     public abstract void refreshAll() throws CacheLoadException;
54
55     /**
56      * Removes all mappings from this cache.
57      */
58     public void clear() {
59         getCacheMap().clear();
60     }
61
62
63     /**
64      * <p>For a given key value, return a boolean indicating if the cache
65      * contains a value for the key.</p>
66      *
67      * @param key key for the desired cache entry
68      * @return true if the cache contains a mapping for the specified key
69      */
70     public boolean containsKey(Object JavaDoc key) {
71         return getCacheMap().containsKey(key);
72     }
73
74
75     /**
76      * Returns true if this cache maps one or more keys to the specified value.
77      * More formally, returns true if and only if this cache contains at least
78      * one mapping to a value v such that
79      * <code>(value==null ? v==null : value.equals(v))</code>.
80      * This operation will require time linear in the cache size.
81      *
82      * @param value value whose presence in this map is to be
83      * tested.
84      * @return true if this map maps one or more keys to the specified value.
85      */
86     public boolean containsValue(Object JavaDoc value) {
87         return getCacheMap().containsValue(value);
88     }
89
90
91     /**
92      * Returns a set view of the mappings contained in this cache. Each element
93      * in the returned set is a Map.Entry. The set is backed by the cache, so
94      * changes to the map are reflected in the set, and vice-versa. If the cache
95      * is modified while an iteration over the set is in progress, the results
96      * of the iteration are undefined. The set supports element removal, which
97      * removes the corresponding mapping from the cache, via the
98      * Iterator.remove, Set.remove, removeAll, retainAll and clear operations.
99      * It does not support the add or addAll operations.
100      *
101      * @return the set of mappings in this cache
102      */
103     public Set JavaDoc entrySet() {
104         return getCacheMap().entrySet();
105     }
106
107
108     /**
109      * <p>For a given key value, return the object associated with the key
110      * value from the cache. If the value is not found in the cache, or the key
111      * is associated with the value null, a null reference is returned. The only
112      * way to tell for certain if the cache contains the key is to use the
113      * containsKey() method.</p>
114      *
115      * @param key key for the desired cache entry
116      * @return <code>Object</code>
117      */
118     public Object JavaDoc get(Object JavaDoc key) {
119         return getCacheMap().get(key);
120     }
121
122
123     /**
124      * Returns true if this map contains no key-value mappings.
125      *
126      * @return true if this map contains no key-value mappings
127      */
128     public boolean isEmpty() {
129         return getCacheMap().isEmpty();
130     }
131
132
133     /**
134      * Returns the keys of the cache.
135      * @return <code>Set</code> The set of all keys in the cache.
136      */
137     public Set JavaDoc keySet() {
138         return getCacheMap().keySet();
139     }
140
141
142     /**
143      * Put the Object value into the cache referenced by the Object key
144      *
145      * @param key key for the value to add to this cache
146      * @param value value to add for the given key
147      * @return the old value stored at the given key
148      */
149     public Object JavaDoc put(Object JavaDoc key, Object JavaDoc value) {
150         return getCacheMap().put(key, value);
151     }
152
153
154     /**
155      * Copies all of the mappings from the specified map to this cache.
156      * These mappings will replace any mappings that this cache had for any of
157      * the keys currently in the specified cache.
158      *
159      * @param t the map to place all values of into this cache
160      */
161     public void putAll(Map JavaDoc t) {
162         getCacheMap().putAll(t);
163     }
164
165
166     /**
167      * Removes the mapping for this key from this cache.
168      *
169      * @param key the key to remove from the cache
170      * @return previous value associated with specified key, or null if there
171      * was no mapping for key.
172      */
173     public Object JavaDoc remove(Object JavaDoc key) {
174         return getCacheMap().remove(key);
175     }
176
177
178     /**
179      * Returns the number of key-value mappings in this map. If the map contains
180      * more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.
181      *
182      * @return the number of key-value mappings in this map.
183      */
184     public int size() {
185         return getCacheMap().size();
186     }
187
188
189     /**
190      * Returns a collection view of the values contained in this cache. The
191      * collection is backed by the cache, so changes to the cache are reflected
192      * in the collection, and vice-versa.
193      *
194      * @return a collection view of the values contained in this cache
195      */
196     public Collection JavaDoc values() {
197         return getCacheMap().values();
198     }
199
200     /**
201      * @see Startable#start()
202      */
203     public void start() throws CacheLoadException {
204         refreshAll();
205     }
206
207     /**
208      * @see Startable#stop()
209      */
210     public void stop() {
211     }
212
213     /**
214      * @see Suspendable#resume()
215      */
216     public void resume() throws CacheLoadException {
217         refreshAll();
218     }
219
220     /**
221      * @see Suspendable#suspend()
222      */
223     public void suspend() {
224     }
225
226     /**
227      * This execution should flush the cache of the current entries and refill
228      * it from the dataloader with new entries.
229      * @see org.sape.carbon.services.scheduler.Schedulable#runScheduledTask
230      * @throws CacheLoadException when their is a failure to load the values
231      * from the dataloader.
232      */
233     public void runScheduledTask() throws CacheLoadException {
234         refreshAll();
235     }
236
237     /**
238      * Returns a referench to the Map that contains all the cached data. This
239      * is used by the Map interface methods of this class.
240      *
241      * @return Map containing the cached data
242      */
243     protected abstract Map JavaDoc getCacheMap();
244 }
Popular Tags