MapMaker.java

/*
 * Copyright (C) 2009 The Guava Authors
 *
 * 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://www.apache.org/licenses/LICENSE-2.0
 *
 * 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.glassfish.jersey.internal.guava;

import java.lang.ref.SoftReference;
import java.lang.ref.WeakReference;
import java.util.ConcurrentModificationException;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentMap;

/**
 * <p>A builder of {@link ConcurrentMap} instances having any combination of the following features:
 * <p>
 * <ul>
 * <li>keys or values automatically wrapped in {@linkplain WeakReference weak} or {@linkplain
 * SoftReference soft} references
 * <li>notification of evicted (or otherwise removed) entries
 * <li>on-demand computation of values for keys not already present
 * </ul>
 * <p>
 * <p>Usage example: <pre>   {@code
 * <p>
 *   ConcurrentMap<Request, Stopwatch> timers = new MapMaker()
 *       .concurrencyLevel(4)
 *       .weakKeys()
 *       .makeMap();}</pre>
 * <p>
 * <p>These features are all optional; {@code new MapMaker().makeMap()} returns a valid concurrent
 * map that behaves similarly to a {@link ConcurrentHashMap}.
 * <p>
 * <p>The returned map is implemented as a hash table with similar performance characteristics to
 * {@link ConcurrentHashMap}. It supports all optional operations of the {@code ConcurrentMap}
 * interface. It does not permit null keys or values.
 * <p>
 * <p><b>Note:</b> by default, the returned map uses equality comparisons (the {@link Object#equals
 * equals} method) to determine equality for keys or values. However, if {@link #weakKeys} was
 * specified, the map uses identity ({@code ==}) comparisons instead for keys. Likewise, if {@link
 * #weakValues} or {@link #softValues} was specified, the map uses identity comparisons for values.
 * <p>
 * <p>The view collections of the returned map have <i>weakly consistent iterators</i>. This means
 * that they are safe for concurrent use, but if other threads modify the map after the iterator is
 * created, it is undefined which of these changes, if any, are reflected in that iterator. These
 * iterators never throw {@link ConcurrentModificationException}.
 * <p>
 * <p>If {@link #weakKeys}, {@link #weakValues}, or {@link #softValues} are requested, it is
 * possible for a key or value present in the map to be reclaimed by the garbage collector. Entries
 * with reclaimed keys or values may be removed from the map on each map modification or on
 * occasional map accesses; such entries may be counted by {@link Map#size}, but will never be
 * visible to read or write operations. A partially-reclaimed entry is never exposed to the user.
 * Any {@link Map.Entry} instance retrieved from the map's
 * {@linkplain Map#entrySet entry set} is a snapshot of that entry's state at the time of
 * retrieval; such entries do, however, support {@link Map.Entry#setValue}, which simply
 * calls {@link Map#put} on the entry's key.
 * <p>
 * <p>The maps produced by {@code MapMaker} are serializable, and the deserialized maps retain all
 * the configuration properties of the original map. During deserialization, if the original map had
 * used soft or weak references, the entries are reconstructed as they were, but it's not unlikely
 * they'll be quickly garbage-collected before they are ever accessed.
 * <p>
 * <p>{@code new MapMaker().weakKeys().makeMap()} is a recommended replacement for {@link
 * java.util.WeakHashMap}, but note that it compares keys using object identity whereas {@code
 * WeakHashMap} uses {@link Object#equals}.
 *
 * @author Bob Lee
 * @author Charles Fry
 * @author Kevin Bourrillion
 * @since 2.0 (imported from Google Collections Library)
 */
public final class MapMaker extends GenericMapMaker<Object, Object> {
    static final int UNSET_INT = -1;
    private static final int DEFAULT_INITIAL_CAPACITY = 16;
    private static final int DEFAULT_CONCURRENCY_LEVEL = 4;
    private static final int DEFAULT_EXPIRATION_NANOS = 0;

    private final int initialCapacity = UNSET_INT;
    private final int concurrencyLevel = UNSET_INT;
    final int maximumSize = UNSET_INT;

    private final long expireAfterWriteNanos = UNSET_INT;
    private final long expireAfterAccessNanos = UNSET_INT;

    Equivalence<Object> getKeyEquivalence() {
        return getKeyStrength().defaultEquivalence();
    }

    int getInitialCapacity() {
        return (initialCapacity == UNSET_INT) ? DEFAULT_INITIAL_CAPACITY : initialCapacity;
    }

