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 javax.annotation.concurrent.Immutable;
31 import java.util.Collection;
32 import java.util.Collections;
33 import java.util.Map;
34 import java.util.Optional;
35 import java.util.Set;
36 import java.util.function.BiConsumer;
37 import it.tidalwave.util.impl.TypeSafeHashMap;
38
39 /***************************************************************************************************************************************************************
40 *
41 * A map that is type safe, i.e. the pairs (key, value) are type-checked. It's immutable.
42 *
43 * @author Fabrizio Giudici
44 *
45 **************************************************************************************************************************************************************/
46 @Immutable
47 public interface TypeSafeMap extends Iterable<Map.Entry<Key<?>, Object>>
48 {
49 /***********************************************************************************************************************************************************
50 * Returns a value given its key.
51 *
52 * @param <T> the type
53 * @param key the key
54 * @return the value
55 * @throws NotFoundException if the key is not found
56 * @deprecated Use {@link #getOptional(Key)} instead
57 **********************************************************************************************************************************************************/
58 @Nonnull @Deprecated
59 public <T> T get (@Nonnull Key<T> key)
60 throws NotFoundException;
61
62 /***********************************************************************************************************************************************************
63 * Returns an optional value given its key.
64 *
65 * @param <T> the type
66 * @param key the key
67 * @return the value
68 *
69 * @since 3.2-ALPHA-1
70 **********************************************************************************************************************************************************/
71 @Nonnull
72 public default <T> Optional<T> getOptional (@Nonnull final Key<? extends T> key)
73 {
74 try
75 {
76 return Optional.of(get(key));
77 }
78 catch (NotFoundException e)
79 {
80 return Optional.empty();
81 }
82 }
83
84 /***********************************************************************************************************************************************************
85 * Checks whether a pair has been stored.
86 *
87 * @param key the key
88 * @return {@code true} if the pair is present
89 **********************************************************************************************************************************************************/
90 public boolean containsKey (@Nonnull Key<?> key);
91
92 /***********************************************************************************************************************************************************
93 * Returns a set of all the contained keys.
94 *
95 * @return the keys as a mutable set
96 **********************************************************************************************************************************************************/
97 @Nonnull
98 public Set<Key<?>> keySet();
99
100 /***********************************************************************************************************************************************************
101 * Returns a set of all the contained values.
102 *
103 * @return the values as a mutable collection
104 * @since 3.2-ALPHA-6
105 **********************************************************************************************************************************************************/
106 @Nonnull
107 public Collection<Object> values();
108
109 /***********************************************************************************************************************************************************
110 * Returns a set of all the contained (key, value) pairs.
111 *
112 * @return the pairs as a mutable collection
113 * @since 3.2-ALPHA-6
114 **********************************************************************************************************************************************************/
115 @Nonnull
116 public Set<Map.Entry<Key<?>, Object>> entrySet();
117
118 /***********************************************************************************************************************************************************
119 * Returns the size of this map.
120 *
121 * @return the size
122 **********************************************************************************************************************************************************/
123 @Nonnegative
124 public int size();
125
126 /***********************************************************************************************************************************************************
127 * Returns the contents as a plain {@link Map}.
128 *
129 * @return the contents as a mutable map
130 **********************************************************************************************************************************************************/
131 @Nonnull
132 public Map<Key<?>, Object> asMap();
133
134 /***********************************************************************************************************************************************************
135 * Performs the given action on all the pairs (key, value) contained in this map.
136 *
137 * @param action the action
138 * @param <T> the value type
139 * @since 3.2-ALPHA-10
140 **********************************************************************************************************************************************************/
141 public <T> void forEach (@Nonnull BiConsumer<? super Key<T>, ? super T> action);
142
143 /***********************************************************************************************************************************************************
144 * Create a new instance with an additional pair (key, value=
145 *
146 * @param <T> the type
147 * @param key the key
148 * @param value the value
149 * @return the new instance
150 * @since 3.2-ALPHA-2
151 **********************************************************************************************************************************************************/
152 @Nonnull
153 public <T> TypeSafeMap with (@Nonnull final Key<T> key, @Nonnull final T value);
154
155 /***********************************************************************************************************************************************************
156 * Creates a new empty instance.
157 *
158 * @return the new instance
159 * @since 3.2-ALPHA-2
160 **********************************************************************************************************************************************************/
161 @Nonnull
162 public static TypeSafeMap newInstance()
163 {
164 return new TypeSafeHashMap(Collections.emptyMap());
165 }
166
167 /***********************************************************************************************************************************************************
168 * Creates an instance cloning the given map.
169 *
170 * @param map the map to clone
171 * @return the new instance
172 * @since 3.2-ALPHA-2
173 **********************************************************************************************************************************************************/
174 @Nonnull
175 public static TypeSafeMap ofCloned (@Nonnull final Map<? extends Key<?>, Object> map)
176 {
177 return new TypeSafeHashMap(map);
178 }
179 }