1 /***
2 * BaseCache.java
3 *
4 * This file is part of the creme library.
5 * The creme library intends to ease the development effort of large
6 * applications by providing easy to use support classes.
7 *
8 * Copyright (C) 2002 Denis Bregeon
9 *
10 * This library is free software; you can redistribute it and/or
11 * modify it under the terms of the GNU Lesser General Public
12 * License as published by the Free Software Foundation; either
13 * version 2.1 of the License, or (at your option) any later version.
14 *
15 * This library is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 * Lesser General Public License for more details.
19 *
20 * You should have received a copy of the GNU Lesser General Public
21 * License along with this library; if not, write to the Free Software
22 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
23 *
24 * contact information: dbregeon@sourceforge.net
25 */
26 package org.jcreme.caches;
27
28 import java.util.HashSet;
29
30 /***
31 * This abstract cache is the base for policied caches. The policy element is
32 * not enforced in this class. It is up to the subclasses to enforce the
33 * policies.
34 *
35 * @author $Author: dbregeon $
36 * @version $Revision: 1.2 $
37 */
38 public abstract class BaseCache implements Cache {
39 /***
40 * The initial size of the cache.
41 */
42 private int minSize;
43
44 /***
45 * The maximum size of the cache.
46 */
47 private int maxSize;
48
49 /***
50 * The policy used to store the objects.
51 */
52 private CachePolicy replacementPolicy = null;
53
54 /***
55 * The list of the listeners for this cache.
56 */
57 private final transient HashSet listeners = new HashSet();
58
59 /***
60 * Creates new Cache
61 */
62 protected BaseCache() {
63
64 this(0, Integer.MAX_VALUE, CachePolicy.NONE);
65 }
66
67 /***
68 * Creates new Cache
69 *
70 * @param policy
71 * the policy used by this cache.
72 */
73 protected BaseCache(CachePolicy policy) {
74
75 this(0, Integer.MAX_VALUE, policy);
76 }
77
78 /***
79 * Creates new Cache
80 *
81 * @param minSize
82 * the initial size of the cache (number of objects).
83 * @param maxSize
84 * the maximum size of the cache (number of objects).
85 * @param policy
86 * the policy of this cache.
87 */
88 protected BaseCache(int minSize, int maxSize, CachePolicy policy) {
89 this.minSize = minSize;
90 this.maxSize = maxSize;
91 this.replacementPolicy = policy;
92 }
93
94 /***
95 * This method modifies the maximum size of the cache.
96 *
97 * @param maxSize
98 * the maximum number of objects that can be stored in the cache.
99 */
100 public void setMaxSize(final int maxSize) {
101 this.maxSize = maxSize;
102 }
103
104 /***
105 * Enables access to the policy currently used by the cache.
106 *
107 * @return the policy of the cache.
108 */
109 public CachePolicy getReplacementPolicy() {
110 return this.replacementPolicy;
111 }
112
113 /***
114 * Enables to modify the policy of this Cache.
115 *
116 * @param policy
117 * the new policy for the Cache.
118 */
119 protected void setReplacementPolicy(final CachePolicy policy) {
120 this.replacementPolicy = policy;
121 }
122
123 /***
124 * This method adds an object in the cache.
125 *
126 * @param key
127 * the key that will be used to retrieve the object.
128 * @param value
129 * the object to store in the cache.
130 * @throws CacheFullException
131 * if the object could not be stored in the cache.
132 */
133 public abstract void registerObject(final Object key, final Object value)
134 throws CacheFullException;
135
136 /***
137 * This method removes an object from the cache.
138 *
139 * @param key
140 * the key that was used to store the object in the cache.
141 */
142 public abstract void unregisterObject(Object key);
143
144 /***
145 * Gives access to an object registered in the cache.
146 *
147 * @param key
148 * the key used to register the searched object.
149 * @return the object stored in the cache. Null if no object was stored with
150 * this key.
151 */
152 public abstract Object getObject(Object key);
153
154 /***
155 * Gives access to the Cache's maximum size.
156 *
157 * @return the maximum size for the Cache.
158 */
159 public int getMaxSize() {
160 return this.maxSize;
161 }
162
163 /***
164 * Gives access to the Cache's minimum size.
165 *
166 * @return the minimum size for the Cache.
167 */
168 protected int getMinSize() {
169 return this.minSize;
170 }
171
172 /***
173 * To add a CacheListener for this cache.
174 *
175 * @param listener
176 * a cache listener. It is silently ignored if it is null.
177 */
178 public void addCacheListener(final CacheListener listener) {
179 if (listener != null) {
180 this.listeners.add(listener);
181 }
182 }
183
184 /***
185 * To remove a CacheListener for this cache.
186 *
187 * @param listener
188 * a cache listener. It is silently ignored if it is null.
189 */
190 public void removeCacheListener(final CacheListener listener) {
191 if (listener != null) {
192 this.listeners.remove(listener);
193 }
194 }
195
196 /***
197 * Convenience method to fire events when the cache is modified.
198 *
199 * @param evt
200 * a cache event.
201 */
202 protected void fireElementRemoved(final CacheEvent evt) {
203 final Object[] theListeners = this.listeners.toArray();
204 for (int i = theListeners.length - 1; i >= 0; i--) {
205 ((CacheListener) theListeners[i]).elementRemoved(evt);
206 }
207 }
208
209 /***
210 * Convenience method to fire events when the cache is modified.
211 *
212 * @param evt
213 * a cache event.
214 */
215 protected void fireElementAdded(final CacheEvent evt) {
216 final Object[] theListeners = this.listeners.toArray();
217 for (int i = theListeners.length - 1; i >= 0; i--) {
218 ((CacheListener) theListeners[i]).elementAdded(evt);
219 }
220 }
221
222 /***
223 * Convenience method to build events when the cache is modified.
224 *
225 * @param element
226 * the element that changed in the cache.
227 * @return the event built from element.
228 */
229 protected CacheEvent buildEvent(final Object element) {
230 return new CacheEvent(this, element);
231 }
232
233 /***
234 * Gives access to all the objects stored in the Cache.
235 *
236 * @return all the contents of the Cache.
237 */
238 public abstract Object[] getAllObjects();
239
240 /***
241 * Removes all the objects from the Cache, leaving it empty.
242 */
243 public abstract void clear();
244
245 /***
246 * This methods gives the current size of the cache.
247 *
248 * @return the number of objects currently stored in the cache.
249 */
250 public abstract int getSize();
251
252 /***
253 * This method gives the same result as the getAllObjects method but the
254 * objects in the result array are types with the parameter type.
255 *
256 * @param type
257 * the type to give to the object in the result array.
258 * @return an array of objects of the type.
259 */
260 public abstract Object[] getAllObjects(Class type);
261
262 /***
263 * Gives access to the list of listeners that listen to this cache.
264 *
265 * @return the listeners of this Cache.
266 */
267 public CacheListener[] getCacheListeners() {
268 return (CacheListener[]) this.listeners
269 .toArray(new CacheListener[this.listeners.size()]);
270 }
271 }