1 package org.apache.commons.jcs.auxiliary;
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.logging.behavior.ICacheEvent;
24 import org.apache.commons.jcs.engine.logging.behavior.ICacheEventLogger;
25
26 import java.io.IOException;
27 import java.io.Serializable;
28 import java.util.Map;
29 import java.util.Set;
30
31 /**
32 * All ICacheEvents are defined as final. Children must implement process events. These are wrapped
33 * in event log parent calls.
34 *
35 * You can override the public method, but if you don't, the default will call getWithTiming.
36 */
37 public abstract class AbstractAuxiliaryCacheEventLogging<K, V>
38 extends AbstractAuxiliaryCache<K, V>
39 {
40 /**
41 * Puts an item into the cache.
42 *
43 * @param cacheElement
44 * @throws IOException
45 */
46 @Override
47 public void update( ICacheElement<K, V> cacheElement )
48 throws IOException
49 {
50 updateWithEventLogging( cacheElement );
51 }
52
53 /**
54 * Puts an item into the cache. Wrapped in logging.
55 *
56 * @param cacheElement
57 * @throws IOException
58 */
59 protected final void updateWithEventLogging( ICacheElement<K, V> cacheElement )
60 throws IOException
61 {
62 ICacheEvent<K> cacheEvent = createICacheEvent( cacheElement, ICacheEventLogger.UPDATE_EVENT );
63 try
64 {
65 processUpdate( cacheElement );
66 }
67 finally
68 {
69 logICacheEvent( cacheEvent );
70 }
71 }
72
73 /**
74 * Implementation of put.
75 *
76 * @param cacheElement
77 * @throws IOException
78 */
79 protected abstract void processUpdate( ICacheElement<K, V> cacheElement )
80 throws IOException;
81
82 /**
83 * Gets the item from the cache.
84 *
85 * @param key
86 * @return ICacheElement, a wrapper around the key, value, and attributes
87 * @throws IOException
88 */
89 @Override
90 public ICacheElement<K, V> get( K key )
91 throws IOException
92 {
93 return getWithEventLogging( key );
94 }
95
96 /**
97 * Gets the item from the cache. Wrapped in logging.
98 *
99 * @param key
100 * @return ICacheElement, a wrapper around the key, value, and attributes
101 * @throws IOException
102 */
103 protected final ICacheElement<K, V> getWithEventLogging( K key )
104 throws IOException
105 {
106 ICacheEvent<K> cacheEvent = createICacheEvent( getCacheName(), key, ICacheEventLogger.GET_EVENT );
107 try
108 {
109 return processGet( key );
110 }
111 finally
112 {
113 logICacheEvent( cacheEvent );
114 }
115 }
116
117 /**
118 * Implementation of get.
119 *
120 * @param key
121 * @return ICacheElement, a wrapper around the key, value, and attributes
122 * @throws IOException
123 */
124 protected abstract ICacheElement<K, V> processGet( K key )
125 throws IOException;
126
127 /**
128 * Gets multiple items from the cache based on the given set of keys.
129 *
130 * @param keys
131 * @return a map of K key to ICacheElement<K, V> element, or an empty map if there is no
132 * data in cache for any of these keys
133 * @throws IOException
134 */
135 @Override
136 public Map<K, ICacheElement<K, V>> getMultiple(Set<K> keys)
137 throws IOException
138 {
139 return getMultipleWithEventLogging( keys );
140 }
141
142 /**
143 * Gets multiple items from the cache based on the given set of keys.
144 *
145 * @param keys
146 * @return a map of K key to ICacheElement<K, V> element, or an empty map if there is no
147 * data in cache for any of these keys
148 * @throws IOException
149 */
150 protected final Map<K, ICacheElement<K, V>> getMultipleWithEventLogging(Set<K> keys )
151 throws IOException
152 {
153 ICacheEvent<Serializable> cacheEvent = createICacheEvent( getCacheName(), (Serializable) keys,
154 ICacheEventLogger.GETMULTIPLE_EVENT );
155 try
156 {
157 return processGetMultiple( keys );
158 }
159 finally
160 {
161 logICacheEvent( cacheEvent );
162 }
163 }
164
165 /**
166 * Implementation of getMultiple.
167 *
168 * @param keys
169 * @return a map of K key to ICacheElement<K, V> element, or an empty map if there is no
170 * data in cache for any of these keys
171 * @throws IOException
172 */
173 protected abstract Map<K, ICacheElement<K, V>> processGetMultiple(Set<K> keys)
174 throws IOException;
175
176 /**
177 * Gets items from the cache matching the given pattern. Items from memory will replace those
178 * from remote sources.
179 *
180 * This only works with string keys. It's too expensive to do a toString on every key.
181 *
182 * Auxiliaries will do their best to handle simple expressions. For instance, the JDBC disk
183 * cache will convert * to % and . to _
184 *
185 * @param pattern
186 * @return a map of K key to ICacheElement<K, V> element, or an empty map if there is no
187 * data matching the pattern.
188 * @throws IOException
189 */
190 @Override
191 public Map<K, ICacheElement<K, V>> getMatching( String pattern )
192 throws IOException
193 {
194 return getMatchingWithEventLogging( pattern );
195 }
196
197 /**
198 * Gets mmatching items from the cache based on the given pattern.
199 *
200 * @param pattern
201 * @return a map of K key to ICacheElement<K, V> element, or an empty map if there is no
202 * data matching the pattern.
203 * @throws IOException
204 */
205 protected final Map<K, ICacheElement<K, V>> getMatchingWithEventLogging( String pattern )
206 throws IOException
207 {
208 ICacheEvent<String> cacheEvent = createICacheEvent( getCacheName(), pattern, ICacheEventLogger.GETMATCHING_EVENT );
209 try
210 {
211 return processGetMatching( pattern );
212 }
213 finally
214 {
215 logICacheEvent( cacheEvent );
216 }
217 }
218
219 /**
220 * Implementation of getMatching.
221 *
222 * @param pattern
223 * @return a map of K key to ICacheElement<K, V> element, or an empty map if there is no
224 * data matching the pattern.
225 * @throws IOException
226 */
227 protected abstract Map<K, ICacheElement<K, V>> processGetMatching( String pattern )
228 throws IOException;
229
230 /**
231 * Removes the item from the cache. Wraps the remove in event logs.
232 *
233 * @param key
234 * @return boolean, whether or not the item was removed
235 * @throws IOException
236 */
237 @Override
238 public boolean remove( K key )
239 throws IOException
240 {
241 return removeWithEventLogging( key );
242 }
243
244 /**
245 * Removes the item from the cache. Wraps the remove in event logs.
246 *
247 * @param key
248 * @return boolean, whether or not the item was removed
249 * @throws IOException
250 */
251 protected final boolean removeWithEventLogging( K key )
252 throws IOException
253 {
254 ICacheEvent<K> cacheEvent = createICacheEvent( getCacheName(), key, ICacheEventLogger.REMOVE_EVENT );
255 try
256 {
257 return processRemove( key );
258 }
259 finally
260 {
261 logICacheEvent( cacheEvent );
262 }
263 }
264
265 /**
266 * Specific implementation of remove.
267 *
268 * @param key
269 * @return boolean, whether or not the item was removed
270 * @throws IOException
271 */
272 protected abstract boolean processRemove( K key )
273 throws IOException;
274
275 /**
276 * Removes all from the region. Wraps the removeAll in event logs.
277 *
278 * @throws IOException
279 */
280 @Override
281 public void removeAll()
282 throws IOException
283 {
284 removeAllWithEventLogging();
285 }
286
287 /**
288 * Removes all from the region. Wraps the removeAll in event logs.
289 *
290 * @throws IOException
291 */
292 protected final void removeAllWithEventLogging()
293 throws IOException
294 {
295 ICacheEvent<String> cacheEvent = createICacheEvent( getCacheName(), "all", ICacheEventLogger.REMOVEALL_EVENT );
296 try
297 {
298 processRemoveAll();
299 }
300 finally
301 {
302 logICacheEvent( cacheEvent );
303 }
304 }
305
306 /**
307 * Specific implementation of removeAll.
308 *
309 * @throws IOException
310 */
311 protected abstract void processRemoveAll()
312 throws IOException;
313
314 /**
315 * Synchronously dispose the remote cache; if failed, replace the remote handle with a zombie.
316 *
317 * @throws IOException
318 */
319 @Override
320 public void dispose()
321 throws IOException
322 {
323 disposeWithEventLogging();
324 }
325
326 /**
327 * Synchronously dispose the remote cache; if failed, replace the remote handle with a zombie.
328 * Wraps the removeAll in event logs.
329 *
330 * @throws IOException
331 */
332 protected final void disposeWithEventLogging()
333 throws IOException
334 {
335 ICacheEvent<String> cacheEvent = createICacheEvent( getCacheName(), "none", ICacheEventLogger.DISPOSE_EVENT );
336 try
337 {
338 processDispose();
339 }
340 finally
341 {
342 logICacheEvent( cacheEvent );
343 }
344 }
345
346 /**
347 * Specific implementation of dispose.
348 *
349 * @throws IOException
350 */
351 protected abstract void processDispose()
352 throws IOException;
353 }