%line | %branch | |||||||||
---|---|---|---|---|---|---|---|---|---|---|
org.apache.jcs.access.CacheAccess |
|
|
1 | package org.apache.jcs.access; |
|
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 java.io.IOException; |
|
23 | import java.io.Serializable; |
|
24 | ||
25 | import org.apache.commons.logging.Log; |
|
26 | import org.apache.commons.logging.LogFactory; |
|
27 | import org.apache.jcs.access.behavior.ICacheAccess; |
|
28 | import org.apache.jcs.access.exception.CacheException; |
|
29 | import org.apache.jcs.access.exception.InvalidArgumentException; |
|
30 | import org.apache.jcs.access.exception.InvalidHandleException; |
|
31 | import org.apache.jcs.access.exception.ObjectExistsException; |
|
32 | import org.apache.jcs.engine.CacheElement; |
|
33 | import org.apache.jcs.engine.behavior.ICacheElement; |
|
34 | import org.apache.jcs.engine.behavior.ICompositeCacheAttributes; |
|
35 | import org.apache.jcs.engine.behavior.IElementAttributes; |
|
36 | import org.apache.jcs.engine.control.CompositeCache; |
|
37 | import org.apache.jcs.engine.control.CompositeCacheManager; |
|
38 | import org.apache.jcs.engine.stats.behavior.ICacheStats; |
|
39 | ||
40 | /** |
|
41 | * This class provides an interface for all types of access to the cache. |
|
42 | * <p> |
|
43 | * An instance of this class is tied to a specific cache region. Static methods are provided to get |
|
44 | * such instances. |
|
45 | * <p> |
|
46 | * Using this class you can retrieve an item, the items wrapper, the element configuration, put an |
|
47 | * item in the cache, remove an item, and clear a region. |
|
48 | * <p> |
|
49 | * The JCS class is the prefered way to access these methods. |
|
50 | */ |
|
51 | 6 | public class CacheAccess |
52 | implements ICacheAccess |
|
53 | { |
|
54 | 6 | /** The logger. */ |
55 | 348 | private static final Log log = LogFactory.getLog( CacheAccess.class ); |
56 | ||
57 | /** |
|
58 | * Cache manager use by the various forms of defineRegion and getAccess |
|
59 | */ |
|
60 | private static CompositeCacheManager cacheMgr; |
|
61 | ||
62 | /** |
|
63 | * The cache that a given instance of this class provides access to. |
|
64 | * <p> |
|
65 | * @TODO Should this be the inteface? |
|
66 | */ |
|
67 | protected CompositeCache cacheControl; |
|
68 | ||
69 | /** |
|
70 | * Constructor for the CacheAccess object. |
|
71 | * <p> |
|
72 | * @param cacheControl The cache which the created instance accesses |
|
73 | */ |
|
74 | 15 | public CacheAccess( CompositeCache cacheControl ) |
75 | 645 | { |
76 | 665 | this.cacheControl = cacheControl; |
77 | 664 | } |
78 | ||
79 | // ----------------------------- static methods for access to cache regions |
|
80 | ||
81 | /** |
|
82 | * Define a new cache region with the given name. In the oracle specification, these attributes |
|
83 | * are global and not region specific, regional overirdes is a value add each region should be |
|
84 | * able to house both cache and element attribute sets. It is more efficient to define a cache |
|
85 | * in the props file and then strictly use the get access method. Use of the define region |
|
86 | * outside of an initialization block should be avoided. |
|
87 | * <p> |
|
88 | * @param name Name that will identify the region |
|
89 | * @return CacheAccess instance for the new region |
|
90 | * @exception CacheException |
|
91 | */ |
|
92 | public static CacheAccess defineRegion( String name ) |
|
93 | throws CacheException |
|
94 | { |
|
95 | 8 | ensureCacheManager(); |
96 | ||
97 | 8 | return new CacheAccess( cacheMgr.getCache( name ) ); |
98 | } |
|
99 | ||
100 | /** |
|
101 | * Define a new cache region with the specified name and attributes. |
|
102 | * <p> |
|
103 | * @param name Name that will identify the region |
|
104 | * @param cattr CompositeCacheAttributes for the region |
|
105 | * @return CacheAccess instance for the new region |
|
106 | * @exception CacheException |
|
107 | */ |
|
108 | public static CacheAccess defineRegion( String name, ICompositeCacheAttributes cattr ) |
|
109 | throws CacheException |
|
110 | { |
|
111 | 8 | ensureCacheManager(); |
112 | ||
113 | 8 | return new CacheAccess( cacheMgr.getCache( name, cattr ) ); |
114 | } |
|
115 | ||
116 | /** |
|
117 | * Define a new cache region with the specified name and attributes and return a CacheAccess to |
|
118 | * it. |
|
119 | * <p> |
|
120 | * @param name Name that will identify the region |
|
121 | * @param cattr CompositeCacheAttributes for the region |
|
122 | * @param attr Attributes for the region |
|
123 | * @return CacheAccess instance for the new region |
|
124 | * @exception CacheException |
|
125 | */ |
|
126 | public static CacheAccess defineRegion( String name, ICompositeCacheAttributes cattr, IElementAttributes attr ) |
|
127 | throws CacheException |
|
128 | { |
|
129 | 8 | ensureCacheManager(); |
130 | ||
131 | 8 | return new CacheAccess( cacheMgr.getCache( name, cattr, attr ) ); |
132 | } |
|
133 | ||
134 | /** |
|
135 | * Get a CacheAccess instance for the given region. |
|
136 | * <p> |
|
137 | * @param region Name that identifies the region |
|
138 | * @return CacheAccess instance for region |
|
139 | * @exception CacheException |
|
140 | */ |
|
141 | public static CacheAccess getAccess( String region ) |
|
142 | throws CacheException |
|
143 | { |
|
144 | 32 | ensureCacheManager(); |
145 | ||
146 | 32 | return new CacheAccess( cacheMgr.getCache( region ) ); |
147 | } |
|
148 | ||
149 | /** |
|
150 | * Get a CacheAccess instance for the given region with the given attributes. |
|
151 | * <p> |
|
152 | * @param region Name that identifies the region |
|
153 | * @param icca |
|
154 | * @return CacheAccess instance for region |
|
155 | * @exception CacheException |
|
156 | */ |
|
157 | public static CacheAccess getAccess( String region, ICompositeCacheAttributes icca ) |
|
158 | throws CacheException |
|
159 | { |
|
160 | 0 | ensureCacheManager(); |
161 | ||
162 | 0 | return new CacheAccess( cacheMgr.getCache( region, icca ) ); |
163 | } |
|
164 | ||
165 | /** |
|
166 | * Helper method which checks to make sure the cacheMgr class field is set, and if not requests |
|
167 | * an instance from CacheManagerFactory. |
|
168 | */ |
|
169 | protected static void ensureCacheManager() |
|
170 | { |
|
171 | 56 | synchronized ( CacheAccess.class ) |
172 | { |
|
173 | 56 | if ( cacheMgr == null ) |
174 | { |
|
175 | 8 | cacheMgr = CompositeCacheManager.getInstance(); |
176 | } |
|
177 | 56 | } |
178 | 56 | } |
179 | ||
180 | // ------------------------------------------------------- instance methods |
|
181 | ||
182 | /** |
|
183 | * Retrieve an object from the cache region this instance provides access to. |
|
184 | * <p> |
|
185 | * @param name Key the object is stored as |
|
186 | * @return The object if found or null |
|
187 | */ |
|
188 | public Object get( Object name ) |
|
189 | { |
|
190 | 1505649 | ICacheElement element = this.cacheControl.get( (Serializable) name ); |
191 | ||
192 | 1506218 | return ( element != null ) ? element.getVal() : class="keyword">null; |
193 | } |
|
194 | ||
195 | /** |
|
196 | * This method returns the ICacheElement wrapper which provides access to element info and other |
|
197 | * attributes. |
|
198 | * <p> |
|
199 | * This returns a reference to the wrapper. Any modifications will be reflected in the cache. No |
|
200 | * defensive copy is made. |
|
201 | * <p> |
|
202 | * This method is most useful if you want to determine things such as the how long the element |
|
203 | 67006 | * has been in the cache. |
204 | * <p> |
|
205 | 67006 | * The last access time in teh ElementAttributes should be current. |
206 | * <p> |
|
207 | * @param name Key the object is stored as |
|
208 | * @return The ICacheElement if the object is found or null |
|
209 | */ |
|
210 | public ICacheElement getCacheElement( Object name ) |
|
211 | { |
|
212 | 15 | return this.cacheControl.get( (Serializable) name ); |
213 | } |
|
214 | ||
215 | /** |
|
216 | * Place a new object in the cache, associated with key name. If there is currently an object |
|
217 | * associated with name in the region an ObjectExistsException is thrown. Names are scoped to a |
|
218 | * region so they must be unique within the region they are placed. |
|
219 | * <p> |
|
220 | * @param key Key object will be stored with |
|
221 | * @param value Object to store |
|
222 | * @exception CacheException and ObjectExistsException is thrown if the item is already in the |
|
223 | * cache. |
|
224 | */ |
|
225 | public void putSafe( Object key, Object value ) |
|
226 | 1 | throws CacheException |
227 | { |
|
228 | 8 | if ( this.cacheControl.get( (Serializable) key ) != null ) |
229 | { |
|
230 | 8 | throw new ObjectExistsException( "putSafe failed. Object exists in the cache for key [" + key |
231 | + "]. Remove first or use a non-safe put to override the value." ); |
|
232 | } |
|
233 | 0 | put( key, value ); |
234 | 0 | } |
235 | ||
236 | /** |
|
237 | * Place a new object in the cache, associated with key name. If there is currently an object |
|
238 | * associated with name in the region it is replaced. Names are scoped to a region so they must |
|
239 | * be unique within the region they are placed. ObjectExistsException |
|
240 | * @param name Key object will be stored with |
|
241 | * @param obj Object to store |
|
242 | * @exception CacheException |
|
243 | */ |
|
244 | public void put( Object name, Object obj ) |
|
245 | throws CacheException |
|
246 | { |
|
247 | // Call put with a copy of the contained caches default attributes. |
|
248 | // the attributes are copied by the cacheControl |
|
249 | 1472240 | put( name, obj, this.cacheControl.getElementAttributes() ); |
250 | 1472200 | } |
251 | ||
252 | /** |
|
253 | * Constructs a cache element with these attribures, and puts it into the cache. |
|
254 | * <p> |
|
255 | * If the key or the value is null, and InvalidArgumentException is thrown. |
|
256 | * <p> |
|
257 | * @see org.apache.jcs.access.behavior.ICacheAccess#put(java.lang.Object, java.lang.Object, |
|
258 | * org.apache.jcs.engine.behavior.IElementAttributes) |
|
259 | */ |
|
260 | public void put( Object key, Object val, IElementAttributes attr ) |
|
261 | throws CacheException |
|
262 | { |
|
263 | 1612299 | if ( key == null ) |
264 | { |
|
265 | 8 | throw new InvalidArgumentException( "Key must not be null" ); |
266 | } |
|
267 | 1612271 | else if ( val == null ) |
268 | { |
|
269 | 8 | throw new InvalidArgumentException( "Value must not be null" ); |
270 | 72505 | } |
271 | 72505 | |
272 | // Create the element and update. This may throw an IOException which |
|
273 | // should be wrapped by cache access. |
|
274 | try |
|
275 | { |
|
276 | 1612282 | CacheElement ce = new CacheElement( this.cacheControl.getCacheName(), (Serializable) key, |
277 | (Serializable) val ); |
|
278 | ||
279 | 1612104 | ce.setElementAttributes( attr ); |
280 | ||
281 | 1612183 | this.cacheControl.update( ce ); |
282 | } |
|
283 | 1 | catch ( Exception e ) |
284 | { |
|
285 | 72506 | throw new CacheException( e ); |
286 | 1612064 | } |
287 | 1612107 | } |
288 | ||
289 | 72505 | /** |
290 | * Destory the region and all objects within it. After calling this method, the Cache object can |
|
291 | * no longer be used as it will be closed. |
|
292 | * <p> |
|
293 | * @exception CacheException |
|
294 | * @deprecated |
|
295 | */ |
|
296 | public void destroy() |
|
297 | throws CacheException |
|
298 | 145010 | { |
299 | 72505 | try |
300 | { |
|
301 | 72505 | this.cacheControl.removeAll(); |
302 | } |
|
303 | 72505 | catch ( IOException e ) |
304 | { |
|
305 | 0 | throw new CacheException( e ); |
306 | 0 | } |
307 | 0 | } |
308 | ||
309 | 72505 | /** |
310 | * Removes all of the elements from a region. |
|
311 | * <p> |
|
312 | * @deprecated use clear() |
|
313 | * @throws CacheException |
|
314 | */ |
|
315 | public void remove() |
|
316 | throws CacheException |
|
317 | { |
|
318 | 0 | clear(); |
319 | 0 | } |
320 | ||
321 | /** |
|
322 | * Removes all of the elements from a region. |
|
323 | * <p> |
|
324 | * @throws CacheException |
|
325 | */ |
|
326 | public void clear() |
|
327 | throws CacheException |
|
328 | { |
|
329 | try |
|
330 | { |
|
331 | 79 | this.cacheControl.removeAll(); |
332 | } |
|
333 | 0 | catch ( IOException e ) |
334 | { |
|
335 | 0 | throw new CacheException( e ); |
336 | 79 | } |
337 | 79 | } |
338 | ||
339 | /** |
|
340 | * Invalidate all objects associated with key name, removing all references to the objects from |
|
341 | * the cache. |
|
342 | * <p> |
|
343 | * @param name Key that specifies object to invalidate |
|
344 | * @exception CacheException |
|
345 | * @deprecated use remove |
|
346 | */ |
|
347 | public void destroy( Object name ) |
|
348 | throws CacheException |
|
349 | { |
|
350 | 0 | this.cacheControl.remove( (Serializable) name ); |
351 | 0 | } |
352 | ||
353 | 1 | /** |
354 | * Removes a single item by name. |
|
355 | * <p> |
|
356 | * @param name the name of the item to remove. |
|
357 | * @throws CacheException |
|
358 | */ |
|
359 | 1 | public void remove( Object name ) |
360 | throws CacheException |
|
361 | { |
|
362 | 424363 | this.cacheControl.remove( (Serializable) name ); |
363 | 424367 | } |
364 | ||
365 | /** |
|
366 | * ResetAttributes allows for some of the attributes of a region to be reset in particular |
|
367 | * expiration time attriubtes, time to live, default time to live and idle time, and event |
|
368 | * handlers. Changing default settings on groups and regions will not affect existing objects. |
|
369 | * Only object loaded after the reset will use the new defaults. If no name argument is |
|
370 | * provided, the reset is applied to the region. |
|
371 | * <p> |
|
372 | * NOTE: this method is does not reset the attributes for items already in the cache. It could |
|
373 | * potentially do this for items in memory, and maybe on disk (which would be slow) but not |
|
374 | * remote items. Rather than have unpredicatble behavior, this method just sets the default |
|
375 | * attributes. |
|
376 | * <p> |
|
377 | * TODO is should be renamed "setDefaultElementAttributes" |
|
378 | * <p> |
|
379 | * @deprecated As of release 1.3 |
|
380 | * @see setDefaultElementAttributes |
|
381 | * @param attr New attributes for this region. |
|
382 | * @exception CacheException |
|
383 | * @exception InvalidHandleException |
|
384 | */ |
|
385 | public void resetElementAttributes( IElementAttributes attr ) |
|
386 | 2003 | throws CacheException, InvalidHandleException |
387 | 2003 | { |
388 | 0 | this.cacheControl.setElementAttributes( attr ); |
389 | 0 | } |
390 | ||
391 | /** |
|
392 | * This method is does not reset the attributes for items already in the cache. It could |
|
393 | * potentially do this for items in memory, and maybe on disk (which would be slow) but not |
|
394 | * remote items. Rather than have unpredicatble behavior, this method just sets the default |
|
395 | * attributes. Items subsequently put into the cache will use these defaults if they do not |
|
396 | * specify specific attributes. |
|
397 | * <p> |
|
398 | * @param attr the default attributes. |
|
399 | * @throws CacheException if something goes wrong. |
|
400 | */ |
|
401 | public void setDefaultElementAttributes( IElementAttributes attr ) |
|
402 | throws CacheException |
|
403 | { |
|
404 | 29 | this.cacheControl.setElementAttributes( attr ); |
405 | 29 | } |
406 | ||
407 | /** |
|
408 | * Reset attributes for a particular element in the cache. NOTE: this method is currently not |
|
409 | * implemented. |
|
410 | * <p> |
|
411 | * @param name Key of object to reset attributes for |
|
412 | * @param attr New attributes for the object |
|
413 | * @exception CacheException |
|
414 | * @exception InvalidHandleException if the item does not exist. |
|
415 | */ |
|
416 | public void resetElementAttributes( Object name, IElementAttributes attr ) |
|
417 | throws CacheException, InvalidHandleException |
|
418 | { |
|
419 | 0 | ICacheElement element = this.cacheControl.get( (Serializable) name ); |
420 | 0 | if ( element == null ) |
421 | { |
|
422 | 0 | throw new InvalidHandleException( "Object for name [" + name + "] is not in the cache" ); |
423 | } |
|
424 | ||
425 | // Although it will work currently, don't assume pass by reference here, |
|
426 | // i.e. don't do this: |
|
427 | // element.setElementAttributes( attr ); |
|
428 | // Another reason to call put is to force the changes to be distributed. |
|
429 | 0 | put( element.getKey(), element.getVal(), attr ); |
430 | ||
431 | 0 | } |
432 | ||
433 | /** |
|
434 | * GetElementAttributes will return an attribute object describing the current attributes |
|
435 | * associated with the object name. |
|
436 | * <p> |
|
437 | * This was confusing, so I created a new method with a clear name. |
|
438 | * <p> |
|
439 | * @deprecated As of release 1.3 |
|
440 | * @see getDefaultElementAttributes |
|
441 | * @return Attributes for this region |
|
442 | * @exception CacheException |
|
443 | */ |
|
444 | public IElementAttributes getElementAttributes() |
|
445 | throws CacheException |
|
446 | { |
|
447 | 0 | return this.cacheControl.getElementAttributes(); |
448 | } |
|
449 | ||
450 | /** |
|
451 | * Retrieves A COPY OF the default element attributes used by this region. This does not provide |
|
452 | * a reference to the element attributes. |
|
453 | * <p> |
|
454 | * Each time an element is added to the cache without element attributes, the default element |
|
455 | * attributes are cloned. |
|
456 | * <p> |
|
457 | * @return the deafualt element attributes used by this region. |
|
458 | * @throws CacheException |
|
459 | */ |
|
460 | public IElementAttributes getDefaultElementAttributes() |
|
461 | throws CacheException |
|
462 | { |
|
463 | 140036 | return this.cacheControl.getElementAttributes(); |
464 | } |
|
465 | ||
466 | /** |
|
467 | * GetElementAttributes will return an attribute object describing the current attributes |
|
468 | * associated with the object name. The name object must override the Object.equals and |
|
469 | * Object.hashCode methods. |
|
470 | * <p> |
|
471 | * @param name Key of object to get attributes for |
|
472 | * @return Attributes for the object, null if object not in cache |
|
473 | * @exception CacheException |
|
474 | */ |
|
475 | public IElementAttributes getElementAttributes( Object name ) |
|
476 | throws CacheException |
|
477 | { |
|
478 | 0 | IElementAttributes attr = null; |
479 | ||
480 | try |
|
481 | { |
|
482 | 0 | attr = this.cacheControl.getElementAttributes( (Serializable) name ); |
483 | } |
|
484 | 0 | catch ( IOException ioe ) |
485 | { |
|
486 | 0 | log.error( "Failure getting element attributes", ioe ); |
487 | 0 | } |
488 | ||
489 | 0 | return attr; |
490 | } |
|
491 | ||
492 | /** |
|
493 | * This returns the ICacheStats object with information on this region and its auxiliaries. |
|
494 | * <p> |
|
495 | * This data can be formatted as needed. |
|
496 | * <p> |
|
497 | * @return ICacheStats |
|
498 | */ |
|
499 | public ICacheStats getStatistics() |
|
500 | { |
|
501 | 0 | return this.cacheControl.getStatistics(); |
502 | } |
|
503 | ||
504 | /** |
|
505 | * @return A String version of the stats. |
|
506 | */ |
|
507 | public String getStats() |
|
508 | { |
|
509 | 55690 | return this.cacheControl.getStats(); |
510 | } |
|
511 | ||
512 | /** |
|
513 | * Dispose this region. Flushes objects to and closes auxiliary caches. This is a shutdown |
|
514 | * command! |
|
515 | * <p> |
|
516 | * To simply remove all elements from the region use clear(). |
|
517 | */ |
|
518 | public void dispose() |
|
519 | { |
|
520 | 0 | this.cacheControl.dispose(); |
521 | 0 | } |
522 | ||
523 | /** |
|
524 | * Gets the ICompositeCacheAttributes of the cache region. |
|
525 | * <p> |
|
526 | * @return ICompositeCacheAttributes, the controllers config info, defined in the top section of |
|
527 | * a region definition. |
|
528 | */ |
|
529 | public ICompositeCacheAttributes getCacheAttributes() |
|
530 | { |
|
531 | 109 | return this.cacheControl.getCacheAttributes(); |
532 | } |
|
533 | ||
534 | /** |
|
535 | * Sets the ICompositeCacheAttributes of the cache region. |
|
536 | * <p> |
|
537 | * @param cattr The new ICompositeCacheAttribute value |
|
538 | */ |
|
539 | public void setCacheAttributes( ICompositeCacheAttributes cattr ) |
|
540 | { |
|
541 | 0 | this.cacheControl.setCacheAttributes( cattr ); |
542 | 0 | } |
543 | 2 | |
544 | /** |
|
545 | * This instructs the memory cache to remove the <i>numberToFree</i> according to its eviction |
|
546 | * policy. For example, the LRUMemoryCache will remove the <i>numberToFree</i> least recently |
|
547 | * used items. These will be spooled to disk if a disk auxiliary is available. |
|
548 | * <p> |
|
549 | * @param numberToFree |
|
550 | * @return the number that were removed. if you ask to free 5, but there are only 3, you will |
|
551 | * get 3. |
|
552 | * @throws CacheException |
|
553 | */ |
|
554 | public int freeMemoryElements( class="keyword">int numberToFree ) |
|
555 | throws CacheException |
|
556 | { |
|
557 | 0 | int numFreed = -1; |
558 | try |
|
559 | { |
|
560 | 0 | numFreed = this.cacheControl.getMemoryCache().freeElements( numberToFree ); |
561 | } |
|
562 | 0 | catch ( IOException ioe ) |
563 | { |
|
564 | 0 | String message = "Failure freeing memory elements. "; |
565 | 9 | log.error( message, ioe ); |
566 | 0 | throw new CacheException( message + ioe.getMessage() ); |
567 | 0 | } |
568 | 0 | return numFreed; |
569 | } |
|
570 | } |
This report is generated by jcoverage, Maven and Maven JCoverage Plugin. |