1 package org.apache.commons.jcs3.access.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.util.Map;
23 import java.util.Set;
24 import java.util.function.Supplier;
25
26 import org.apache.commons.jcs3.access.exception.CacheException;
27 import org.apache.commons.jcs3.engine.behavior.ICacheElement;
28 import org.apache.commons.jcs3.engine.behavior.IElementAttributes;
29
30 /**
31 * ICacheAccess defines the behavior for client access.
32 */
33 public interface ICacheAccess<K, V>
34 extends ICacheAccessManagement
35 {
36 /**
37 * Basic get method.
38 * <p>
39 * @param name
40 * @return Object or null if not found.
41 */
42 V get(K name);
43
44 /**
45 * Basic get method. If the object cannot be found in the cache, it will be
46 * retrieved by calling the supplier and subsequently storing it in the cache.
47 * <p>
48 * @param name
49 * @param supplier supplier to be called if the value is not found
50 * @return Object.
51 */
52 V get(K name, Supplier<V> supplier);
53
54 /**
55 * Retrieve matching objects from the cache region this instance provides access to.
56 * <p>
57 * @param pattern - a key pattern for the objects stored
58 * @return A map of key to values. These are stripped from the wrapper.
59 */
60 Map<K, V> getMatching(String pattern);
61
62 /**
63 * Puts in cache if an item does not exist with the name in that region.
64 * <p>
65 * @param name
66 * @param obj
67 * @throws CacheException
68 */
69 void putSafe(K name, V obj)
70 throws CacheException;
71
72 /**
73 * Puts and/or overrides an element with the name in that region.
74 * <p>
75 * @param name
76 * @param obj
77 * @throws CacheException
78 */
79 void put(K name, V obj)
80 throws CacheException;
81
82 /**
83 * Description of the Method
84 * <p>
85 * @param name
86 * @param obj
87 * @param attr
88 * @throws CacheException
89 */
90 void put(K name, V obj, IElementAttributes attr)
91 throws CacheException;
92
93 /**
94 * This method returns the ICacheElement<K, V> wrapper which provides access to element info and other
95 * attributes.
96 * <p>
97 * This returns a reference to the wrapper. Any modifications will be reflected in the cache. No
98 * defensive copy is made.
99 * <p>
100 * This method is most useful if you want to determine things such as the how long the element
101 * has been in the cache.
102 * <p>
103 * The last access time in the ElementAttributes should be current.
104 * <p>
105 * @param name Key the object is stored as
106 * @return The ICacheElement<K, V> if the object is found or null
107 */
108 ICacheElement<K, V> getCacheElement(K name);
109
110 /**
111 * Get multiple elements from the cache based on a set of cache keys.
112 * <p>
113 * This method returns the ICacheElement<K, V> wrapper which provides access to element info and other
114 * attributes.
115 * <p>
116 * This returns a reference to the wrapper. Any modifications will be reflected in the cache. No
117 * defensive copy is made.
118 * <p>
119 * This method is most useful if you want to determine things such as the how long the element
120 * has been in the cache.
121 * <p>
122 * The last access time in the ElementAttributes should be current.
123 * <p>
124 * @param names set of Object cache keys
125 * @return a map of Object key to ICacheElement<K, V> element, or empty map if none of the keys are
126 * present
127 */
128 Map<K, ICacheElement<K, V>> getCacheElements(Set<K> names);
129
130 /**
131 * Get multiple elements from the cache based on a set of cache keys.
132 * <p>
133 * This method returns the ICacheElement<K, V> wrapper which provides access to element info and other
134 * attributes.
135 * <p>
136 * This returns a reference to the wrapper. Any modifications will be reflected in the cache. No
137 * defensive copy is made.
138 * <p>
139 * This method is most useful if you want to determine things such as the how long the element
140 * has been in the cache.
141 * <p>
142 * The last access time in the ElementAttributes should be current.
143 * <p>
144 * @param pattern key search pattern
145 * @return a map of Object key to ICacheElement<K, V> element, or empty map if no keys match the
146 * pattern
147 */
148 Map<K, ICacheElement<K, V>> getMatchingCacheElements(String pattern);
149
150 /**
151 * Remove an object for this key if one exists, else do nothing.
152 * <p>
153 * @param name
154 * @throws CacheException
155 */
156 void remove(K name)
157 throws CacheException;
158
159 /**
160 * Reset the attributes on the object matching this key name.
161 * <p>
162 * @param name
163 * @param attributes
164 * @throws CacheException
165 */
166 void resetElementAttributes(K name, IElementAttributes attributes)
167 throws CacheException;
168
169 /**
170 * Gets the elementAttributes attribute of the ICacheAccess object
171 * <p>
172 * @param name
173 * @return The elementAttributes value
174 * @throws CacheException
175 */
176 IElementAttributes getElementAttributes(K name)
177 throws CacheException;
178 }