带过期时间的Map-ExpiringMap

文章首发于：clawhub.club

---

有的时候，一些需求过于简单，不必要用很复杂的方式解决，比如不引入中间件。这个ExpiringMap就是其中的一个产物，当然，单机环境下它仍然有自己的用途。
ExpiringMap包含一个工作线程，这个线程定期扫描现有的键值对中，是否有过期的数据，如果有的话就删除，并且支持实现过期时监听事件。
源码相对来说比较简单，是mina中的一个工具类：

import java.util.Collection;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.CopyOnWriteArrayList;
import java.util.concurrent.locks.ReadWriteLock;
import java.util.concurrent.locks.ReentrantReadWriteLock;

/**
 * A map with expiration.  This class contains a worker thread that will
 * periodically check this class in order to determine if any objects
 * should be removed based on the provided time-to-live value.
 * 带过期时间的Map。这个类包含一个工作线程，它将定期检查这个类，以便根据提供的生存时间值确定是否应该删除任何对象。
 *
 * @param <K> The key type
 * @param <V> The value type
 * @author <a href="http://mina.apache.org">Apache MINA Project</a>
 */
public class ExpiringMap<K, V> implements Map<K, V> {
    /**
     * The default value, 60 seconds
     */
    public static final int DEFAULT_TIME_TO_LIVE = 60;

    /**
     * The default value, 1 second
     */
    public static final int DEFAULT_EXPIRATION_INTERVAL = 1;

    private static volatile int expirerCount = 1;

    private final ConcurrentHashMap<K, ExpiringObject> delegate;

    private final CopyOnWriteArrayList<ExpirationListener<V>> expirationListeners;

    private final Expirer expirer;

    /**
     * Creates a new instance of ExpiringMap using the default values
     * DEFAULT_TIME_TO_LIVE and DEFAULT_EXPIRATION_INTERVAL
     */
    public ExpiringMap() {
        this(DEFAULT_TIME_TO_LIVE, DEFAULT_EXPIRATION_INTERVAL);
    }

    /**
     * Creates a new instance of ExpiringMap using the supplied
     * time-to-live value and the default value for DEFAULT_EXPIRATION_INTERVAL
     *
     * @param timeToLive The time-to-live value (seconds)
     */
    public ExpiringMap(int timeToLive) {
        this(timeToLive, DEFAULT_EXPIRATION_INTERVAL);
    }

    /**
     * Creates a new instance of ExpiringMap using the supplied values and
     * a {@link ConcurrentHashMap} for the internal data structure.
     *
     * @param timeToLive         The time-to-live value (seconds)
     * @param expirationInterval The time between checks to see if a value should be removed (seconds)
     */
    public ExpiringMap(int timeToLive, int expirationInterval) {
        this(new ConcurrentHashMap<>(), new CopyOnWriteArrayList<>(), timeToLive,
                expirationInterval);
    }

