1 package org.apache.jcs.engine.memory.behavior;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22 import java.io.IOException;
23 import java.io.Serializable;
24 import java.util.Iterator;
25 import java.util.Set;
26
27 import org.apache.jcs.engine.behavior.ICacheElement;
28 import org.apache.jcs.engine.behavior.ICompositeCacheAttributes;
29 import org.apache.jcs.engine.control.CompositeCache;
30 import org.apache.jcs.engine.stats.behavior.IStats;
31
32 /***
33 * For the framework. Insures methods a MemoryCache needs to access.
34 *
35 */
36 public interface IMemoryCache
37 {
38 /***
39 * Initialize the memory cache
40 * <p>
41 * @param cache
42 * The cache (region) this memory store is attached to.
43 */
44 public void initialize( CompositeCache cache );
45
46 /***
47 * Destroy the memory cache
48 * <p>
49 * @throws IOException
50 */
51 public void dispose()
52 throws IOException;
53
54 /***
55 * Get the number of elements contained in the memory store
56 * <p>
57 * @return Element count
58 */
59 public int getSize();
60
61 /***
62 * Returns the historical and statistical data for a region's memory cache.
63 * <p>
64 * @return Statistics and Infor for the Memory Cache.
65 */
66 public IStats getStatistics();
67
68 /***
69 * Get an iterator for all elements in the memory cache. This should be
70 * removed since it is fairly dangerous. Other classes should not be able to
71 * directly access items in the memory cache.
72 * <p>
73 * @return An iterator
74 */
75 public Iterator getIterator();
76
77 /***
78 * Get an Array of the keys for all elements in the memory cache.
79 * <p>
80 * @return Object[]
81 * @TODO This should probably be done in chunks with a range pased in. This
82 * will be a problem if someone puts a 1,000,000 or so items in a
83 * region.
84 */
85 public Object[] getKeyArray();
86
87 /***
88 * Removes an item from the cache
89 * <p>
90 * @param key
91 * Identifies item to be removed
92 * @return Description of the Return Value
93 * @exception IOException
94 * Description of the Exception
95 */
96 public boolean remove( Serializable key )
97 throws IOException;
98
99 /***
100 * Removes all cached items from the cache.
101 * <p>
102 * @exception IOException
103 * Description of the Exception
104 */
105 public void removeAll()
106 throws IOException;
107
108 /***
109 * This instructs the memory cache to remove the <i>numberToFree</i>
110 * according to its eviction policy. For example, the LRUMemoryCache will
111 * remove the <i>numberToFree</i> least recently used items. These will be
112 * spooled to disk if a disk auxiliary is available.
113 * <p>
114 * @param numberToFree
115 * @return the number that were removed. if you ask to free 5, but there are
116 * only 3, you will get 3.
117 * @throws IOException
118 */
119 public int freeElements( int numberToFree )
120 throws IOException;
121
122 /***
123 * Get an item from the cache
124 * <p>
125 * @param key
126 * Description of the Parameter
127 * @return Description of the Return Value
128 * @exception IOException
129 * Description of the Exception
130 */
131 public ICacheElement get( Serializable key )
132 throws IOException;
133
134 /***
135 * Get an item from the cache without effecting its order or last access
136 * time
137 * <p>
138 * @param key
139 * Description of the Parameter
140 * @return The quiet value
141 * @exception IOException
142 * Description of the Exception
143 */
144 public ICacheElement getQuiet( Serializable key )
145 throws IOException;
146
147 /***
148 * Spools the item contained in the provided element to disk
149 * <p>
150 * @param ce
151 * Description of the Parameter
152 * @exception IOException
153 * Description of the Exception
154 */
155 public void waterfal( ICacheElement ce )
156 throws IOException;
157
158 /***
159 * Puts an item to the cache.
160 * <p>
161 * @param ce
162 * Description of the Parameter
163 * @exception IOException
164 * Description of the Exception
165 */
166 public void update( ICacheElement ce )
167 throws IOException;
168
169 /***
170 * Returns the CacheAttributes for the region.
171 * <p>
172 * @return The cacheAttributes value
173 */
174 public ICompositeCacheAttributes getCacheAttributes();
175
176 /***
177 * Sets the CacheAttributes of the region.
178 * <p>
179 * @param cattr
180 * The new cacheAttributes value
181 */
182 public void setCacheAttributes( ICompositeCacheAttributes cattr );
183
184 /***
185 * Gets the cache hub / region that uses the MemoryCache.
186 * <p>
187 * @return The cache value
188 */
189 public CompositeCache getCompositeCache();
190
191 /***
192 * Gets the set of keys of objects currently in the group.
193 * <p>
194 * @param group
195 * @return a Set of group keys.
196 */
197 public Set getGroupKeys( String group );
198
199 }