View Javadoc

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  }