package org.apache.avalon.excalibur.cache;

import org.apache.avalon.framework.component.Component;
import org.apache.avalon.framework.thread.ThreadSafe;

public interface Cache
    extends ThreadSafe, Component
{
    /**
     * Add listener.
     *
     * @param listener listener instance to add
     */
    void addCacheListener( final CacheListener listener );

    /**
     * Remove listener.
     *
     * @param listener listener instance to remove
     */
    void removeCacheListener( final CacheListener listener );

    /**
     * Return capacity of cache.
     *
     * @return capacity of cache
     */
    int capacity();
   
    /**
     * Return size of cache.
     *
     * @return the number of key-value mappings in this cache.
     */
    int size();

    /**
     * @param key
     * @param value
     * @return old value
     */
    Object put( Object key, Object value );

    /**
     * @param key
     * @return
     */
    Object get( Object key );

    /**
     * @param key
     * @return
     */
    boolean containsKey( Object key );

    /**
     * @param key
     * @return old value
     */
    Object remove( Object key );

    /**
     * Clear cache.
     */
    void clear();
}