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     */
036        Future<V> asyncTake(K key);
037
038        /**
039         * Waits for the specified amount of time for an entry with the given key
040         * and returns the associated value. Returns null if no value was provided
041         * within the poll time. May return null if the producer withdraws the entry
042         * without providing a value.
043         * 
044         * @param key key for the entry
045         * @param timeout timeout before the methods returns
046         * @param unit time unit used in conjunction with timout
047         * @return the value of the entry
048         * @throws InterruptedException
049         */
050        V poll(K key, long timeout, TimeUnit unit) throws InterruptedException;
051
052        /**
053         * Polls for an entry in a background thread.
054         * 
055         * @param key key for the entry
056         * @return Future the result
057     */
058        Future<V> asyncPoll(K key, long timeout, TimeUnit unit);
059}
060