1 package org.apache.commons.jcs.engine.behavior; 2 3 /* 4 * Licensed to the Apache Software Foundation (ASF) under one 5 * or more contributor license agreements. See the NOTICE file 6 * distributed with this work for additional information 7 * regarding copyright ownership. The ASF licenses this file 8 * to you under the Apache License, Version 2.0 (the 9 * "License"); you may not use this file except in compliance 10 * with the License. You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, 15 * software distributed under the License is distributed on an 16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17 * KIND, either express or implied. See the License for the 18 * specific language governing permissions and limitations 19 * under the License. 20 */ 21 22 import org.apache.commons.jcs.engine.CacheStatus; 23 import org.apache.commons.jcs.engine.match.behavior.IKeyMatcher; 24 25 import java.io.IOException; 26 import java.util.Map; 27 import java.util.Set; 28 29 /** 30 * This is the top level interface for all cache like structures. It defines the methods used 31 * internally by JCS to access, modify, and instrument such structures. 32 * 33 * This allows for a suite of reusable components for accessing such structures, for example 34 * asynchronous access via an event queue. 35 */ 36 public interface ICache<K, V> 37 extends ICacheType 38 { 39 /** 40 * Puts an item to the cache. 41 * 42 * @param element 43 * @throws IOException 44 */ 45 void update( ICacheElement<K, V> element ) 46 throws IOException; 47 48 /** 49 * Gets an item from the cache. 50 * 51 * @param key 52 * @return a cache element, or null if there is no data in cache for this key 53 * @throws IOException 54 */ 55 ICacheElement<K, V> get( K key ) 56 throws IOException; 57 58 /** 59 * Gets multiple items from the cache based on the given set of keys. 60 * 61 * @param keys 62 * @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 63 * @throws IOException 64 */ 65 Map<K, ICacheElement<K, V>> getMultiple(Set<K> keys) 66 throws IOException; 67 68 /** 69 * Gets items from the cache matching the given pattern. Items from memory will replace those from remote sources. 70 * 71 * This only works with string keys. It's too expensive to do a toString on every key. 72 * 73 * Auxiliaries will do their best to handle simple expressions. For instance, the JDBC disk cache will convert * to % and . to _ 74 * 75 * @param pattern 76 * @return a map of K key to ICacheElement<K, V> element, or an empty map if there is no data matching the pattern. 77 * @throws IOException 78 */ 79 Map<K, ICacheElement<K, V>> getMatching(String pattern) 80 throws IOException; 81 82 /** 83 * Removes an item from the cache. 84 * 85 * @param key 86 * @return false if there was an error in removal 87 * @throws IOException 88 */ 89 boolean remove( K key ) 90 throws IOException; 91 92 /** 93 * Removes all cached items from the cache. 94 * 95 * @throws IOException 96 */ 97 void removeAll() 98 throws IOException; 99 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 }