zkoss/zk

/* Cache.java

    Purpose:
        
    Description:
        
    History:
        Thu Sep  6 15:35:06     2007, Created by tomyeh

Copyright (C) 2007 Potix Corporation. All Rights Reserved.

{{IS_RIGHT
    This program is distributed under LGPL Version 2.1 in the hope that
    it will be useful, but WITHOUT ANY WARRANTY.
}}IS_RIGHT
*/
package org.zkoss.util;

/**
 * Represents a cache.
 * The interface is similar to java.util.Map but simpler to implement.
 *
 * @author tomyeh
 * @since 3.0.0
 */
public interface Cache<K,V> {
    /** Returns whether the specified key is stored.
     */
    public boolean containsKey(Object key);
    /** Returns the object of the specified key, or null if not found.
     */
    public V get(Object key);
    /** Stores an object to the cache.
     * @return the previous value of the same, or null if no such value
     */
    public V put(K key, V value);
    /** Removes an object from the cache.
     * @return the object if found.
     */
    public V remove(Object key);
    /** Clears all objects being cached.
     */
    public void clear();

    //Control//
    /** The default minimal lifetime, unit=milliseconds. It is 30 minutes. */
    public static final int DEFAULT_LIFETIME = 30 * 60 * 1000;
    /** The default maximal allowed size. It is 512. */
    public static final int DEFAULT_MAX_SIZE = 512;

    /**
     * Returns the minimal lifetime, unit=milliseconds.
     * An mapping won't be removed by GC unless the minimal lifetime
     * or the maximal allowed size exceeds.
     * @see #getMaxSize
     */
    public int getLifetime();
    /**
     * Sets the minimal lifetime. Default: {@link #DEFAULT_LIFETIME}.
     *
     * @param lifetime the lifetime, unit=milliseconds;
     * if non-positive, they will be removed immediately.
     * @see #getLifetime
     */
    public void setLifetime(int lifetime);
    /**
     * Returns the maximal allowed size. Default: {@link #DEFAULT_MAX_SIZE}.
     * An mapping won't be removed by GC unless the minimal lifetime
     * or the maximal allowed size exceeds.
     * @see #getLifetime
     */
    public int getMaxSize();
    /**
     * Sets the maximal allowed size.
     * @see #getMaxSize
     */
    public void setMaxSize(int maxsize);
}