1 package org.apache.commons.jcs.engine.memory.behavior;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import org.apache.commons.jcs.engine.behavior.ICacheElement;
23 import org.apache.commons.jcs.engine.behavior.ICompositeCacheAttributes;
24 import org.apache.commons.jcs.engine.control.CompositeCache;
25 import org.apache.commons.jcs.engine.stats.behavior.IStats;
26
27 import java.io.IOException;
28 import java.util.Map;
29 import java.util.Set;
30
31 /** For the framework. Insures methods a MemoryCache needs to access. */
32 public interface IMemoryCache<K, V>
33 {
34 /**
35 * Initialize the memory cache
36 * <p>
37 * @param cache The cache (region) this memory store is attached to.
38 */
39 void initialize( CompositeCache<K, V> cache );
40
41 /**
42 * Destroy the memory cache
43 * <p>
44 * @throws IOException
45 */
46 void dispose()
47 throws IOException;
48
49 /**
50 * Get the number of elements contained in the memory store
51 * <p>
52 * @return Element count
53 */
54 int getSize();
55
56 /**
57 * Returns the historical and statistical data for a region's memory cache.
58 * <p>
59 * @return Statistics and Info for the Memory Cache.
60 */
61 IStats getStatistics();
62
63 /**
64 * Get a set of the keys for all elements in the memory cache.
65 * <p>
66 * @return a set of the key type
67 * TODO This should probably be done in chunks with a range passed in. This
68 * will be a problem if someone puts a 1,000,000 or so items in a
69 * region.
70 */
71 Set<K> getKeySet();
72
73 /**
74 * Removes an item from the cache
75 * <p>
76 * @param key
77 * Identifies item to be removed
78 * @return Description of the Return Value
79 * @throws IOException
80 * Description of the Exception
81 */
82 boolean remove( K key )
83 throws IOException;
84
85 /**
86 * Removes all cached items from the cache.
87 * <p>
88 * @throws IOException
89 * Description of the Exception
90 */
91 void removeAll()
92 throws IOException;
93
94 /**
95 * This instructs the memory cache to remove the <i>numberToFree</i>
96 * according to its eviction policy. For example, the LRUMemoryCache will
97 * remove the <i>numberToFree</i> least recently used items. These will be
98 * spooled to disk if a disk auxiliary is available.
99 * <p>
100 * @param numberToFree
101 * @return the number that were removed. if you ask to free 5, but there are
102 * only 3, you will get 3.
103 * @throws IOException
104 */
105 int freeElements( int numberToFree )
106 throws IOException;
107
108 /**
109 * Get an item from the cache
110 * <p>
111 * @param key
112 * Description of the Parameter
113 * @return Description of the Return Value
114 * @throws IOException
115 * Description of the Exception
116 */
117 ICacheElement<K, V> get( K key )
118 throws IOException;
119
120 /**
121 * Gets multiple items from the cache based on the given set of keys.
122 * <p>
123 * @param keys
124 * @return a map of K key to ICacheElement<K, V> element, or an empty map
125 * if there is no data in cache for any of these keys
126 * @throws IOException
127 */
128 Map<K, ICacheElement<K, V>> getMultiple( Set<K> keys )
129 throws IOException;
130
131 /**
132 * Get an item from the cache without effecting its order or last access
133 * time
134 * <p>
135 * @param key
136 * Description of the Parameter
137 * @return The quiet value
138 * @throws IOException
139 * Description of the Exception
140 */
141 ICacheElement<K, V> getQuiet( K key )
142 throws IOException;
143
144 /**
145 * Spools the item contained in the provided element to disk
146 * <p>
147 * @param ce
148 * Description of the Parameter
149 * @throws IOException
150 * Description of the Exception
151 */
152 void waterfal( ICacheElement<K, V> ce )
153 throws IOException;
154
155 /**
156 * Puts an item to the cache.
157 * <p>
158 * @param ce
159 * Description of the Parameter
160 * @throws IOException
161 * Description of the Exception
162 */
163 void update( ICacheElement<K, V> ce )
164 throws IOException;
165
166 /**
167 * Returns the CacheAttributes for the region.
168 * <p>
169 * @return The cacheAttributes value
170 */
171 ICompositeCacheAttributes getCacheAttributes();
172
173 /**
174 * Sets the CacheAttributes of the region.
175 * <p>
176 * @param cattr
177 * The new cacheAttributes value
178 */
179 void setCacheAttributes( ICompositeCacheAttributes cattr );
180
181 /**
182 * Gets the cache hub / region that uses the MemoryCache.
183 * <p>
184 * @return The cache value
185 */
186 CompositeCache<K, V> getCompositeCache();
187 }