1 /*
2 * Copyright (C) 2007 The Guava Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package com.google.common.collect;
18
19 import com.google.common.annotations.Beta;
20 import com.google.common.annotations.GwtCompatible;
21 import com.google.common.base.Objects;
22 import com.google.errorprone.annotations.CanIgnoreReturnValue;
23 import java.util.Collection;
24 import java.util.Iterator;
25 import java.util.Map;
26 import java.util.Set;
27 import org.checkerframework.checker.nullness.qual.Nullable;
28
29 /**
30 * A map which forwards all its method calls to another map. Subclasses should override one or more
31 * methods to modify the behavior of the backing map as desired per the <a
32 * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>.
33 *
34 * <p><b>Warning:</b> The methods of {@code ForwardingMap} forward <i>indiscriminately</i> to the
35 * methods of the delegate. For example, overriding {@link #put} alone <i>will not</i> change the
36 * behavior of {@link #putAll}, which can lead to unexpected behavior. In this case, you should
37 * override {@code putAll} as well, either providing your own implementation, or delegating to the
38 * provided {@code standardPutAll} method.
39 *
40 * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code
41 * default} methods. Instead, it inherits their default implementations. When those implementations
42 * invoke methods, they invoke methods on the {@code ForwardingMap}.
43 *
44 * <p>Each of the {@code standard} methods, where appropriate, use {@link Objects#equal} to test
45 * equality for both keys and values. This may not be the desired behavior for map implementations
46 * that use non-standard notions of key equality, such as a {@code SortedMap} whose comparator is
47 * not consistent with {@code equals}.
48 *
49 * <p>The {@code standard} methods and the collection views they return are not guaranteed to be
50 * thread-safe, even when all of the methods that they depend on are thread-safe.
51 *
52 * @author Kevin Bourrillion
53 * @author Jared Levy
54 * @author Louis Wasserman
55 * @since 2.0
56 */
57 @GwtCompatible
58 public abstract class ForwardingMap<K, V> extends ForwardingObject implements Map<K, V> {
59 // TODO(lowasser): identify places where thread safety is actually lost
60
61 /** Constructor for use by subclasses. */
62 protected ForwardingMap() {}
63
64 @Override
65 protected abstract Map<K, V> delegate();
66
67 @Override
68 public int size() {
69 return delegate().size();
70 }
71
72 @Override
73 public boolean isEmpty() {
74 return delegate().isEmpty();
75 }
76
77 @CanIgnoreReturnValue
78 @Override
79 public V remove(Object key) {
80 return delegate().remove(key);
81 }
82
83 @Override
84 public void clear() {
85 delegate().clear();
86 }
87
88 @Override
89 public boolean containsKey(@Nullable Object key) {
90 return delegate().containsKey(key);
91 }
92
93 @Override
94 public boolean containsValue(@Nullable Object value) {
95 return delegate().containsValue(value);
96 }
97
98 @Override
99 public V get(@Nullable Object key) {
100 return delegate().get(key);
101 }
102
103 @CanIgnoreReturnValue
104 @Override
105 public V put(K key, V value) {
106 return delegate().put(key, value);
107 }
108
109 @Override
110 public void putAll(Map<? extends K, ? extends V> map) {
111 delegate().putAll(map);
112 }
113
114 @Override
115 public Set<K> keySet() {
116 return delegate().keySet();
117 }
118
119 @Override
120 public Collection<V> values() {
121 return delegate().values();
122 }
123
124 @Override
125 public Set<Entry<K, V>> entrySet() {
126 return delegate().entrySet();
127 }
128
129 @Override
130 public boolean equals(@Nullable Object object) {
131 return object == this || delegate().equals(object);
132 }
133
134 @Override
135 public int hashCode() {
136 return delegate().hashCode();
137 }
138
139 /**
140 * A sensible definition of {@link #putAll(Map)} in terms of {@link #put(Object, Object)}. If you
141 * override {@link #put(Object, Object)}, you may wish to override {@link #putAll(Map)} to forward
142 * to this implementation.
143 *
144 * @since 7.0
145 */
146 protected void standardPutAll(Map<? extends K, ? extends V> map) {
147 Maps.putAllImpl(this, map);
148 }
149
150 /**
151 * A sensible, albeit inefficient, definition of {@link #remove} in terms of the {@code iterator}
152 * method of {@link #entrySet}. If you override {@link #entrySet}, you may wish to override {@link
153 * #remove} to forward to this implementation.
154 *
155 * <p>Alternately, you may wish to override {@link #remove} with {@code keySet().remove}, assuming
156 * that approach would not lead to an infinite loop.
157 *
158 * @since 7.0
159 */
160 @Beta
161 protected V standardRemove(@Nullable Object key) {
162 Iterator<Entry<K, V>> entryIterator = entrySet().iterator();
163 while (entryIterator.hasNext()) {
164 Entry<K, V> entry = entryIterator.next();
165 if (Objects.equal(entry.getKey(), key)) {
166 V value = entry.getValue();
167 entryIterator.remove();
168 return value;
169 }
170 }
171 return null;
172 }
173
174 /**
175 * A sensible definition of {@link #clear} in terms of the {@code iterator} method of {@link
176 * #entrySet}. In many cases, you may wish to override {@link #clear} to forward to this
177 * implementation.
178 *
179 * @since 7.0
180 */
181 protected void standardClear() {
182 Iterators.clear(entrySet().iterator());
183 }
184
185 /**
186 * A sensible implementation of {@link Map#keySet} in terms of the following methods: {@link
187 * ForwardingMap#clear}, {@link ForwardingMap#containsKey}, {@link ForwardingMap#isEmpty}, {@link
188 * ForwardingMap#remove}, {@link ForwardingMap#size}, and the {@link Set#iterator} method of
189 * {@link ForwardingMap#entrySet}. In many cases, you may wish to override {@link
190 * ForwardingMap#keySet} to forward to this implementation or a subclass thereof.
191 *
192 * @since 10.0
193 */
194 @Beta
195 protected class StandardKeySet extends Maps.KeySet<K, V> {
196 /** Constructor for use by subclasses. */
197 public StandardKeySet() {
198 super(ForwardingMap.this);
199 }
200 }
201
202 /**
203 * A sensible, albeit inefficient, definition of {@link #containsKey} in terms of the {@code
204 * iterator} method of {@link #entrySet}. If you override {@link #entrySet}, you may wish to
205 * override {@link #containsKey} to forward to this implementation.
206 *
207 * @since 7.0
208 */
209 @Beta
210 protected boolean standardContainsKey(@Nullable Object key) {
211 return Maps.containsKeyImpl(this, key);
212 }
213
214 /**
215 * A sensible implementation of {@link Map#values} in terms of the following methods: {@link
216 * ForwardingMap#clear}, {@link ForwardingMap#containsValue}, {@link ForwardingMap#isEmpty},
217 * {@link ForwardingMap#size}, and the {@link Set#iterator} method of {@link
218 * ForwardingMap#entrySet}. In many cases, you may wish to override {@link ForwardingMap#values}
219 * to forward to this implementation or a subclass thereof.
220 *
221 * @since 10.0
222 */
223 @Beta
224 protected class StandardValues extends Maps.Values<K, V> {
225 /** Constructor for use by subclasses. */
226 public StandardValues() {
227 super(ForwardingMap.this);
228 }
229 }
230
231 /**
232 * A sensible definition of {@link #containsValue} in terms of the {@code iterator} method of
233 * {@link #entrySet}. If you override {@link #entrySet}, you may wish to override {@link
234 * #containsValue} to forward to this implementation.
235 *
236 * @since 7.0
237 */
238 protected boolean standardContainsValue(@Nullable Object value) {
239 return Maps.containsValueImpl(this, value);
240 }
241
242 /**
243 * A sensible implementation of {@link Map#entrySet} in terms of the following methods: {@link
244 * ForwardingMap#clear}, {@link ForwardingMap#containsKey}, {@link ForwardingMap#get}, {@link
245 * ForwardingMap#isEmpty}, {@link ForwardingMap#remove}, and {@link ForwardingMap#size}. In many
246 * cases, you may wish to override {@link #entrySet} to forward to this implementation or a
247 * subclass thereof.
248 *
249 * @since 10.0
250 */
251 @Beta
252 protected abstract class StandardEntrySet extends Maps.EntrySet<K, V> {
253 /** Constructor for use by subclasses. */
254 public StandardEntrySet() {}
255
256 @Override
257 Map<K, V> map() {
258 return ForwardingMap.this;
259 }
260 }
261
262 /**
263 * A sensible definition of {@link #isEmpty} in terms of the {@code iterator} method of {@link
264 * #entrySet}. If you override {@link #entrySet}, you may wish to override {@link #isEmpty} to
265 * forward to this implementation.
266 *
267 * @since 7.0
268 */
269 protected boolean standardIsEmpty() {
270 return !entrySet().iterator().hasNext();
271 }
272
273 /**
274 * A sensible definition of {@link #equals} in terms of the {@code equals} method of {@link
275 * #entrySet}. If you override {@link #entrySet}, you may wish to override {@link #equals} to
276 * forward to this implementation.
277 *
278 * @since 7.0
279 */
280 protected boolean standardEquals(@Nullable Object object) {
281 return Maps.equalsImpl(this, object);
282 }
283
284 /**
285 * A sensible definition of {@link #hashCode} in terms of the {@code iterator} method of {@link
286 * #entrySet}. If you override {@link #entrySet}, you may wish to override {@link #hashCode} to
287 * forward to this implementation.
288 *
289 * @since 7.0
290 */
291 protected int standardHashCode() {
292 return Sets.hashCodeImpl(entrySet());
293 }
294
295 /**
296 * A sensible definition of {@link #toString} in terms of the {@code iterator} method of {@link
297 * #entrySet}. If you override {@link #entrySet}, you may wish to override {@link #toString} to
298 * forward to this implementation.
299 *
300 * @since 7.0
301 */
302 protected String standardToString() {
303 return Maps.toStringImpl(this);
304 }
305 }