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