1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.shiro.cache;
20
21 import java.util.Collection;
22 import java.util.Set;
23
24 /**
25 * A Cache efficiently stores temporary objects primarily to improve an application's performance.
26 *
27 * <p>Shiro doesn't implement a full Cache mechanism itself, since that is outside the core competency of a
28 * Security framework. Instead, this interface provides an abstraction (wrapper) API on top of an underlying
29 * cache framework's cache instance (e.g. JCache, Ehcache, JCS, OSCache, JBossCache, TerraCotta, Coherence,
30 * GigaSpaces, etc, etc), allowing a Shiro user to configure any cache mechanism they choose.
31 *
32 * @since 0.2
33 */
34 public interface Cache<K, V> {
35
36 /**
37 * Returns the Cached value stored under the specified {@code key} or
38 * {@code null} if there is no Cache entry for that {@code key}.
39 *
40 * @param key the key that the value was previous added with
41 * @return the cached object or {@code null} if there is no entry for the specified {@code key}
42 * @throws CacheException if there is a problem accessing the underlying cache system
43 */
44 public V get(K key) throws CacheException;
45
46 /**
47 * Adds a Cache entry.
48 *
49 * @param key the key used to identify the object being stored.
50 * @param value the value to be stored in the cache.
51 * @return the previous value associated with the given {@code key} or {@code null} if there was previous value
52 * @throws CacheException if there is a problem accessing the underlying cache system
53 */
54 public V put(K key, V value) throws CacheException;
55
56 /**
57 * Remove the cache entry corresponding to the specified key.
58 *
59 * @param key the key of the entry to be removed.
60 * @return the previous value associated with the given {@code key} or {@code null} if there was previous value
61 * @throws CacheException if there is a problem accessing the underlying cache system
62 */
63 public V remove(K key) throws CacheException;
64
65 /**
66 * Clear all entries from the cache.
67 *
68 * @throws CacheException if there is a problem accessing the underlying cache system
69 */
70 public void clear() throws CacheException;
71
72 /**
73 * Returns the number of entries in the cache.
74 *
75 * @return the number of entries in the cache.
76 */
77 public int size();
78
79 /**
80 * Returns a view of all the keys for entries contained in this cache.
81 *
82 * @return a view of all the keys for entries contained in this cache.
83 */
84 public Set<K> keys();
85
86 /**
87 * Returns a view of all of the values contained in this cache.
88 *
89 * @return a view of all of the values contained in this cache.
90 */
91 public Collection<V> values();
92 }