001/* 
002 * JKNIV, utils - Helper utilities for jdk code.
003 * 
004 * Copyright (C) 2017, the original author or authors.
005 *
006 * This library is free software; you can redistribute it and/or
007 * modify it under the terms of the GNU Lesser General Public
008 * License as published by the Free Software Foundation; either
009 * version 2.1 of the License.
010 * 
011 * This library is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014 * Lesser General Public License for more details.
015 * 
016 * You should have received a copy of the GNU Lesser General Public
017 * License along with this library; if not, write to the Free Software Foundation, Inc., 
018 * 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
019 */
020package net.sf.jkniv.cache;
021
022import java.util.Date;
023import java.util.Map;
024import java.util.Set;
025
026/**
027 * An object that maps keys to values. A map cannot contain duplicate keys;
028 * each key can map to at most one value.
029 *
030 * @param <K> the type of keys maintained by this map
031 * @param <V> Type of objects stored in cache
032 *
033 * @author Alisson Gomes
034 * @since 0.6.0
035 */
036public interface Cacheable<K, V>
037{
038    /**
039     * cache name
040     * @return the cache name 
041     */
042    String getName();
043    
044    /**
045     * policy that maintenance the capacity and expire time of data
046     * @return rules to cache maintain the data 
047     */
048    CachePolicy getPolicy();
049    
050    /**
051     * Policy to control the cache data
052     * @param policy that maintenance the capacity and expire time of data
053     */
054    void setPolicy(CachePolicy policy);
055    
056    /**
057     * Associates the specified value with the specified key in this cache
058     * If the cache previously contained a mapping for the key, the old value 
059     * is replaced by the specified value.
060     * @param key with which the specified value is to be associated
061     * @param value to be associated with the specified key
062     * @return the previous value associated with <tt>key</tt>, or
063     *         <tt>null</tt> if there isn't mapping for <tt>key</tt>.
064     * @throws IllegalArgumentException if some the <tt>key</tt> or <tt>value</tt> are {@code null}.
065     */
066    V put(K key, V value);
067
068    /**
069     * Returns the value to which the specified key is cached,
070     * or {@code null} if this cache contains no mapping for the key.
071     * @param key the key whose associated value is to be returned
072     * @return the value to which the specified key is cached, or
073     *         {@code null} if this map contains no mapping for the key
074     */
075    V get(K key);
076    
077    /**
078     * Returns a {@link Entry} view of the mappings contained in this cache.
079     * @param key the key whose associated with entry is to be returned
080     * @return a set view of the {@link Entry} contained in this cache, or
081     *         {@code null} if this map contains no mapping for the key
082     */
083    Cacheable.Entry<V> getEntry(K key);
084    
085    Set<java.util.Map.Entry<K, Cacheable.Entry<V>>> entrySet();
086    
087    Cacheable.Entry<V> remove(K key);
088
089    /**
090     * Removes all of the mappings from this map (optional operation). 
091     * The map will be empty after this call returns.
092     */
093    void clear();
094    
095    /**
096     * Returns the number of key-value mappings in this map. 
097     * If the cache contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.
098     * 
099     * @return the number of elements in this cache
100     */
101    long size();
102    
103    /**
104     * A cache entry (key-value pair).  The <tt>Cacheable.getEntry</tt> method returns
105     * a cache value view.
106     *
107     * @see Cacheable#getEntry(Object)
108     */
109    interface Entry<V>
110    {
111        /**
112         * Timestamp from cached value
113         * @return the timestamp when the value was cached
114         */
115        Date getTimestamp();
116        
117        /**
118         * Last access the cached value
119         * @return the timestamp from last access 
120         */
121        Date getLastAccess();
122        
123        /**
124         * Entry value from cache
125         * @return the value to which the entry cached, or
126         *         {@code null} if this cache contains no entry
127         */
128        V getValue();
129        
130        /**
131         * how many times this entry was reach
132         * @return quantity of times hit this entry
133         */
134        int hits();
135    }
136    
137}