001    /*
002     * The contents of this file are subject to the terms
003     * of the Common Development and Distribution License
004     * (the "License").  You may not use this file except
005     * in compliance with the License.
006     * 
007     * You can obtain a copy of the license at
008     * http://www.opensource.org/licenses/cddl1.php
009     * See the License for the specific language governing
010     * permissions and limitations under the License.
011     */
012    
013    /*
014     * MultivaluedMap.java
015     *
016     * Created on February 13, 2007, 2:30 PM
017     *
018     */
019    
020    package javax.ws.rs.core;
021    
022    import java.util.List;
023    import java.util.Map;
024    
025    /**
026     * A map of key-values pairs. Each key can have zero or more values.
027     * 
028     */
029    public interface MultivaluedMap<K, V> extends Map<K, List<V>> {
030        
031        /**
032         * Set the key's value to be a one item list consisting of the supplied value.
033         * Any existing values will be replaced.
034         * 
035         * @param key the key
036         * @param value the single value of the key
037         */
038        void putSingle(K key, V value);
039        
040        /**
041         * Add a value to the current list of values for the supplied key.
042         * @param key the key 
043         * @param value the value to be added.
044         */
045        void add(K key, V value);
046        
047        /**
048         * A shortcut to get the first value of the supplied key.
049         * @param key the key
050         * @return the first value for the specified key or null if the key is
051         * not in the map.
052         */
053        V getFirst(K key);
054        
055    }
056