001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.collections4.map;
018
019import java.io.IOException;
020import java.io.ObjectInputStream;
021import java.io.ObjectOutputStream;
022import java.io.Serializable;
023import java.util.Map;
024
025import org.apache.commons.collections4.BoundedMap;
026
027/**
028 * A <code>Map</code> implementation with a fixed maximum size which removes
029 * the least recently used entry if an entry is added when full.
030 * <p>
031 * The least recently used algorithm works on the get and put operations only.
032 * Iteration of any kind, including setting the value by iteration, does not
033 * change the order. Queries such as containsKey and containsValue or access
034 * via views also do not change the order.
035 * <p>
036 * A somewhat subtle ramification of the least recently used
037 * algorithm is that calls to {@link #get(Object)} stand a very good chance
038 * of modifying the map's iteration order and thus invalidating any
039 * iterators currently in use.  It is therefore suggested that iterations
040 * over an {@link LRUMap} instance access entry values only through a
041 * {@link org.apache.commons.collections4.MapIterator MapIterator} or {@link #entrySet()} iterator.
042 * <p>
043 * The map implements <code>OrderedMap</code> and entries may be queried using
044 * the bidirectional <code>OrderedMapIterator</code>. The order returned is
045 * least recently used to most recently used. Iterators from map views can
046 * also be cast to <code>OrderedIterator</code> if required.
047 * <p>
048 * All the available iterators can be reset back to the start by casting to
049 * <code>ResettableIterator</code> and calling <code>reset()</code>.
050 * <p>
051 * <strong>Note that LRUMap is not synchronized and is not thread-safe.</strong>
052 * If you wish to use this map from multiple threads concurrently, you must use
053 * appropriate synchronization. The simplest approach is to wrap this map
054 * using {@link java.util.Collections#synchronizedMap(Map)}. This class may throw
055 * <code>NullPointerException</code>'s when accessed by concurrent threads.
056 *
057 * @since 3.0 (previously in main package v1.0)
058 * @version $Id: LRUMap.html 972397 2015-11-14 15:01:49Z tn $
059 */
060public class LRUMap<K, V>
061        extends AbstractLinkedMap<K, V> implements BoundedMap<K, V>, Serializable, Cloneable {
062
063    /** Serialisation version */
064    private static final long serialVersionUID = -612114643488955218L;
065    /** Default maximum size */
066    protected static final int DEFAULT_MAX_SIZE = 100;
067
068    /** Maximum size */
069    private transient int maxSize;
070    /** Scan behaviour */
071    private boolean scanUntilRemovable;
072
073    /**
074     * Constructs a new empty map with a maximum size of 100.
075     */
076    public LRUMap() {
077        this(DEFAULT_MAX_SIZE, DEFAULT_LOAD_FACTOR, false);
078    }
079
080    /**
081     * Constructs a new, empty map with the specified maximum size.
082     *
083     * @param maxSize  the maximum size of the map
084     * @throws IllegalArgumentException if the maximum size is less than one
085     */
086    public LRUMap(final int maxSize) {
087        this(maxSize, DEFAULT_LOAD_FACTOR);
088    }
089
090    /**
091     * Constructs a new, empty map with the specified maximum size.
092     *
093     * @param maxSize  the maximum size of the map
094     * @param initialSize  the initial size of the map
095     * @throws IllegalArgumentException if the maximum size is less than one
096     * @throws IllegalArgumentException if the initial size is negative or larger than the maximum size
097     * @since 4.1
098     */
099    public LRUMap(final int maxSize, final int initialSize) {
100        this(maxSize, initialSize, DEFAULT_LOAD_FACTOR);
101    }
102
103    /**
104     * Constructs a new, empty map with the specified maximum size.
105     *
106     * @param maxSize  the maximum size of the map
107     * @param scanUntilRemovable  scan until a removeable entry is found, default false
108     * @throws IllegalArgumentException if the maximum size is less than one
109     * @since 3.1
110     */
111    public LRUMap(final int maxSize, final boolean scanUntilRemovable) {
112        this(maxSize, DEFAULT_LOAD_FACTOR, scanUntilRemovable);
113    }
114
115    /**
116     * Constructs a new, empty map with the specified max capacity and
117     * load factor.
118     *
119     * @param maxSize  the maximum size of the map
120     * @param loadFactor  the load factor
121     * @throws IllegalArgumentException if the maximum size is less than one
122     * @throws IllegalArgumentException if the load factor is less than zero
123     */
124    public LRUMap(final int maxSize, final float loadFactor) {
125        this(maxSize, loadFactor, false);
126    }
127
128    /**
129     * Constructs a new, empty map with the specified max / initial capacity and
130     * load factor.
131     *
132     * @param maxSize  the maximum size of the map
133     * @param initialSize  the initial size of the map
134     * @param loadFactor  the load factor
135     * @throws IllegalArgumentException if the maximum size is less than one
136     * @throws IllegalArgumentException if the initial size is negative or larger than the maximum size
137     * @throws IllegalArgumentException if the load factor is less than zero
138     * @since 4.1
139     */
140    public LRUMap(final int maxSize, final int initialSize, final float loadFactor) {
141        this(maxSize, initialSize, loadFactor, false);
142    }
143
144    /**
145     * Constructs a new, empty map with the specified max capacity and load factor.
146     *
147     * @param maxSize  the maximum size of the map
148     * @param loadFactor  the load factor
149     * @param scanUntilRemovable  scan until a removeable entry is found, default false
150     * @throws IllegalArgumentException if the maximum size is less than one
151     * @throws IllegalArgumentException if the load factor is less than zero
152     * @since 3.1
153     */
154    public LRUMap(final int maxSize, final float loadFactor, final boolean scanUntilRemovable) {
155        this(maxSize, maxSize, loadFactor, scanUntilRemovable);
156    }
157
158    /**
159     * Constructs a new, empty map with the specified max / initial capacity and load factor.
160     *
161     * @param maxSize  the maximum size of the map
162     * @param initialSize  the initial size of the map
163     * @param loadFactor  the load factor
164     * @param scanUntilRemovable  scan until a removeable entry is found, default false
165     * @throws IllegalArgumentException if the maximum size is less than one
166     * @throws IllegalArgumentException if the initial size is negative or larger than the maximum size
167     * @throws IllegalArgumentException if the load factor is less than zero
168     * @since 4.1
169     */
170    public LRUMap(final int maxSize,
171                  final int initialSize,
172                  final float loadFactor,
173                  final boolean scanUntilRemovable) {
174
175        super(initialSize, loadFactor);
176        if (maxSize < 1) {
177            throw new IllegalArgumentException("LRUMap max size must be greater than 0");
178        }
179        if (initialSize > maxSize) {
180            throw new IllegalArgumentException("LRUMap initial size must not be greather than max size");
181        }
182        this.maxSize = maxSize;
183        this.scanUntilRemovable = scanUntilRemovable;
184    }
185
186    /**
187     * Constructor copying elements from another map.
188     * <p>
189     * The maximum size is set from the map's size.
190     *
191     * @param map  the map to copy
192     * @throws NullPointerException if the map is null
193     * @throws IllegalArgumentException if the map is empty
194     */
195    public LRUMap(final Map<? extends K, ? extends V> map) {
196        this(map, false);
197    }
198
199    /**
200     * Constructor copying elements from another map.
201     * <p/>
202     * The maximum size is set from the map's size.
203     *
204     * @param map  the map to copy
205     * @param scanUntilRemovable  scan until a removeable entry is found, default false
206     * @throws NullPointerException if the map is null
207     * @throws IllegalArgumentException if the map is empty
208     * @since 3.1
209     */
210    public LRUMap(final Map<? extends K, ? extends V> map, final boolean scanUntilRemovable) {
211        this(map.size(), DEFAULT_LOAD_FACTOR, scanUntilRemovable);
212        putAll(map);
213    }
214
215    //-----------------------------------------------------------------------
216    /**
217     * Gets the value mapped to the key specified.
218     * <p>
219     * This operation changes the position of the key in the map to the
220     * most recently used position (last).
221     *
222     * @param key  the key
223     * @return the mapped value, null if no match
224     */
225    @Override
226    public V get(final Object key) {
227        return get(key, true);
228    }
229
230    /**
231     * Gets the value mapped to the key specified.
232     * <p>
233     * If {@code updateToMRU} is {@code true}, the position of the key in the map
234     * is changed to the most recently used position (last), otherwise the iteration
235     * order is not changed by this operation.
236     *
237     * @param key  the key
238     * @param updateToMRU  whether the key shall be updated to the
239     *   most recently used position
240     * @return the mapped value, null if no match
241     * @since 4.1
242     */
243    public V get(final Object key, final boolean updateToMRU) {
244        final LinkEntry<K, V> entry = getEntry(key);
245        if (entry == null) {
246            return null;
247        }
248        if (updateToMRU) {
249            moveToMRU(entry);
250        }
251        return entry.getValue();
252    }
253
254    //-----------------------------------------------------------------------
255    /**
256     * Moves an entry to the MRU position at the end of the list.
257     * <p>
258     * This implementation moves the updated entry to the end of the list.
259     *
260     * @param entry  the entry to update
261     */
262    protected void moveToMRU(final LinkEntry<K, V> entry) {
263        if (entry.after != header) {
264            modCount++;
265            // remove
266            if(entry.before == null) {
267                throw new IllegalStateException("Entry.before is null." +
268                    " Please check that your keys are immutable, and that you have used synchronization properly." +
269                    " If so, then please report this to dev@commons.apache.org as a bug.");
270            }
271            entry.before.after = entry.after;
272            entry.after.before = entry.before;
273            // add first
274            entry.after = header;
275            entry.before = header.before;
276            header.before.after = entry;
277            header.before = entry;
278        } else if (entry == header) {
279            throw new IllegalStateException("Can't move header to MRU" +
280                " (please report this to dev@commons.apache.org)");
281        }
282    }
283
284    /**
285     * Updates an existing key-value mapping.
286     * <p>
287     * This implementation moves the updated entry to the end of the list
288     * using {@link #moveToMRU(AbstractLinkedMap.LinkEntry)}.
289     *
290     * @param entry  the entry to update
291     * @param newValue  the new value to store
292     */
293    @Override
294    protected void updateEntry(final HashEntry<K, V> entry, final V newValue) {
295        moveToMRU((LinkEntry<K, V>) entry);  // handles modCount
296        entry.setValue(newValue);
297    }
298
299    /**
300     * Adds a new key-value mapping into this map.
301     * <p>
302     * This implementation checks the LRU size and determines whether to
303     * discard an entry or not using {@link #removeLRU(AbstractLinkedMap.LinkEntry)}.
304     * <p>
305     * From Commons Collections 3.1 this method uses {@link #isFull()} rather
306     * than accessing <code>size</code> and <code>maxSize</code> directly.
307     * It also handles the scanUntilRemovable functionality.
308     *
309     * @param hashIndex  the index into the data array to store at
310     * @param hashCode  the hash code of the key to add
311     * @param key  the key to add
312     * @param value  the value to add
313     */
314    @Override
315    protected void addMapping(final int hashIndex, final int hashCode, final K key, final V value) {
316        if (isFull()) {
317            LinkEntry<K, V> reuse = header.after;
318            boolean removeLRUEntry = false;
319            if (scanUntilRemovable) {
320                while (reuse != header && reuse != null) {
321                    if (removeLRU(reuse)) {
322                        removeLRUEntry = true;
323                        break;
324                    }
325                    reuse = reuse.after;
326                }
327                if (reuse == null) {
328                    throw new IllegalStateException(
329                        "Entry.after=null, header.after" + header.after + " header.before" + header.before +
330                        " key=" + key + " value=" + value + " size=" + size + " maxSize=" + maxSize +
331                        " Please check that your keys are immutable, and that you have used synchronization properly." +
332                        " If so, then please report this to dev@commons.apache.org as a bug.");
333                }
334            } else {
335                removeLRUEntry = removeLRU(reuse);
336            }
337
338            if (removeLRUEntry) {
339                if (reuse == null) {
340                    throw new IllegalStateException(
341                        "reuse=null, header.after=" + header.after + " header.before" + header.before +
342                        " key=" + key + " value=" + value + " size=" + size + " maxSize=" + maxSize +
343                        " Please check that your keys are immutable, and that you have used synchronization properly." +
344                        " If so, then please report this to dev@commons.apache.org as a bug.");
345                }
346                reuseMapping(reuse, hashIndex, hashCode, key, value);
347            } else {
348                super.addMapping(hashIndex, hashCode, key, value);
349            }
350        } else {
351            super.addMapping(hashIndex, hashCode, key, value);
352        }
353    }
354
355    /**
356     * Reuses an entry by removing it and moving it to a new place in the map.
357     * <p>
358     * This method uses {@link #removeEntry}, {@link #reuseEntry} and {@link #addEntry}.
359     *
360     * @param entry  the entry to reuse
361     * @param hashIndex  the index into the data array to store at
362     * @param hashCode  the hash code of the key to add
363     * @param key  the key to add
364     * @param value  the value to add
365     */
366    protected void reuseMapping(final LinkEntry<K, V> entry, final int hashIndex, final int hashCode,
367                                final K key, final V value) {
368        // find the entry before the entry specified in the hash table
369        // remember that the parameters (except the first) refer to the new entry,
370        // not the old one
371        try {
372            final int removeIndex = hashIndex(entry.hashCode, data.length);
373            final HashEntry<K, V>[] tmp = data;  // may protect against some sync issues
374            HashEntry<K, V> loop = tmp[removeIndex];
375            HashEntry<K, V> previous = null;
376            while (loop != entry && loop != null) {
377                previous = loop;
378                loop = loop.next;
379            }
380            if (loop == null) {
381                throw new IllegalStateException(
382                    "Entry.next=null, data[removeIndex]=" + data[removeIndex] + " previous=" + previous +
383                    " key=" + key + " value=" + value + " size=" + size + " maxSize=" + maxSize +
384                    " Please check that your keys are immutable, and that you have used synchronization properly." +
385                    " If so, then please report this to dev@commons.apache.org as a bug.");
386            }
387
388            // reuse the entry
389            modCount++;
390            removeEntry(entry, removeIndex, previous);
391            reuseEntry(entry, hashIndex, hashCode, key, value);
392            addEntry(entry, hashIndex);
393        } catch (final NullPointerException ex) {
394            throw new IllegalStateException(
395                    "NPE, entry=" + entry + " entryIsHeader=" + (entry==header) +
396                    " key=" + key + " value=" + value + " size=" + size + " maxSize=" + maxSize +
397                    " Please check that your keys are immutable, and that you have used synchronization properly." +
398                    " If so, then please report this to dev@commons.apache.org as a bug.");
399        }
400    }
401
402    /**
403     * Subclass method to control removal of the least recently used entry from the map.
404     * <p>
405     * This method exists for subclasses to override. A subclass may wish to
406     * provide cleanup of resources when an entry is removed. For example:
407     * <pre>
408     * protected boolean removeLRU(LinkEntry entry) {
409     *   releaseResources(entry.getValue());  // release resources held by entry
410     *   return true;  // actually delete entry
411     * }
412     * </pre>
413     * <p>
414     * Alternatively, a subclass may choose to not remove the entry or selectively
415     * keep certain LRU entries. For example:
416     * <pre>
417     * protected boolean removeLRU(LinkEntry entry) {
418     *   if (entry.getKey().toString().startsWith("System.")) {
419     *     return false;  // entry not removed from LRUMap
420     *   } else {
421     *     return true;  // actually delete entry
422     *   }
423     * }
424     * </pre>
425     * The effect of returning false is dependent on the scanUntilRemovable flag.
426     * If the flag is true, the next LRU entry will be passed to this method and so on
427     * until one returns false and is removed, or every entry in the map has been passed.
428     * If the scanUntilRemovable flag is false, the map will exceed the maximum size.
429     * <p>
430     * NOTE: Commons Collections 3.0 passed the wrong entry to this method.
431     * This is fixed in version 3.1 onwards.
432     *
433     * @param entry  the entry to be removed
434     * @return {@code true}
435     */
436    protected boolean removeLRU(final LinkEntry<K, V> entry) {
437        return true;
438    }
439
440    //-----------------------------------------------------------------------
441    /**
442     * Returns true if this map is full and no new mappings can be added.
443     *
444     * @return <code>true</code> if the map is full
445     */
446    public boolean isFull() {
447        return size >= maxSize;
448    }
449
450    /**
451     * Gets the maximum size of the map (the bound).
452     *
453     * @return the maximum number of elements the map can hold
454     */
455    public int maxSize() {
456        return maxSize;
457    }
458
459    /**
460     * Whether this LRUMap will scan until a removable entry is found when the
461     * map is full.
462     *
463     * @return true if this map scans
464     * @since 3.1
465     */
466    public boolean isScanUntilRemovable() {
467        return scanUntilRemovable;
468    }
469
470    //-----------------------------------------------------------------------
471    /**
472     * Clones the map without cloning the keys or values.
473     *
474     * @return a shallow clone
475     */
476    @Override
477    public LRUMap<K, V> clone() {
478        return (LRUMap<K, V>) super.clone();
479    }
480
481    /**
482     * Write the map out using a custom routine.
483     */
484    private void writeObject(final ObjectOutputStream out) throws IOException {
485        out.defaultWriteObject();
486        doWriteObject(out);
487    }
488
489    /**
490     * Read the map in using a custom routine.
491     */
492    private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
493        in.defaultReadObject();
494        doReadObject(in);
495    }
496
497    /**
498     * Writes the data necessary for <code>put()</code> to work in deserialization.
499     *
500     * @param out  the output stream
501     * @throws IOException if an error occurs while writing to the stream
502     */
503    @Override
504    protected void doWriteObject(final ObjectOutputStream out) throws IOException {
505        out.writeInt(maxSize);
506        super.doWriteObject(out);
507    }
508
509    /**
510     * Reads the data necessary for <code>put()</code> to work in the superclass.
511     *
512     * @param in  the input stream
513     * @throws IOException if an error occurs while reading from the stream
514     * @throws ClassNotFoundException if an object read from the stream can not be loaded
515     */
516    @Override
517    protected void doReadObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
518        maxSize = in.readInt();
519        super.doReadObject(in);
520    }
521
522}