Module ch.bind.philib
Package ch.bind.philib.util

Interface TimeoutMap<K,​V>

  • Type Parameters:
    K - type parameter for the map's keys.
    V - type parameter for the map's values.
    All Known Implementing Classes:
    SimpleTimeoutMap
    public interface TimeoutMap<K,​V>
    A map which additionaly to normal map operations allows the user to supply a timeout. The oldest timed-out entry in the map can be found through the non-blocking pollTimeoutNow() method or two blocking methods: pollTimeoutBlocking() and pollTimeoutBlocking(long, TimeUnit).
    Author:
    Philipp Meinen

    • Method Detail

      • put

        V put​(long timeout,
      K key,
      V value)
        Add a key-value pair with an associated timeout to the map. The resulting timeout-timestamp is the current time plus the supplied timeout.
        Parameters:
        timeout - the timeout for this key-value pair (in milliseconds)
        key - -
        value - -
        Returns:
        the value which was previously associated with the given key or null if none.

      • get

        V get​(K key)
        Searches a value by its key
        Parameters:
        key -
        Returns:
        null if the key does not exist.

      • remove

        V remove​(K key)
        removes an entry by it's key
        Parameters:
        key - the key for which an entry must be removed.
        Returns:
        null if there was no entry for this key in that map, otherwise the value of the removed entry.

      • pollTimeoutNow

        Map.Entry<K,​V> pollTimeoutNow()
        Nonblocking poll for the next entry which is timed out, based on the time of the invocation of this method.
        Returns:
        null if there is no timed-out entry in this map. otherwise the oldest timed-out entry.

      • pollAllTimeoutNow

        List<Map.Entry<K,​V>> pollAllTimeoutNow()
        Nonblocking poll for all timed out entries, based on the time of the invocation of this method.
        Returns:
        Collections.EMPTY_LIST if there is are no timed out entries in this map.

      • pollTimeoutBlocking

        Map.Entry<K,​V> pollTimeoutBlocking()
                                  throws InterruptedException
        Blocking poll for the next entry which is timed out.
        Returns:
        null if there is no timed-out entry in this map within the given duration. otherwise the oldest timed-out entry.
        Throws:
        InterruptedException

      • pollTimeoutBlocking

        Map.Entry<K,​V> pollTimeoutBlocking​(long duration,
                                         TimeUnit timeUnit)
                                  throws InterruptedException
        Blocking poll for the next entry which is timed out. The parameters duration and timeUnit define for how long the method must wait for a timeout to occur.
        Returns:
        null if there is no timed-out entry in this map within the given duration. otherwise the oldest timed-out entry.
        Throws:
        InterruptedException

      • clear

        void clear()
        removes all key-value pairs from this map.

      • size

        int size()
        query the number of entries in this map.
        Returns:
        the number of entries in this map.

      • isEmpty

        boolean isEmpty()
        Returns:
        true if this map is empty, false otherwise.

      • containsKey

        boolean containsKey​(K key)
        Check for the existence of a key.
        Parameters:
        key - -
        Returns:
        true if there is an entry identified by that key in this map, false otherwise.

      • getTimeToNextTimeout

        long getTimeToNextTimeout()
        Returns:
        Long.MAX_VALUE if the TimeoutMap is empty. Otherwise the time until the next entry times out (in milliseconds since the epoch). A return value of zero indicates that there is at least one entry which has already timed out.