001/* 002 * Copyright (C) 2007 The Guava 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 * http://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 com.google.common.collect; 018 019import com.google.common.annotations.Beta; 020import com.google.common.annotations.GwtCompatible; 021import com.google.common.base.Objects; 022import com.google.errorprone.annotations.CanIgnoreReturnValue; 023import java.util.Collection; 024import java.util.Iterator; 025import java.util.Map; 026import java.util.Set; 027import org.checkerframework.checker.nullness.qual.Nullable; 028 029/** 030 * A map which forwards all its method calls to another map. Subclasses should override one or more 031 * methods to modify the behavior of the backing map as desired per the <a 032 * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>. 033 * 034 * <p><b>Warning:</b> The methods of {@code ForwardingMap} forward <i>indiscriminately</i> to the 035 * methods of the delegate. For example, overriding {@link #put} alone <i>will not</i> change the 036 * behavior of {@link #putAll}, which can lead to unexpected behavior. In this case, you should 037 * override {@code putAll} as well, either providing your own implementation, or delegating to the 038 * provided {@code standardPutAll} method. 039 * 040 * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code 041 * default} methods. Instead, it inherits their default implementations. When those implementations 042 * invoke methods, they invoke methods on the {@code ForwardingMap}. 043 * 044 * <p>Each of the {@code standard} methods, where appropriate, use {@link Objects#equal} to test 045 * equality for both keys and values. This may not be the desired behavior for map implementations 046 * that use non-standard notions of key equality, such as a {@code SortedMap} whose comparator is 047 * not consistent with {@code equals}. 048 * 049 * <p>The {@code standard} methods and the collection views they return are not guaranteed to be 050 * thread-safe, even when all of the methods that they depend on are thread-safe. 051 * 052 * @author Kevin Bourrillion 053 * @author Jared Levy 054 * @author Louis Wasserman 055 * @since 2.0 056 */ 057@GwtCompatible 058public abstract class ForwardingMap<K, V> extends ForwardingObject implements Map<K, V> { 059 // TODO(lowasser): identify places where thread safety is actually lost 060 061 /** Constructor for use by subclasses. */ 062 protected ForwardingMap() {} 063 064 @Override 065 protected abstract Map<K, V> delegate(); 066 067 @Override 068 public int size() { 069 return delegate().size(); 070 } 071 072 @Override 073 public boolean isEmpty() { 074 return delegate().isEmpty(); 075 } 076 077 @CanIgnoreReturnValue 078 @Override 079 public V remove(Object object) { 080 return delegate().remove(object); 081 } 082 083 @Override 084 public void clear() { 085 delegate().clear(); 086 } 087 088 @Override 089 public boolean containsKey(@Nullable Object key) { 090 return delegate().containsKey(key); 091 } 092 093 @Override 094 public boolean containsValue(@Nullable Object value) { 095 return delegate().containsValue(value); 096 } 097 098 @Override 099 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}