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 java.util.Map;
23 import java.util.Map.Entry;
24 import org.checkerframework.checker.nullness.qual.Nullable;
25
26 /**
27 * A map entry which forwards all its method calls to another map entry. Subclasses should override
28 * one or more methods to modify the behavior of the backing map entry as desired per the <a
29 * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>.
30 *
31 * <p><b>Warning:</b> The methods of {@code ForwardingMapEntry} forward <i>indiscriminately</i> to
32 * the methods of the delegate. For example, overriding {@link #getValue} alone <i>will not</i>
33 * change the behavior of {@link #equals}, which can lead to unexpected behavior. In this case, you
34 * should override {@code equals} as well, either providing your own implementation, or delegating
35 * to the provided {@code standardEquals} method.
36 *
37 * <p>Each of the {@code standard} methods, where appropriate, use {@link Objects#equal} to test
38 * equality for both keys and values. This may not be the desired behavior for map implementations
39 * that use non-standard notions of key equality, such as the entry of a {@code SortedMap} whose
40 * comparator is not consistent with {@code equals}.
41 *
42 * <p>The {@code standard} methods are not guaranteed to be thread-safe, even when all of the
43 * methods that they depend on are thread-safe.
44 *
45 * @author Mike Bostock
46 * @author Louis Wasserman
47 * @since 2.0
48 */
49 @GwtCompatible
50 public abstract class ForwardingMapEntry<K, V> extends ForwardingObject implements Map.Entry<K, V> {
51 // TODO(lowasser): identify places where thread safety is actually lost
52
53 /** Constructor for use by subclasses. */
54 protected ForwardingMapEntry() {}
55
56 @Override
57 protected abstract Entry<K, V> delegate();
58
59 @Override
60 public K getKey() {
61 return delegate().getKey();
62 }
63
64 @Override
65 public V getValue() {
66 return delegate().getValue();
67 }
68
69 @Override
70 public V setValue(V value) {
71 return delegate().setValue(value);
72 }
73
74 @Override
75 public boolean equals(@Nullable Object object) {
76 return delegate().equals(object);
77 }
78
79 @Override
80 public int hashCode() {
81 return delegate().hashCode();
82 }
83
84 /**
85 * A sensible definition of {@link #equals(Object)} in terms of {@link #getKey()} and {@link
86 * #getValue()}. If you override either of these methods, you may wish to override {@link
87 * #equals(Object)} to forward to this implementation.
88 *
89 * @since 7.0
90 */
91 protected boolean standardEquals(@Nullable Object object) {
92 if (object instanceof Entry) {
93 Entry<?, ?> that = (Entry<?, ?>) object;
94 return Objects.equal(this.getKey(), that.getKey())
95 && Objects.equal(this.getValue(), that.getValue());
96 }
97 return false;
98 }
99
100 /**
101 * A sensible definition of {@link #hashCode()} in terms of {@link #getKey()} and {@link
102 * #getValue()}. If you override either of these methods, you may wish to override {@link
103 * #hashCode()} to forward to this implementation.
104 *
105 * @since 7.0
106 */
107 protected int standardHashCode() {
108 K k = getKey();
109 V v = getValue();
110 return ((k == null) ? 0 : k.hashCode()) ^ ((v == null) ? 0 : v.hashCode());
111 }
112
113 /**
114 * A sensible definition of {@link #toString} in terms of {@link #getKey} and {@link #getValue}.
115 * If you override either of these methods, you may wish to override {@link #equals} to forward to
116 * this implementation.
117 *
118 * @since 7.0
119 */
120 @Beta
121 protected String standardToString() {
122 return getKey() + "=" + getValue();
123 }
124 }