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  ;
33  import java.util.Iterator  ;
34  import java.util.Enumeration  ;
35  import java.util.Map  ;
36  import java.util.Properties  ;
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   props) throws Exception  ;
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   props) throws Exception  ;
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   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   get(Object   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   getAll(Object   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   key);
97      
98      /**
99       * get an Iterator for the keys stored in the cache
100      * @returns an Iterator
101      */
102     public Iterator   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   elements();
110 
111     /**
112      * get an Iterator for the values stored in the cache
113      * @returns an Iterator
114      */
115     public Iterator   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   put(Object   key, Object   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   put(Object   key, Object   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   key, Object   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   key, Object   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   remove(Object   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   remove(Object   key, Object   value);
173 
174     /**
175      * remove all the item with the given key.
176      * @param key lookup key
177      */
178     public void removeAll(Object   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   getStatByName(String   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   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags