001package org.apache.commons.jcs.engine.memory.behavior; 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 org.apache.commons.jcs.engine.behavior.ICacheElement; 023import org.apache.commons.jcs.engine.behavior.ICompositeCacheAttributes; 024import org.apache.commons.jcs.engine.control.CompositeCache; 025import org.apache.commons.jcs.engine.stats.behavior.IStats; 026 027import java.io.IOException; 028import java.util.Map; 029import java.util.Set; 030 031/** For the framework. Insures methods a MemoryCache needs to access. */ 032public interface IMemoryCache<K, V> 033{ 034 /** 035 * Initialize the memory cache 036 * <p> 037 * @param cache The cache (region) this memory store is attached to. 038 */ 039 void initialize( CompositeCache<K, V> cache ); 040 041 /** 042 * Destroy the memory cache 043 * <p> 044 * @throws IOException 045 */ 046 void dispose() 047 throws IOException; 048 049 /** 050 * Get the number of elements contained in the memory store 051 * <p> 052 * @return Element count 053 */ 054 int getSize(); 055 056 /** 057 * Returns the historical and statistical data for a region's memory cache. 058 * <p> 059 * @return Statistics and Info for the Memory Cache. 060 */ 061 IStats getStatistics(); 062 063 /** 064 * Get a set of the keys for all elements in the memory cache. 065 * <p> 066 * @return a set of the key type 067 * TODO This should probably be done in chunks with a range passed in. This 068 * will be a problem if someone puts a 1,000,000 or so items in a 069 * region. 070 */ 071 Set<K> getKeySet(); 072 073 /** 074 * Removes an item from the cache 075 * <p> 076 * @param key 077 * Identifies item to be removed 078 * @return Description of the Return Value 079 * @throws IOException 080 * Description of the Exception 081 */ 082 boolean remove( K key ) 083 throws IOException; 084 085 /** 086 * Removes all cached items from the cache. 087 * <p> 088 * @throws IOException 089 * Description of the Exception 090 */ 091 void removeAll() 092 throws IOException; 093 094 /** 095 * This instructs the memory cache to remove the <i>numberToFree</i> 096 * according to its eviction policy. For example, the LRUMemoryCache will 097 * remove the <i>numberToFree</i> least recently used items. These will be 098 * spooled to disk if a disk auxiliary is available. 099 * <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}