001package ca.uhn.hl7v2.concurrent;
002
003import java.util.Map;
004import java.util.concurrent.Future;
005import java.util.concurrent.TimeUnit;
006
007public interface BlockingMap<K, V> extends Map<K, V> {
008
009        /**
010         * Adds an entry only if there's already a consumer waiting for the value.
011         * 
012         * @param key key for the entry to be added
013         * @param value entry to be added
014         * @return true if entry was added and a consumer is already waiting for the
015         *         value, false otherwise
016         */
017        boolean give(K key, V value);
018
019        /**
020         * Waits for an entry for the given key and returns the associated value.
021         * May return null if the producer withdraws the entry without providing a
022         * value.
023         * 
024         * @param key key for the entry
025         * @return the value of the entry
026         * @throws InterruptedException
027         */
028        V take(K key) throws InterruptedException;
029        
030        /**
031         * Waits for an entry in a background thread.
032         * 
033         * @param key key for the entry
034         * @return Future the result
035         * @throws InterruptedException
036         */
037        Future<V> asyncTake(K key) throws InterruptedException;
038
039        /**
040         * Waits for the specified amount of time for an entry with the given key
041         * and returns the associated value. Returns null if no value was provided
042         * within the poll time. May return null if the producer withdraws the entry
043         * without providing a value.
044         * 
045         * @param key key for the entry
046         * @param timeout timeout before the methods returns
047         * @param unit time unit used in conjunction with timout
048         * @return the value of the entry
049         * @throws InterruptedException
050         */
051        V poll(K key, long timeout, TimeUnit unit) throws InterruptedException;
052
053        /**
054         * Polls for an entry in a background thread.
055         * 
056         * @param key key for the entry
057         * @return Future the result
058         * @throws InterruptedException
059         */
060        Future<V> asyncPoll(K key, long timeout, TimeUnit unit) throws InterruptedException;
061}
062