001package org.apache.commons.jcs.engine.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.CacheStatus;
023import org.apache.commons.jcs.engine.match.behavior.IKeyMatcher;
024
025import java.io.IOException;
026import java.util.Map;
027import java.util.Set;
028
029/**
030 * This is the top level interface for all cache like structures. It defines the methods used
031 * internally by JCS to access, modify, and instrument such structures.
032 * 
033 * This allows for a suite of reusable components for accessing such structures, for example
034 * asynchronous access via an event queue.
035 */
036public interface ICache<K, V>
037    extends ICacheType
038{
039    /**
040     * Puts an item to the cache.
041     * 
042     * @param element
043     * @throws IOException
044     */
045    void update( ICacheElement<K, V> element )
046        throws IOException;
047
048    /**
049     * Gets an item from the cache.
050     * 
051     * @param key
052     * @return a cache element, or null if there is no data in cache for this key
053     * @throws IOException
054     */
055    ICacheElement<K, V> get( K key )
056        throws IOException;
057
058    /**
059     * Gets multiple items from the cache based on the given set of keys.
060     * 
061     * @param keys
062     * @return a map of K key to ICacheElement&lt;K, V&gt; element, or an empty map if there is no data in cache for any of these keys
063     * @throws IOException
064     */
065    Map<K, ICacheElement<K, V>> getMultiple(Set<K> keys)
066        throws IOException;
067
068    /**
069     * Gets items from the cache matching the given pattern.  Items from memory will replace those from remote sources.
070     * 
071     * This only works with string keys.  It's too expensive to do a toString on every key.
072     * 
073     * Auxiliaries will do their best to handle simple expressions.  For instance, the JDBC disk cache will convert * to % and . to _
074     * 
075     * @param pattern
076     * @return a map of K key to ICacheElement&lt;K, V&gt; element, or an empty map if there is no data matching the pattern.
077     * @throws IOException
078     */
079    Map<K, ICacheElement<K, V>> getMatching(String pattern)
080        throws IOException;
081
082    /**
083     * Removes an item from the cache.
084     * 
085     * @param key
086     * @return false if there was an error in removal
087     * @throws IOException
088     */
089    boolean remove( K key )
090        throws IOException;
091
092    /**
093     * Removes all cached items from the cache.
094     * 
095     * @throws IOException
096     */
097    void removeAll()
098        throws IOException;
099
100    /**
101     * Prepares for shutdown.
102     * @throws IOException
103     */
104    void dispose()
105        throws IOException;
106
107    /**
108     * Returns the current cache size in number of elements.
109     * 
110     * @return number of elements
111     */
112    int getSize();
113
114    /**
115     * Returns the cache status.
116     * 
117     * @return Alive or Error
118     */
119    CacheStatus getStatus();
120
121    /**
122     * Returns the cache stats.
123     * 
124     * @return String of important historical information.
125     */
126    String getStats();
127
128    /**
129     * Returns the cache name.
130     * 
131     * @return usually the region name.
132     */
133    String getCacheName();
134
135    /**
136     * Sets the key matcher used by get matching.
137     * 
138     * @param keyMatcher
139     */
140    void setKeyMatcher( IKeyMatcher<K> keyMatcher );
141}