    int getConcurrencyLevel() {
        return (concurrencyLevel == UNSET_INT) ? DEFAULT_CONCURRENCY_LEVEL : concurrencyLevel;
    }

    MapMakerInternalMap.Strength getKeyStrength() {
        return MapMakerInternalMap.Strength.STRONG;
    }

    MapMakerInternalMap.Strength getValueStrength() {
        return MapMakerInternalMap.Strength.STRONG;
    }

    long getExpireAfterWriteNanos() {
        return (expireAfterWriteNanos == UNSET_INT) ? DEFAULT_EXPIRATION_NANOS : expireAfterWriteNanos;
    }

    long getExpireAfterAccessNanos() {
        return (expireAfterAccessNanos == UNSET_INT)
                ? DEFAULT_EXPIRATION_NANOS : expireAfterAccessNanos;
    }

    Ticker getTicker() {
        return Ticker.systemTicker();
    }

    /**
     * Returns a string representation for this MapMaker instance. The exact form of the returned
     * string is not specificed.
     */
    @Override
    public String toString() {
        MoreObjects.ToStringHelper s = MoreObjects.toStringHelper(this);
        if (initialCapacity != UNSET_INT) {
            s.add("initialCapacity", initialCapacity);
        }
        if (concurrencyLevel != UNSET_INT) {
            s.add("concurrencyLevel", concurrencyLevel);
        }
        if (maximumSize != UNSET_INT) {
            s.add("maximumSize", maximumSize);
        }
        if (expireAfterWriteNanos != UNSET_INT) {
            s.add("expireAfterWrite", expireAfterWriteNanos + "ns");
        }
        if (expireAfterAccessNanos != UNSET_INT) {
            s.add("expireAfterAccess", expireAfterAccessNanos + "ns");
        }
        return s.toString();
    }

    /**
     * The reason why an entry was removed.
     */
    enum RemovalCause {
        /**
         * The entry was manually removed by the user. This can result from the user invoking
         * {@link Map#remove}, {@link ConcurrentMap#remove}, or {@link java.util.Iterator#remove}.
         */
        EXPLICIT {
        },

        /**
         * The entry itself was not actually removed, but its value was replaced by the user. This can
         * result from the user invoking {@link Map#put}, {@link Map#putAll},
         * {@link ConcurrentMap#replace(Object, Object)}, or
         * {@link ConcurrentMap#replace(Object, Object, Object)}.
         */
        REPLACED {
        },

        /**
         * The entry was removed automatically because its key or value was garbage-collected. This can
         * occur when using {@link #softValues}, {@link #weakKeys}, or {@link #weakValues}.
         */
        COLLECTED {
        },

        /**
         * The entry's expiration timestamp has passed. This can occur when using {@link
         * #expireAfterWrite} or {@link #expireAfterAccess}.
         */
        EXPIRED {
        },

        /**
         * The entry was evicted due to size constraints. This can occur when using {@link
         * #maximumSize}.
         */
        SIZE {
        }

    }

    /**
     * An object that can receive a notification when an entry is removed from a map. The removal
     * resulting in notification could have occured to an entry being manually removed or replaced, or
     * due to eviction resulting from timed expiration, exceeding a maximum size, or garbage
     * collection.
     * <p>
     * <p>An instance may be called concurrently by multiple threads to process different entries.
     * Implementations of this interface should avoid performing blocking calls or synchronizing on
     * shared resources.
     *
     * @param <K> the most general type of keys this listener can listen for; for
     *            example {@code Object} if any key is acceptable
     * @param <V> the most general type of values this listener can listen for; for
     *            example {@code Object} if any key is acceptable
     */
    interface RemovalListener<K, V> {
        /**
         * Notifies the listener that a removal occurred at some point in the past.
         */
        void onRemoval(RemovalNotification<K, V> notification);
    }

    /**
     * A notification of the removal of a single entry. The key or value may be null if it was already
     * garbage collected.
     * <p>
     * <p>Like other {@code Map.Entry} instances associated with MapMaker, this class holds strong
     * references to the key and value, regardless of the type of references the map may be using.
     */
    static final class RemovalNotification<K, V> extends ImmutableEntry<K, V> {
        private static final long serialVersionUID = 0;

        RemovalNotification(K key, V value, RemovalCause cause) {
            super(key, value);
        }

    }

}