001package org.apache.commons.jcs.access; 002 003/* 004 * Licensed to the Apache Software Foundation (ASF) under one 005 * or more contributor license agreements. See the NOTICE file 006 * distributed with this work for additional information 007 * regarding copyright ownership. The ASF licenses this file 008 * to you under the Apache License, Version 2.0 (the 009 * "License"); you may not use this file except in compliance 010 * with the License. You may obtain a copy of the License at 011 * 012 * http://www.apache.org/licenses/LICENSE-2.0 013 * 014 * Unless required by applicable law or agreed to in writing, 015 * software distributed under the License is distributed on an 016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 017 * KIND, either express or implied. See the License for the 018 * specific language governing permissions and limitations 019 * under the License. 020 */ 021 022import java.io.IOException; 023 024import org.apache.commons.jcs.access.behavior.ICacheAccessManagement; 025import org.apache.commons.jcs.access.exception.CacheException; 026import org.apache.commons.jcs.engine.behavior.ICompositeCacheAttributes; 027import org.apache.commons.jcs.engine.behavior.IElementAttributes; 028import org.apache.commons.jcs.engine.control.CompositeCache; 029import org.apache.commons.jcs.engine.stats.behavior.ICacheStats; 030 031/** 032 * This class provides the common methods for all types of access to the cache. 033 * <p> 034 * An instance of this class is tied to a specific cache region. Static methods are provided to get 035 * such instances. 036 * <p> 037 * Using this class you can retrieve an item, the item's wrapper, and the element's configuration. You can also put an 038 * item in the cache, remove an item, and clear a region. 039 * <p> 040 * The JCS class is the preferred way to access these methods. 041 */ 042public abstract class AbstractCacheAccess<K, V> 043 implements ICacheAccessManagement 044{ 045 /** 046 * The cache that a given instance of this class provides access to. 047 * <p> 048 * TODO Should this be the interface? 049 */ 050 private final CompositeCache<K, V> cacheControl; 051 052 /** 053 * Constructor for the CacheAccess object. 054 * <p> 055 * @param cacheControl The cache which the created instance accesses 056 */ 057 protected AbstractCacheAccess( CompositeCache<K, V> cacheControl ) 058 { 059 this.cacheControl = cacheControl; 060 } 061 062 /** 063 * Removes all of the elements from a region. 064 * <p> 065 * @throws CacheException 066 */ 067 @Override 068 public void clear() 069 throws CacheException 070 { 071 try 072 { 073 this.getCacheControl().removeAll(); 074 } 075 catch ( IOException e ) 076 { 077 throw new CacheException( e ); 078 } 079 } 080 081 /** 082 * This method is does not reset the attributes for items already in the cache. It could 083 * potentially do this for items in memory, and maybe on disk (which would be slow) but not 084 * remote items. Rather than have unpredictable behavior, this method just sets the default 085 * attributes. Items subsequently put into the cache will use these defaults if they do not 086 * specify specific attributes. 087 * <p> 088 * @param attr the default attributes. 089 * @throws CacheException if something goes wrong. 090 */ 091 @Override 092 public void setDefaultElementAttributes( IElementAttributes attr ) 093 throws CacheException 094 { 095 this.getCacheControl().setElementAttributes( attr ); 096 } 097 098 /** 099 * Retrieves A COPY OF the default element attributes used by this region. This does not provide 100 * a reference to the element attributes. 101 * <p> 102 * Each time an element is added to the cache without element attributes, the default element 103 * attributes are cloned. 104 * <p> 105 * @return the default element attributes used by this region. 106 * @throws CacheException 107 */ 108 @Override 109 public IElementAttributes getDefaultElementAttributes() 110 throws CacheException 111 { 112 return this.getCacheControl().getElementAttributes(); 113 } 114 115 /** 116 * This returns the ICacheStats object with information on this region and its auxiliaries. 117 * <p> 118 * This data can be formatted as needed. 119 * <p> 120 * @return ICacheStats 121 */ 122 @Override 123 public ICacheStats getStatistics() 124 { 125 return this.getCacheControl().getStatistics(); 126 } 127 128 /** 129 * @return A String version of the stats. 130 */ 131 @Override 132 public String getStats() 133 { 134 return this.getCacheControl().getStats(); 135 } 136 137 /** 138 * Dispose this region. Flushes objects to and closes auxiliary caches. This is a shutdown 139 * command! 140 * <p> 141 * To simply remove all elements from the region use clear(). 142 */ 143 @Override 144 public void dispose() 145 { 146 this.getCacheControl().dispose(); 147 } 148 149 /** 150 * Gets the ICompositeCacheAttributes of the cache region. 151 * <p> 152 * @return ICompositeCacheAttributes, the controllers config info, defined in the top section of 153 * a region definition. 154 */ 155 @Override 156 public ICompositeCacheAttributes getCacheAttributes() 157 { 158 return this.getCacheControl().getCacheAttributes(); 159 } 160 161 /** 162 * Sets the ICompositeCacheAttributes of the cache region. 163 * <p> 164 * @param cattr The new ICompositeCacheAttribute value 165 */ 166 @Override 167 public void setCacheAttributes( ICompositeCacheAttributes cattr ) 168 { 169 this.getCacheControl().setCacheAttributes( cattr ); 170 } 171 172 /** 173 * This instructs the memory cache to remove the <i>numberToFree</i> according to its eviction 174 * policy. For example, the LRUMemoryCache will remove the <i>numberToFree</i> least recently 175 * used items. These will be spooled to disk if a disk auxiliary is available. 176 * <p> 177 * @param numberToFree 178 * @return the number that were removed. if you ask to free 5, but there are only 3, you will 179 * get 3. 180 * @throws CacheException 181 */ 182 @Override 183 public int freeMemoryElements( int numberToFree ) 184 throws CacheException 185 { 186 int numFreed = -1; 187 try 188 { 189 numFreed = this.getCacheControl().getMemoryCache().freeElements( numberToFree ); 190 } 191 catch ( IOException ioe ) 192 { 193 String message = "Failure freeing memory elements."; 194 throw new CacheException( message, ioe ); 195 } 196 return numFreed; 197 } 198 199 public CompositeCache<K, V> getCacheControl() { 200 return cacheControl; 201 } 202 203}