org.codehaus.cake.cache.policy.ReplacementPolicy Maven / Gradle / Ivy
/*
* Copyright 2008 Kasper Nielsen.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://cake.codehaus.org/LICENSE
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package org.codehaus.cake.cache.policy;
import org.codehaus.cake.cache.Cache;
import org.codehaus.cake.cache.CacheEntry;
/**
* A (cache) replacement policy determines which data item(s) should be evicted (deleted) from the cache when the free
* space is insufficient for accommodating a new item to be cached. Normally users should not need to implement this
* interface, only if they want to implement a custom replacement polices.
*
* A replacement policy does not control when or how many entries should be evicted only what entries should be evicted.
*
* This library comes with a number of predefined replacement policies, see
* {@link org.codehaus.cake.cache.policy.Policies} for the most commonly used policies.
*
* For performance reasons cache policies are not expected to be thread-safe. Instead, any cache implementation using a
* replacement policy must maintain thread safety.
*
* @author Kasper Nielsen
* @version $Id: ReplacementPolicy.java 491 2007-11-30 22:05:50Z kasper $
* @param
* the type of keys cached
* @param
* the type of values cached
*/
public interface ReplacementPolicy {
/**
* Called whenever a new entry is added to the cache. Normally a replacement policy will accept all entries in which
* case true should be returned for all entries. However,
*
* If the policy accepts the entry true should be returned an. A false return value
* indicates that the policy has rejected the entry, for example, if some property . If the entry is rejected the
* cache should not cache it.
*
* @param entry
* the entry to add to the replacement policy
* @return true if the entry was accepted by the replacement policy otherwise false.
*/
boolean add(CacheEntry entry);
/**
* Called whenever the cache removes references to all entries that are cached. Calling this method should have the
* same effect as calling {@link #remove(CacheEntry)} for each individual entry currently cached.
*/
void clear();
/**
* Called by the cache when insufficient space is available for new entries to be added to the cache. This method
* should return the entry that should be evicted next accordingly to the replacement policy.
*
* @return the entry that should be evicted or null if the policy does not contain any entries
*/
CacheEntry evictNext();
/**
* Called whenever an entry is removed by an external action in the cache. For example, the user has removed the
* entry by calling {@link Cache#remove(Object)}.
*
* @param entry
* the entry that was removed
*/
void remove(CacheEntry entry);
/**
* The specified previousentry wasupdated with a new value. If the policy chooses to cache this new
* entry instead of the previous entry the new entry should be returned. This is the normal behaviour of a
* replacement. However, for certain applications it might make sense to keep the previous entry instead of the new
* entry in which the previous entry should be returned. Finally, if null is returned both the
* previous and new entry are removed from the cache.
*
* @param previous
* the the previous entry
* @param newEntry
* the new entry
* @return newEntry if the policy accepted the new entry,previous if the policy wants to keep
* the previous entry, null if neither entries should be keept in the cache.
*/
CacheEntry replace(CacheEntry previous, CacheEntry newEntry);
/**
* Called whenever a entry is accessed in the cache. An entry is accessed whenever {@link Cache#get(Object)},
* {@link Cache#getEntry(Object)}, {@link Cache#getAll(java.util.Collection)} is called. Neither complete scans
* such as those performed by the cache's iterators or partial scan such as scan performed on a filtered list of
* entries.
*
* @param entry
* the entry that was accessed
*/
void touch(CacheEntry entry);
}