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&lt;K, V&gt; 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}