1 /*
2 * Copyright 2002-2014 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.springframework.cache;
18
19 /**
20 * Interface that defines the common cache operations.
21 *
22 * <b>Note:</b> Due to the generic use of caching, it is recommended that
23 * implementations allow storage of <tt>null</tt> values (for example to
24 * cache methods that return {@code null}).
25 *
26 * @author Costin Leau
27 * @author Juergen Hoeller
28 * @since 3.1
29 */
30 public interface Cache {
31
32 /**
33 * Return the cache name.
34 */
35 String getName();
36
37 /**
38 * Return the the underlying native cache provider.
39 */
40 Object getNativeCache();
41
42 /**
43 * Return the value to which this cache maps the specified key.
44 * <p>Returns {@code null} if the cache contains no mapping for this key;
45 * otherwise, the cached value (which may be {@code null} itself) will
46 * be returned in a {@link ValueWrapper}.
47 * @param key the key whose associated value is to be returned
48 * @return the value to which this cache maps the specified key,
49 * contained within a {@link ValueWrapper} which may also hold
50 * a cached {@code null} value. A straight {@code null} being
51 * returned means that the cache contains no mapping for this key.
52 * @see #get(Object, Class)
53 */
54 ValueWrapper get(Object key);
55
56 /**
57 * Return the value to which this cache maps the specified key,
58 * generically specifying a type that return value will be cast to.
59 * <p>Note: This variant of {@code get} does not allow for differentiating
60 * between a cached {@code null} value and no cache entry found at all.
61 * Use the standard {@link #get(Object)} variant for that purpose instead.
62 * @param key the key whose associated value is to be returned
63 * @param type the required type of the returned value (may be
64 * {@code null} to bypass a type check; in case of a {@code null}
65 * value found in the cache, the specified type is irrelevant)
66 * @return the value to which this cache maps the specified key
67 * (which may be {@code null} itself), or also {@code null} if
68 * the cache contains no mapping for this key
69 * @throws IllegalStateException if a cache entry has been found
70 * but failed to match the specified type
71 * @see #get(Object)
72 * @since 4.0
73 */
74 <T> T get(Object key, Class<T> type);
75
76 /**
77 * Associate the specified value with the specified key in this cache.
78 * <p>If the cache previously contained a mapping for this key, the old
79 * value is replaced by the specified value.
80 * @param key the key with which the specified value is to be associated
81 * @param value the value to be associated with the specified key
82 */
83 void put(Object key, Object value);
84
85 /**
86 * Atomically associate the specified value with the specified key in this cache
87 * if it is not set already.
88 * <p>This is equivalent to:
89 * <pre><code>
90 * Object existingValue = cache.get(key);
91 * if (existingValue == null) {
92 * cache.put(key, value);
93 * return null;
94 * } else {
95 * return existingValue;
96 * }
97 * </code></pre>
98 * except that the action is performed atomically. While all out-of-the-box
99 * {@link CacheManager} implementations are able to perform the put atomically,
100 * the operation may also be implemented in two steps, e.g. with a check for
101 * presence and a subsequent put, in a non-atomic way. Check the documentation
102 * of the native cache implementation that you are using for more details.
103 * @param key the key with which the specified value is to be associated
104 * @param value the value to be associated with the specified key
105 * @return the value to which this cache maps the specified key (which may be
106 * {@code null} itself), or also {@code null} if the cache did not contain any
107 * mapping for that key prior to this call. Returning {@code null} is therefore
108 * an indicator that the given {@code value} has been associated with the key.
109 * @since 4.1
110 */
111 ValueWrapper putIfAbsent(Object key, Object value);
112
113 /**
114 * Evict the mapping for this key from this cache if it is present.
115 * @param key the key whose mapping is to be removed from the cache
116 */
117 void evict(Object key);
118
119 /**
120 * Remove all mappings from the cache.
121 */
122 void clear();
123
124
125 /**
126 * A (wrapper) object representing a cache value.
127 */
128 interface ValueWrapper {
129
130 /**
131 * Return the actual value in the cache.
132 */
133 Object get();
134 }
135
136 }