001/*
002 * Copyright 2002-2019 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.util;
018
019import java.util.List;
020import java.util.Map;
021
022import org.springframework.lang.Nullable;
023
024/**
025 * Extension of the {@code Map} interface that stores multiple values.
026 *
027 * @author Arjen Poutsma
028 * @since 3.0
029 * @param <K> the key type
030 * @param <V> the value element type
031 */
032public interface MultiValueMap<K, V> extends Map<K, List<V>> {
033
034        /**
035         * Return the first value for the given key.
036         * @param key the key
037         * @return the first value for the specified key, or {@code null} if none
038         */
039        @Nullable
040        V getFirst(K key);
041
042        /**
043         * Add the given single value to the current list of values for the given key.
044         * @param key the key
045         * @param value the value to be added
046         */
047        void add(K key, @Nullable V value);
048
049        /**
050         * Add all the values of the given list to the current list of values for the given key.
051         * @param key they key
052         * @param values the values to be added
053         * @since 5.0
054         */
055        void addAll(K key, List<? extends V> values);
056
057        /**
058         * Add all the values of the given {@code MultiValueMap} to the current values.
059         * @param values the values to be added
060         * @since 5.0
061         */
062        void addAll(MultiValueMap<K, V> values);
063
064        /**
065         * {@link #add(Object, Object) Add} the given value, only when the map does not
066         * {@link #containsKey(Object) contain} the given key.
067         * @param key the key
068         * @param value the value to be added
069         * @since 5.2
070         */
071        default void addIfAbsent(K key, @Nullable V value) {
072                if (!containsKey(key)) {
073                        add(key, value);
074                }
075        }
076
077        /**
078         * Set the given single value under the given key.
079         * @param key the key
080         * @param value the value to set
081         */
082        void set(K key, @Nullable V value);
083
084        /**
085         * Set the given values under.
086         * @param values the values.
087         */
088        void setAll(Map<K, V> values);
089
090        /**
091         * Return a {@code Map} with the first values contained in this {@code MultiValueMap}.
092         * @return a single value representation of this map
093         */
094        Map<K, V> toSingleValueMap();
095
096}