1 package org.apache.commons.jcs3.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 java.io.IOException;
23 import java.util.Map;
24 import java.util.Set;
25
26 import org.apache.commons.jcs3.engine.CacheStatus;
27 import org.apache.commons.jcs3.engine.match.behavior.IKeyMatcher;
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 /** Delimiter of a cache name component. This is used for hierarchical deletion */
40 String NAME_COMPONENT_DELIMITER = ":";
41
42 /**
43 * Puts an item to the cache.
44 *
45 * @param element
46 * @throws IOException
47 */
48 void update( ICacheElement<K, V> element )
49 throws IOException;
50
51 /**
52 * Gets an item from the cache.
53 *
54 * @param key
55 * @return a cache element, or null if there is no data in cache for this key
56 * @throws IOException
57 */
58 ICacheElement<K, V> get( K key )
59 throws IOException;
60
61 /**
62 * Gets multiple items from the cache based on the given set of keys.
63 *
64 * @param keys
65 * @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
66 * @throws IOException
67 */
68 Map<K, ICacheElement<K, V>> getMultiple(Set<K> keys)
69 throws IOException;
70
71 /**
72 * Gets items from the cache matching the given pattern. Items from memory will replace those from remote sources.
73 *
74 * This only works with string keys. It's too expensive to do a toString on every key.
75 *
76 * Auxiliaries will do their best to handle simple expressions. For instance, the JDBC disk cache will convert * to % and . to _
77 *
78 * @param pattern
79 * @return a map of K key to ICacheElement<K, V> element, or an empty map if there is no data matching the pattern.
80 * @throws IOException
81 */
82 Map<K, ICacheElement<K, V>> getMatching(String pattern)
83 throws IOException;
84
85 /**
86 * Removes an item from the cache.
87 *
88 * @param key
89 * @return false if there was an error in removal
90 * @throws IOException
91 */
92 boolean remove( K key )
93 throws IOException;
94
95 /**
96 * Removes all cached items from the cache.
97 *
98 * @throws IOException
99 */
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 }