1 /***
2 * Cache.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.Map;
29
30 /***
31 * This is the general interface to model an object cache. This provides the
32 * methods to store and retrieve an object based on a key.
33 *
34 * @author $Author: dbregeon $
35 * @version $Revision: 1.2 $
36 */
37 public interface Cache {
38 /***
39 * Sets the maximum number of objects that will be stored in this cache.
40 *
41 * @param maxSize
42 * the maximum size.
43 */
44 void setMaxSize(int maxSize);
45
46 /***
47 * @return the replacement policy that is used by the Cache. It determines
48 * how the Cache makes room for new objects when the maximum size is
49 * exceeded.
50 */
51 CachePolicy getReplacementPolicy();
52
53 /***
54 * Registers an object in the cache using the given key to refer to it.
55 *
56 * @param key
57 * the key to use to retrieve the object.
58 * @param value
59 * the object to store in the Cache.
60 * @throws CacheFullException
61 * when the Cache would exceed its maximum size and no room can
62 * be made.
63 */
64 void registerObject(Object key, Object value)
65 throws CacheFullException;
66
67 /***
68 * Removes the object associated with the given key from the Cache.
69 *
70 * @param key
71 * the key associated to the object to be removed.
72 */
73 void unregisterObject(Object key);
74
75 /***
76 * @param key
77 * the key associated to the object to be retrieved.
78 * @return the object associated to the key or null if no object is
79 * associated to the key in the Cache.
80 */
81 Object getObject(Object key);
82
83 /***
84 * @return tthe current maximum size of the cache.
85 */
86 int getMaxSize();
87
88 /***
89 * @return all the objects contained in this Cache.
90 */
91 Object[] getAllObjects();
92
93 /***
94 * This is a convenience method to ensure that the array returned if has
95 * member of the correct type.
96 *
97 * @param type
98 * the type to assign to the array (this should be a type common
99 * to all the objects contained in the Cache.
100 * @return all the objects contained in this Cache.
101 */
102 Object[] getAllObjects(Class type);
103
104 /***
105 * This is a convenience method. It enables to add to the cache all the
106 * objects present in the map.
107 *
108 * @param m
109 * the map that contains the objects (and keys) to use.
110 * @throws CacheFullException
111 * when the Cache would exceed its maximum size and no room can
112 * be made.
113 */
114 void registerAllObjects(Map m) throws CacheFullException;
115
116 /***
117 * This method enables to access to the cache contents.
118 *
119 * @return a map of the (key,value) contents of the cache.
120 */
121 Map getMap();
122
123 /***
124 * Removes all the objects from the Cache, leaving it empty.
125 */
126 void clear();
127
128 /***
129 * @return the current siez of the Cache (the number of otems currently
130 * stored).
131 */
132 int getSize();
133
134 /***
135 * This enables to add a CacheListener to the Cache.
136 *
137 * @param listener
138 * the listener to add.
139 */
140 void addCacheListener(CacheListener listener);
141
142 /***
143 * This enables to remove a CacheListener to the Cache.
144 *
145 * @param listener
146 * the listener to remove.
147 */
148 void removeCacheListener(CacheListener listener);
149
150 /***
151 * @return all the listeners that are attached to this Cache.
152 */
153 CacheListener[] getCacheListeners();
154 }