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