KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > sun > appserv > util > cache > Cache


1 /*
2  * The contents of this file are subject to the terms
3  * of the Common Development and Distribution License
4  * (the License). You may not use this file except in
5  * compliance with the License.
6  *
7  * You can obtain a copy of the license at
8  * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9  * glassfish/bootstrap/legal/CDDLv1.0.txt.
10  * See the License for the specific language governing
11  * permissions and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL
14  * Header Notice in each file and include the License file
15  * at glassfish/bootstrap/legal/CDDLv1.0.txt.
16  * If applicable, add the following below the CDDL Header,
17  * with the fields enclosed by brackets [] replaced by
18  * you own identifying information:
19  * "Portions Copyrighted [year] [name of copyright owner]"
20  *
21  * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22  */

23
24 /**
25  * Copyright 2000-2001 by iPlanet/Sun Microsystems, Inc.,
26  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
27  * All rights reserved.
28  */

29  
30 package com.sun.appserv.util.cache;
31
32 import java.util.ArrayList JavaDoc;
33 import java.util.Iterator JavaDoc;
34 import java.util.Enumeration JavaDoc;
35 import java.util.Map JavaDoc;
36 import java.util.Properties JavaDoc;
37
38 /**
39  * Cache
40  * Generic cache interface
41  */

42 public interface Cache {
43     
44     /**
45      * initialize the cache
46      * @param maxEntries maximum number of entries expected in the cache
47      * @param loadFactor the load factor
48      * @param props opaque list of properties for a given cache implementation
49      * @throws a generic Exception if the initialization failed
50      */

51     public void init(int maxEntries,
52                          float loadFactor, Properties JavaDoc props) throws Exception JavaDoc;
53
54     /**
55      * initialize the cache with the default load factor (0.75)
56      * @param maxEntries maximum number of entries expected in the cache
57      * @param props opaque list of properties for a given cache implementation
58      * @throws a generic Exception if the initialization failed
59      */

60     public void init(int maxEntries, Properties JavaDoc props) throws Exception JavaDoc;
61
62     /**
63      * add the cache module listener
64      * @param listener <code>CacheListener</code> implementation
65      */

66     public void addCacheListener(CacheListener listener);
67
68     /**
69      * get the index of the item given a key
70      * @param key of the entry
71      * @return the index to be used in the cache
72      */

73     public int getIndex(Object JavaDoc key);
74
75     /**
76      * get the item stored at the key.
77      * @param key lookup key
78      * @returns the item stored at the key; null if not found.
79      *
80      * This function returns first value, for a multi-valued key.
81      */

82     public Object JavaDoc get(Object JavaDoc key);
83
84     /**
85      * get all the items with the given key.
86      * @param key lookup key
87      * @returns an Iterator over the items with the given key
88      */

89     public Iterator JavaDoc getAll(Object JavaDoc key);
90
91     /**
92      * check if the cache contains the item at the key
93      * @param key lookup key
94      * @returns true if there is an item stored at the key; false if not.
95      */

96     public boolean contains(Object JavaDoc key);
97     
98     /**
99      * get an Iterator for the keys stored in the cache
100      * @returns an Iterator
101      */

102     public Iterator JavaDoc keys();
103
104     /**
105      * get an Enumeration for the keys stored in the cache
106      * @returns an Enumeration
107      * XXX: should use Iterator which is based on Collections
108      */

109     public Enumeration JavaDoc elements();
110
111     /**
112      * get an Iterator for the values stored in the cache
113      * @returns an Iterator
114      */

115     public Iterator JavaDoc values();
116
117     /**
118      * cache the given value at the specified key and return previous value
119      * @param key lookup key
120      * @param object item value to be stored
121      * @returns the previous item stored at the key; null if not found.
122      *
123      * This function replaces first value, for a multi-valued key.
124      */

125     public Object JavaDoc put(Object JavaDoc key, Object JavaDoc value);
126
127     /**
128      * cache the given value at the specified key and return previous value
129      * @param key lookup key
130      * @param object item value to be stored
131      * @param size in bytes of the value being cached
132      * @returns the previous item stored at the key; null if not found.
133      *
134      * This function replaces first value, for a multi-valued key.
135      */

136     public Object JavaDoc put(Object JavaDoc key, Object JavaDoc value, int size);
137
138     /**
139      * add the given value to the cache at the specified key
140      * @param key lookup key
141      * @param object item value to be stored
142      *
143      * This function is suitable for multi-valued keys.
144      */

145     public void add(Object JavaDoc key, Object JavaDoc value);
146
147     /**
148      * add the given value with specified size to the cache at specified key
149      * @param key lookup key
150      * @param object item value to be stored
151      * @param size in bytes of the value being added
152      *
153      * This function is suitable for multi-valued keys.
154      */

155     public void add(Object JavaDoc key, Object JavaDoc value, int size);
156
157     /**
158      * remove the item with the given key.
159      * @param key lookup key
160      * @returns the item stored at the key; null if not found.
161      *
162      * This function removes first value, for a multi-valued key.
163      */

164     public Object JavaDoc remove(Object JavaDoc key);
165
166     /**
167      * remove the given value stored at the key.
168      * @param key lookup key
169      * @param value to match (for multi-valued keys)
170      * @returns the item stored at the key; null if not found.
171      */

172     public Object JavaDoc remove(Object JavaDoc key, Object JavaDoc value);
173
174     /**
175      * remove all the item with the given key.
176      * @param key lookup key
177      */

178     public void removeAll(Object JavaDoc key);
179
180     /**
181      * wait for a refresh on the object associated with the key
182      * @param index index of the entry. The index must be obtained via
183      * one of the <code>getIndex()</code> methods.
184      * @returns <code>true</code> on successful notification, or
185      * <code>false</code> if there is no thread refreshing this entry.
186      */

187     public boolean waitRefresh(int index);
188
189     /**
190      * notify threads waiting for a refresh on the object associated with the key
191      * @param index index of the entry. The index must be obtained via
192      * one of the <code>getIndex()</code> methods.
193      */

194     public void notifyRefresh(int index);
195
196     /**
197      * clear all the entries from the cache.
198      * @returns the number of entries cleared from the cache
199      */

200     public int clear();
201
202     /**
203      * is this cache empty?
204      * @returns true if the cache is empty; false otherwise.
205      */

206     public boolean isEmpty();
207
208     /**
209      * get the number of entries in the cache
210      * @return the number of entries the cache currently holds
211      */

212     public int getEntryCount();
213
214     /**
215      * get the stats map
216      */

217     /**
218      * get the desired statistic counter
219      * @param key to corresponding stat
220      * @return an Object corresponding to the stat
221      * See also: Constant.java for the key
222      */

223     public Object JavaDoc getStatByName(String JavaDoc key);
224
225     /**
226      * get the stats snapshot
227      * @return a Map of stats
228      * See also: Constant.java for the keys
229      */

230     public Map JavaDoc getStats();
231
232     /**
233      * clear all stats
234      */

235     public void clearStats();
236
237     /**
238      * trim the expired entries from the cache.
239      * @param maxCount maximum number of invalid entries to trim
240      * specify Integer.MAX_VALUE to trim all timedout entries
241      *
242      * This call is to be scheduled by a thread managed by the container.
243      */

244     public void trimExpiredEntries(int maxCount);
245
246     /**
247      * Destroys this cache. This method should perform final clean ups.
248      */

249     public void destroy();
250 }
251
Popular Tags