001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.apache.shiro.cache;
020
021import java.util.Collection;
022import java.util.Set;
023
024/**
025 * A Cache efficiently stores temporary objects primarily to improve an application's performance.
026 *
027 * <p>Shiro doesn't implement a full Cache mechanism itself, since that is outside the core competency of a
028 * Security framework.  Instead, this interface provides an abstraction (wrapper) API on top of an underlying
029 * cache framework's cache instance (e.g. JCache, Ehcache, JCS, OSCache, JBossCache, TerraCotta, Coherence,
030 * GigaSpaces, etc, etc), allowing a Shiro user to configure any cache mechanism they choose.
031 *
032 * @since 0.2
033 */
034public interface Cache<K, V> {
035
036    /**
037     * Returns the Cached value stored under the specified {@code key} or
038     * {@code null} if there is no Cache entry for that {@code key}.
039     *
040     * @param key the key that the value was previous added with
041     * @return the cached object or {@code null} if there is no entry for the specified {@code key}
042     * @throws CacheException if there is a problem accessing the underlying cache system
043     */
044    public V get(K key) throws CacheException;
045
046    /**
047     * Adds a Cache entry.
048     *
049     * @param key   the key used to identify the object being stored.
050     * @param value the value to be stored in the cache.
051     * @return the previous value associated with the given {@code key} or {@code null} if there was previous value
052     * @throws CacheException if there is a problem accessing the underlying cache system
053     */
054    public V put(K key, V value) throws CacheException;
055
056    /**
057     * Remove the cache entry corresponding to the specified key.
058     *
059     * @param key the key of the entry to be removed.
060     * @return the previous value associated with the given {@code key} or {@code null} if there was previous value
061     * @throws CacheException if there is a problem accessing the underlying cache system
062     */
063    public V remove(K key) throws CacheException;
064
065    /**
066     * Clear all entries from the cache.
067     *
068     * @throws CacheException if there is a problem accessing the underlying cache system
069     */
070    public void clear() throws CacheException;
071
072    /**
073     * Returns the number of entries in the cache.
074     *
075     * @return the number of entries in the cache.
076     */
077    public int size();
078
079    /**
080     * Returns a view of all the keys for entries contained in this cache.
081     *
082     * @return a view of all the keys for entries contained in this cache.
083     */
084    public Set<K> keys();
085
086    /**
087     * Returns a view of all of the values contained in this cache.
088     *
089     * @return a view of all of the values contained in this cache.
090     */
091    public Collection<V> values();
092}