    private ExpiringMap(ConcurrentHashMap<K, ExpiringObject> delegate,
                        CopyOnWriteArrayList<ExpirationListener<V>> expirationListeners, int timeToLive, int expirationInterval) {
        this.delegate = delegate;
        this.expirationListeners = expirationListeners;

        this.expirer = new Expirer();
        expirer.setTimeToLive(timeToLive);
        expirer.setExpirationInterval(expirationInterval);
        //开启监听线程
        expirer.startExpiring();
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public V put(K key, V value) {
        ExpiringObject answer = delegate.put(key, new ExpiringObject(key, value, System.currentTimeMillis()));

        if (answer == null) {
            return null;
        }

        return answer.getValue();
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public V get(Object key) {
        ExpiringObject object = delegate.get(key);

        if (object != null) {
            object.setLastAccessTime(System.currentTimeMillis());

            return object.getValue();
        }

        return null;
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public V remove(Object key) {
        ExpiringObject answer = delegate.remove(key);
        if (answer == null) {
            return null;
        }

        return answer.getValue();
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public boolean containsKey(Object key) {
        return delegate.containsKey(key);
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public boolean containsValue(Object value) {
        return delegate.containsValue(value);
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public int size() {
        return delegate.size();
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public boolean isEmpty() {
        return delegate.isEmpty();
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public void clear() {
        delegate.clear();
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public int hashCode() {
        return delegate.hashCode();
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public Set<K> keySet() {
        return delegate.keySet();
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public boolean equals(Object obj) {
        return delegate.equals(obj);
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public void putAll(Map<? extends K, ? extends V> inMap) {
        for (Entry<? extends K, ? extends V> e : inMap.entrySet()) {
            this.put(e.getKey(), e.getValue());
        }
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public Collection<V> values() {
        throw new UnsupportedOperationException();
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public Set<Map.Entry<K, V>> entrySet() {
        throw new UnsupportedOperationException();
    }

    /**
     * Adds a listener in the expiration listeners
     *
     * @param listener The listener to add
     */
    public void addExpirationListener(ExpirationListener<V> listener) {
        expirationListeners.add(listener);
    }

    /**
     * Removes a listener from the expiration listeners
     *
     * @param listener The listener to remove
     */
    public void removeExpirationListener(ExpirationListener<V> listener) {
        expirationListeners.remove(listener);
    }

    /**
     * @return The Expirer instance
     */
    public Expirer getExpirer() {
        return expirer;
    }

    /**
     * Get the interval in which an object will live in the map before it is removed.
     *
     * @return The expiration time in second
     */
    public int getExpirationInterval() {
        return expirer.getExpirationInterval();
    }

    /**
     * @return the Time-to-live value in seconds.
     */
    public int getTimeToLive() {
        return expirer.getTimeToLive();
    }

    /**
     * Set the interval in which an object will live in the map before it is removed.
     *
     * @param expirationInterval The expiration time in seconds
     */
    public void setExpirationInterval(int expirationInterval) {
        expirer.setExpirationInterval(expirationInterval);
    }

    /**
     * Update the value for the time-to-live
     *
     * @param timeToLive The time-to-live (seconds)
     */
    public void setTimeToLive(int timeToLive) {
        expirer.setTimeToLive(timeToLive);
    }

    private class ExpiringObject {
        private K key;

        private V value;

        private long lastAccessTime;

        private final ReadWriteLock lastAccessTimeLock = new ReentrantReadWriteLock();

        ExpiringObject(K key, V value, long lastAccessTime) {
            if (value == null) {
                throw new IllegalArgumentException("An expiring object cannot be null.");
            }

            this.key = key;
            this.value = value;
            this.lastAccessTime = lastAccessTime;
        }

        public long getLastAccessTime() {
            lastAccessTimeLock.readLock().lock();

            try {
                return lastAccessTime;
            } finally {
                lastAccessTimeLock.readLock().unlock();
            }
        }

        public void setLastAccessTime(long lastAccessTime) {
            lastAccessTimeLock.writeLock().lock();

            try {
                this.lastAccessTime = lastAccessTime;
            } finally {
                lastAccessTimeLock.writeLock().unlock();
            }
        }

        public K getKey() {
            return key;
        }

        public V getValue() {
            return value;
        }

        @Override
        public boolean equals(Object obj) {
            return value.equals(obj);
        }

        @Override
        public int hashCode() {
            return value.hashCode();
        }
    }

    /**
     * A Thread that monitors an {@link ExpiringMap} and will remove
     * elements that have passed the threshold.
     * 一个线程，它监视{@link ExpiringMap}，并将删除超过阈值的元素。
     */
    public class Expirer implements Runnable {
        private final ReadWriteLock stateLock = new ReentrantReadWriteLock();

        private long timeToLiveMillis;

        private long expirationIntervalMillis;

        private boolean running = false;

        private final Thread expirerThread;

        /**
         * Creates a new instance of Expirer.
         */
        public Expirer() {
            expirerThread = new Thread(this, "ExpiringMapExpirer-" + expirerCount++);
            //守护线程
            expirerThread.setDaemon(true);
        }

        /**
         * {@inheritDoc}
         */
        @Override
        public void run() {
            while (running) {
                processExpires();

                try {
                    Thread.sleep(expirationIntervalMillis);
                } catch (InterruptedException e) {
                    // Do nothing
                }
            }
        }

        private void processExpires() {
            long timeNow = System.currentTimeMillis();

            for (ExpiringObject o : delegate.values()) {

                if (timeToLiveMillis <= 0) {
                    continue;
                }

                long timeIdle = timeNow - o.getLastAccessTime();

                if (timeIdle >= timeToLiveMillis) {
                    delegate.remove(o.getKey());

                    for (ExpirationListener<V> listener : expirationListeners) {
                        listener.expired(o.getValue());
                    }
                }
            }
        }

        /**
         * Kick off this thread which will look for old objects and remove them.
         * 启动这个线程，它将查找旧对象并删除它们。
         */
        public void startExpiring() {
            stateLock.writeLock().lock();

            try {
                if (!running) {
                    running = true;
                    expirerThread.start();
                }
            } finally {
                stateLock.writeLock().unlock();
            }
        }

        /**
         * If this thread has not started, then start it.
         * Otherwise just return;
         * 如果这个线程还没有启动，那么启动它。否则就返回;
         */
        public void startExpiringIfNotStarted() {
            stateLock.readLock().lock();

            try {
                if (running) {
                    return;
                }
            } finally {
                stateLock.readLock().unlock();
            }

            stateLock.writeLock().lock();

            try {
                if (!running) {
                    running = true;
                    expirerThread.start();
                }
            } finally {
                stateLock.writeLock().unlock();
            }
        }

        /**
         * Stop the thread from monitoring the map.
         * 停止线程监视Map。
         */
        public void stopExpiring() {
            stateLock.writeLock().lock();

            try {
                if (running) {
                    running = false;
                    expirerThread.interrupt();
                }
            } finally {
                stateLock.writeLock().unlock();
            }
        }

        /**
         * Checks to see if the thread is running
         *
         * @return If the thread is running, true.  Otherwise false.
         */
        public boolean isRunning() {
            stateLock.readLock().lock();

            try {
                return running;
            } finally {
                stateLock.readLock().unlock();
            }
        }

        /**
         * @return the Time-to-live value in seconds.
         */
        public int getTimeToLive() {
            stateLock.readLock().lock();

            try {
                return (int) timeToLiveMillis / 1000;
            } finally {
                stateLock.readLock().unlock();
            }
        }

        /**
         * Update the value for the time-to-live
         *
         * @param timeToLive The time-to-live (seconds)
         */
        public void setTimeToLive(long timeToLive) {
            stateLock.writeLock().lock();

            try {
                this.timeToLiveMillis = timeToLive * 1000;
            } finally {
                stateLock.writeLock().unlock();
            }
        }

        /**
         * Get the interval in which an object will live in the map before
         * it is removed.
         *
         * @return The time in seconds.
         */
        public int getExpirationInterval() {
            stateLock.readLock().lock();

            try {
                return (int) expirationIntervalMillis / 1000;
            } finally {
                stateLock.readLock().unlock();
            }
        }

        /**
         * Set the interval in which an object will live in the map before
         * it is removed.
         *
         * @param expirationInterval The time in seconds
         */
        public void setExpirationInterval(long expirationInterval) {
            stateLock.writeLock().lock();

            try {
                this.expirationIntervalMillis = expirationInterval * 1000;
            } finally {
                stateLock.writeLock().unlock();
            }
        }
    }

    /**
     * A listener for expired object events.
     * 过期对象事件的侦听器。
     *
     * @param <E> The event type
     * @author <a href="http://mina.apache.org">Apache MINA Project</a>
     */
    public interface ExpirationListener<E> {
        /**
         * Adds a given event to the listener
         * 向侦听器添加给定的事件
         *
         * @param expiredObject The expired event
         */
        void expired(E expiredObject);
    }

}

我将ExpirationListener监听接口也一并放到了ExpiringMap中。

• 存储键值对的是：ConcurrentHashMap<K, ExpiringObject> delegate，其中ExpiringObject对象存放了键值与最后访问时间（新增和查看时会更新这个时间）。
• 存储配置的监听器的是：CopyOnWriteArrayList<ExpirationListener> expirationListeners，键值对过期是，迭代所有配置的监听器，回调。
• 监控器由Expirer实现，初始化时，新建一个守护线程，定期扫描所有的键值对，过期即删除，监听回调也是在这里调用。
• 监控器的数量由 private static volatile int expirerCount；表示。多个Map实例化时，可获取监控器的数量。

这个类中用了ConcurrentHashMap，CopyOnWriteArrayList，ReentrantReadWriteLock等工具类，所以并发访问时线程安全。