hunt.shiro.cache.Cache source code

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 module hunt.shiro.cache.Cache;
20 
21 
22 /**
23  * A Cache efficiently stores temporary objects primarily to improve an application's performance.
24  *
25  * <p>Shiro doesn't implement a full Cache mechanism itself, since that is outside the core competency of a
26  * Security framework.  Instead, this interface provides an abstraction (wrapper) API on top of an underlying
27  * cache framework's cache instance (e.g. JCache, Ehcache, JCS, OSCache, JBossCache, TerraCotta, Coherence,
28  * GigaSpaces, etc, etc), allowing a Shiro user to configure any cache mechanism they choose.
29  *
30  * @since 0.2
31  */
32 interface Cache(K, V) {
33 
34     /**
35      * Returns the Cached value stored under the specified {@code key} or
36      * {@code null} if there is no Cache entry for that {@code key}.
37      *
38      * @param key the key that the value was previous added with
39      * @return the cached object or {@code null} if there is no entry for the specified {@code key}
40      * @throws CacheException if there is a problem accessing the underlying cache system
41      */
42     V get(K key);
43 
44 
45     V get(K key, V value);
46 
47     /**
48      * Adds a Cache entry.
49      *
50      * @param key   the key used to identify the object being stored.
51      * @param value the value to be stored in the cache.
52      * @return the previous value associated with the given {@code key} or {@code null} if there was previous value
53      * @throws CacheException if there is a problem accessing the underlying cache system
54      */
55     V put(K key, V value);
56 
57     /**
58      * Remove the cache entry corresponding to the specified key.
59      *
60      * @param key the key of the entry to be removed.
61      * @return the previous value associated with the given {@code key} or {@code null} if there was previous value
62      * @throws CacheException if there is a problem accessing the underlying cache system
63      */
64     V remove(K key);
65 
66     /**
67      * Clear all entries from the cache.
68      *
69      * @throws CacheException if there is a problem accessing the underlying cache system
70      */
71     void clear();
72 
73     /**
74      * Returns the number of entries in the cache.
75      *
76      * @return the number of entries in the cache.
77      */
78     int size();
79 
80     /**
81      * Returns a view of all the keys for entries contained in this cache.
82      *
83      * @return a view of all the keys for entries contained in this cache.
84      */
85     K[] keys();
86 
87     /**
88      * Returns a view of all of the values contained in this cache.
89      *
90      * @return a view of all of the values contained in this cache.
91      */
92     V[] values();
93 }