001/**
002 *
003 * Copyright (c) 2014, the Railo Company Ltd. All rights reserved.
004 *
005 * This library is free software; you can redistribute it and/or
006 * modify it under the terms of the GNU Lesser General Public
007 * License as published by the Free Software Foundation; either 
008 * version 2.1 of the License, or (at your option) any later version.
009 * 
010 * This library is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
013 * Lesser General Public License for more details.
014 * 
015 * You should have received a copy of the GNU Lesser General Public 
016 * License along with this library.  If not, see <http://www.gnu.org/licenses/>.
017 * 
018 **/
019package lucee.commons.collection.concurrent;
020
021import lucee.commons.collection.concurrent.ConcurrentLinkedHashMapPro.Entry;
022
023public interface EvictionPolicy {
024        
025        /**
026         * Defines if element access can alter the ordering of elements in the 
027         * underlying cache. This method will be invoked by the underlying cache
028         * implementation when an entry access is generated.
029         * 
030         * <p>Invoking the <tt>get</tt> cache method results in an access to 
031         * the corresponding entry (assuming it exists after the invocation completes).
032         * <i>No other methods generate entry accesses.</i> In particular, operations
033         * on collection-views do <i>not</i> affect the order of iteration of 
034         * the backing cache.
035         * 
036         * @return true for access based ordering, false otherwise
037         */
038        public boolean accessOrder();
039        
040        /**
041         * Defines if element insertion can alter the ordering of elements in 
042         * the underlying cache. This method will be invoked by the underlying 
043         * cache implementation when an entry insertion is generated.
044         * 
045         * <p>Invoking the <tt>put</tt> cache method results in an insertion of the
046         * corresponding entry. The <tt>putAll</tt> method generates one entry
047         * insertion for each mapping in the specified map, in the order that key-value
048         * mappings are provided by the specified map's entry set iterator.
049         * <i>No other methods generate entry insertions.</i>
050         * 
051         * @return true for insertion based ordering, false otherwise
052         */
053        public boolean insertionOrder();
054        
055        /**
056         * This method will be invoked by the underlying cache implementation when a
057         * entry insertion is generated. For every entry insertion an entry eviction
058         * can take place if a cache size threshold has been defined and exceeded and
059         * this method's implementation returns a <i>not NULL<i> element. Invoking the 
060         * <tt>put</tt> cache method results in an insertion of the corresponding entry.
061         * The <tt>putAll</tt> method generates one entry insertion for each mapping
062         * in the specified map, in the order that key-value mappings are provided by
063         * the specified map's entry set iterator. <i>No other methods generate entry
064         * insertions.</i> In particular, operations on collection-views do <i>not</i>
065         * trigger element eviction for the backing cache.
066         * 
067         * @param head the head of the double linked list of all elements in cache
068         * @return the element that should be evicted or null if no eviction should happen
069         */
070        public Entry<?, ?> evictElement(Entry<?, ?> head);
071        
072        /**
073         * This method will be invoked by the underlying cache implementation when a
074         * entry insertion is generated. Invoking the <tt>put</tt> cache method results
075         * in an insertion of the corresponding entry. The <tt>putAll</tt> method 
076         * generates one entry insertion for each mapping in the specified map, 
077         * in the order that key-value mappings are provided by the specified map's
078         * entry set iterator. <i>No other methods generate entry insertions.</i>
079         * 
080         * <p>This method has no effect if {@link #insertionOrder()} method is implemented
081         * to return false, whereas the newly inserted element will be placed at the end 
082         * (just before the head) of the cache's double linked element list.
083         * 
084         * @param head the head of the double linked list of all elements in cache
085         * @param insertedEntry the cache entry that is inserted
086         * @return the element that will be preceding the newly inserted element
087         */
088        public Entry<?, ?> recordInsertion(Entry<?, ?> head, Entry<?, ?> insertedEntry);
089        
090        /**
091         * This method will be invoked by the underlying cache implementation when a
092         * entry access is generated. Invoking the <tt>get</tt> cache method results 
093         * in an access to the corresponding entry (assuming it exists after the 
094         * invocation completes).<i>No other methods generate entry accesses.</i>
095         * 
096         * <p>This method has no effect if {@link #accessOrder()} method is implemented
097         * to return false.
098         * 
099         * @param head the head of the double linked list of all elements in cache
100         * @param accessEntry the cache entry that is accessed
101         * @return the element that will be preceding the newly accessed element
102         */
103        public Entry<?, ?> recordAccess(Entry<?, ?> head, Entry<?, ?> accessedEntry);
104        
105}