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