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}