1 /*
2 * *************************************************************************************************************************************************************
3 *
4 * TheseFoolishThings: Miscellaneous utilities
5 * http://tidalwave.it/projects/thesefoolishthings
6 *
7 * Copyright (C) 2009 - 2025 by Tidalwave s.a.s. (http://tidalwave.it)
8 *
9 * *************************************************************************************************************************************************************
10 *
11 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
12 * You may obtain a copy of the License at
13 *
14 * http://www.apache.org/licenses/LICENSE-2.0
15 *
16 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
17 * CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
18 *
19 * *************************************************************************************************************************************************************
20 *
21 * git clone https://bitbucket.org/tidalwave/thesefoolishthings-src
22 * git clone https://github.com/tidalwave-it/thesefoolishthings-src
23 *
24 * *************************************************************************************************************************************************************
25 */
26 package it.tidalwave.util;
27
28 import javax.annotation.Nonnegative;
29 import javax.annotation.Nonnull;
30 import java.util.Collection;
31 import java.util.Collections;
32 import java.util.Map;
33 import java.util.Set;
34 import java.util.function.BiConsumer;
35 import it.tidalwave.util.impl.TypeSafeHashMultiMap;
36
37 /***************************************************************************************************************************************************************
38 *
39 * A map that is type safe, i.e. the pairs (key, value) are type-checked, and can contain multiple values, i.e. it's
40 * associated to collections (key, collection of values). It's immutable.
41 *
42 * @author Fabrizio Giudici
43 *
44 **************************************************************************************************************************************************************/
45 public interface TypeSafeMultiMap extends Iterable<Map.Entry<Key<?>, Collection<?>>>
46 {
47 /***********************************************************************************************************************************************************
48 * Returns a value given its key.
49 *
50 * @param <T> the type
51 * @param key the key
52 * @return the value as a {@link Collection}
53 **********************************************************************************************************************************************************/
54 @Nonnull
55 public <T> Collection<T> get (@Nonnull Key<T> key);
56
57 /***********************************************************************************************************************************************************
58 * Checks whether a pair has been stored.
59 *
60 * @param key the key
61 * @return {@code true} if the pair is present
62 **********************************************************************************************************************************************************/
63 public boolean containsKey (@Nonnull Key<?> key);
64
65 /***********************************************************************************************************************************************************
66 * Returns a set of all the contained keys.
67 *
68 * @return the keys as a mutable set
69 **********************************************************************************************************************************************************/
70 @Nonnull
71 public Set<Key<?>> keySet();
72
73 /***********************************************************************************************************************************************************
74 * Returns a set of all the contained values.
75 *
76 * @return the values as a mutable collection
77 * @since 3.2-ALPHA-6
78 **********************************************************************************************************************************************************/
79 @Nonnull
80 public Collection<Collection<?>> values();
81
82 /***********************************************************************************************************************************************************
83 * Returns a set of all the contained (key, value) pairs.
84 *
85 * @return the pairs as a mutable collection
86 * @since 3.2-ALPHA-6
87 **********************************************************************************************************************************************************/
88 @Nonnull
89 public Set<Map.Entry<Key<?>, Collection<?>>> entrySet();
90
91 /***********************************************************************************************************************************************************
92 * Returns the size of this map.
93 *
94 * @return the size
95 **********************************************************************************************************************************************************/
96 @Nonnegative
97 public int size();
98
99 /***********************************************************************************************************************************************************
100 * Performs the given action on all the pairs (key, value) contained in this map.
101 *
102 * @param action the action
103 * @param <T> the value type
104 * @since 3.2-ALPHA-10
105 **********************************************************************************************************************************************************/
106 public <T> void forEach (@Nonnull BiConsumer<? super Key<T>, ? super Collection<T>> action);
107
108 /***********************************************************************************************************************************************************
109 * Returns the contents as a plain {@link Map}.
110 *
111 * @return the contents as a mutable map
112 **********************************************************************************************************************************************************/
113 @Nonnull
114 public Map<Key<?>, Collection<?>> asMap();
115
116 /***********************************************************************************************************************************************************
117 * Creates a new instance with an additional pair (key, value).
118 *
119 * @param <T> the type
120 * @param key the key
121 * @param value the value
122 * @return the new instance
123 * @since 3.2-ALPHA-2
124 **********************************************************************************************************************************************************/
125 @Nonnull
126 public <T> TypeSafeMultiMap with (@Nonnull final Key<T> key, @Nonnull final T value);
127
128 /***********************************************************************************************************************************************************
129 * Creates an instance cloning the given map.
130 *
131 * @param map the map to clone
132 * @return the new instance
133 * @since 3.2-ALPHA-2
134 **********************************************************************************************************************************************************/
135 @Nonnull
136 public static TypeSafeMultiMap ofCloned (@Nonnull final Map<? extends Key<?>, ? extends Collection<?>> map)
137 {
138 return new TypeSafeHashMultiMap(map);
139 }
140
141 /***********************************************************************************************************************************************************
142 * Creates a new empty instance.
143 *
144 * @return the new instance
145 * @since 3.2-ALPHA-2
146 **********************************************************************************************************************************************************/
147 @Nonnull
148 public static TypeSafeMultiMap newInstance()
149 {
150 return new TypeSafeHashMultiMap(Collections.emptyMap());
151 }
152 }