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.Set; 026import javax.annotation.CheckForNull; 027import org.checkerframework.checker.nullness.qual.Nullable; 028 029/** 030 * A multiset which forwards all its method calls to another multiset. Subclasses should override 031 * one or more methods to modify the behavior of the backing multiset 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 ForwardingMultiset} forward <b>indiscriminately</b> to 035 * the methods of the delegate. For example, overriding {@link #add(Object, int)} alone <b>will 036 * not</b> change the behavior of {@link #add(Object)}, which can lead to unexpected behavior. In 037 * this case, you should override {@code add(Object)} as well, either providing your own 038 * implementation, or delegating to the provided {@code standardAdd} 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 ForwardingMultiset}. 043 * 044 * <p>The {@code standard} methods and any collection views they return are not guaranteed to be 045 * thread-safe, even when all of the methods that they depend on are thread-safe. 046 * 047 * @author Kevin Bourrillion 048 * @author Louis Wasserman 049 * @since 2.0 050 */ 051@GwtCompatible 052@ElementTypesAreNonnullByDefault 053public abstract class ForwardingMultiset<E extends @Nullable Object> extends ForwardingCollection<E> 054 implements Multiset<E> { 055 056 /** Constructor for use by subclasses. */ 057 protected ForwardingMultiset() {} 058 059 @Override 060 protected abstract Multiset<E> delegate(); 061 062 @Override 063 public int count(@CheckForNull Object element) { 064 return delegate().count(element); 065 } 066 067 @CanIgnoreReturnValue 068 @Override 069 public int add(@ParametricNullness E element, int occurrences) { 070 return delegate().add(element, occurrences); 071 } 072 073 @CanIgnoreReturnValue 074 @Override 075 public int remove(@CheckForNull Object element, int occurrences) { 076 return delegate().remove(element, occurrences); 077 } 078 079 @Override 080 public Set<E> elementSet() { 081 return delegate().elementSet(); 082 } 083 084 @Override 085 public Set<Entry<E>> entrySet() { 086 return delegate().entrySet(); 087 } 088 089 @Override 090 public boolean equals(@CheckForNull Object object) { 091 return object == this || delegate().equals(object); 092 } 093 094 @Override 095 public int hashCode() { 096 return delegate().hashCode(); 097 } 098 099 @CanIgnoreReturnValue 100 @Override 101 public int setCount(@ParametricNullness E element, int count) { 102 return delegate().setCount(element, count); 103 } 104 105 @CanIgnoreReturnValue 106 @Override 107 public boolean setCount(@ParametricNullness E element, int oldCount, int newCount) { 108 return delegate().setCount(element, oldCount, newCount); 109 } 110 111 /** 112 * A sensible definition of {@link #contains} in terms of {@link #count}. If you override {@link 113 * #count}, you may wish to override {@link #contains} to forward to this implementation. 114 * 115 * @since 7.0 116 */ 117 @Override 118 protected boolean standardContains(@CheckForNull Object object) { 119 return count(object) > 0; 120 } 121 122 /** 123 * A sensible definition of {@link #clear} in terms of the {@code iterator} method of {@link 124 * #entrySet}. If you override {@link #entrySet}, you may wish to override {@link #clear} to 125 * forward to this implementation. 126 * 127 * @since 7.0 128 */ 129 @Override 130 protected void standardClear() { 131 Iterators.clear(entrySet().iterator()); 132 } 133 134 /** 135 * A sensible, albeit inefficient, definition of {@link #count} in terms of {@link #entrySet}. If 136 * you override {@link #entrySet}, you may wish to override {@link #count} to forward to this 137 * implementation. 138 * 139 * @since 7.0 140 */ 141 @Beta 142 protected int standardCount(@CheckForNull Object object) { 143 for (Entry<?> entry : this.entrySet()) { 144 if (Objects.equal(entry.getElement(), object)) { 145 return entry.getCount(); 146 } 147 } 148 return 0; 149 } 150 151 /** 152 * A sensible definition of {@link #add(Object)} in terms of {@link #add(Object, int)}. If you 153 * override {@link #add(Object, int)}, you may wish to override {@link #add(Object)} to forward to 154 * this implementation. 155 * 156 * @since 7.0 157 */ 158 protected boolean standardAdd(@ParametricNullness E element) { 159 add(element, 1); 160 return true; 161 } 162 163 /** 164 * A sensible definition of {@link #addAll(Collection)} in terms of {@link #add(Object)} and 165 * {@link #add(Object, int)}. If you override either of these methods, you may wish to override 166 * {@link #addAll(Collection)} to forward to this implementation. 167 * 168 * @since 7.0 169 */ 170 @Beta 171 @Override 172 protected boolean standardAddAll(Collection<? extends E> elementsToAdd) { 173 return Multisets.addAllImpl(this, elementsToAdd); 174 } 175 176 /** 177 * A sensible definition of {@link #remove(Object)} in terms of {@link #remove(Object, int)}. If 178 * you override {@link #remove(Object, int)}, you may wish to override {@link #remove(Object)} to 179 * forward to this implementation. 180 * 181 * @since 7.0 182 */ 183 @Override 184 protected boolean standardRemove(@CheckForNull Object element) { 185 return remove(element, 1) > 0; 186 } 187 188 /** 189 * A sensible definition of {@link #removeAll} in terms of the {@code removeAll} method of {@link 190 * #elementSet}. If you override {@link #elementSet}, you may wish to override {@link #removeAll} 191 * to forward to this implementation. 192 * 193 * @since 7.0 194 */ 195 @Override 196 protected boolean standardRemoveAll(Collection<?> elementsToRemove) { 197 return Multisets.removeAllImpl(this, elementsToRemove); 198 } 199 200 /** 201 * A sensible definition of {@link #retainAll} in terms of the {@code retainAll} method of {@link 202 * #elementSet}. If you override {@link #elementSet}, you may wish to override {@link #retainAll} 203 * to forward to this implementation. 204 * 205 * @since 7.0 206 */ 207 @Override 208 protected boolean standardRetainAll(Collection<?> elementsToRetain) { 209 return Multisets.retainAllImpl(this, elementsToRetain); 210 } 211 212 /** 213 * A sensible definition of {@link #setCount(Object, int)} in terms of {@link #count(Object)}, 214 * {@link #add(Object, int)}, and {@link #remove(Object, int)}. {@link #entrySet()}. If you 215 * override any of these methods, you may wish to override {@link #setCount(Object, int)} to 216 * forward to this implementation. 217 * 218 * @since 7.0 219 */ 220 protected int standardSetCount(@ParametricNullness E element, int count) { 221 return Multisets.setCountImpl(this, element, count); 222 } 223 224 /** 225 * A sensible definition of {@link #setCount(Object, int, int)} in terms of {@link #count(Object)} 226 * and {@link #setCount(Object, int)}. If you override either of these methods, you may wish to 227 * override {@link #setCount(Object, int, int)} to forward to this implementation. 228 * 229 * @since 7.0 230 */ 231 protected boolean standardSetCount(@ParametricNullness E element, int oldCount, int newCount) { 232 return Multisets.setCountImpl(this, element, oldCount, newCount); 233 } 234 235 /** 236 * A sensible implementation of {@link Multiset#elementSet} in terms of the following methods: 237 * {@link ForwardingMultiset#clear}, {@link ForwardingMultiset#contains}, {@link 238 * ForwardingMultiset#containsAll}, {@link ForwardingMultiset#count}, {@link 239 * ForwardingMultiset#isEmpty}, the {@link Set#size} and {@link Set#iterator} methods of {@link 240 * ForwardingMultiset#entrySet}, and {@link ForwardingMultiset#remove(Object, int)}. In many 241 * situations, you may wish to override {@link ForwardingMultiset#elementSet} to forward to this 242 * implementation or a subclass thereof. 243 * 244 * @since 10.0 245 */ 246 @Beta 247 protected class StandardElementSet extends Multisets.ElementSet<E> { 248 /** Constructor for use by subclasses. */ 249 public StandardElementSet() {} 250 251 @Override 252 Multiset<E> multiset() { 253 return ForwardingMultiset.this; 254 } 255 256 @Override 257 public Iterator<E> iterator() { 258 return Multisets.elementIterator(multiset().entrySet().iterator()); 259 } 260 } 261 262 /** 263 * A sensible definition of {@link #iterator} in terms of {@link #entrySet} and {@link 264 * #remove(Object)}. If you override either of these methods, you may wish to override {@link 265 * #iterator} to forward to this implementation. 266 * 267 * @since 7.0 268 */ 269 protected Iterator<E> standardIterator() { 270 return Multisets.iteratorImpl(this); 271 } 272 273 /** 274 * A sensible, albeit inefficient, definition of {@link #size} in terms of {@link #entrySet}. If 275 * you override {@link #entrySet}, you may wish to override {@link #size} to forward to this 276 * implementation. 277 * 278 * @since 7.0 279 */ 280 protected int standardSize() { 281 return Multisets.linearTimeSizeImpl(this); 282 } 283 284 /** 285 * A sensible, albeit inefficient, definition of {@link #equals} in terms of {@code 286 * entrySet().size()} and {@link #count}. If you override either of these methods, you may wish to 287 * override {@link #equals} to forward to this implementation. 288 * 289 * @since 7.0 290 */ 291 protected boolean standardEquals(@CheckForNull Object object) { 292 return Multisets.equalsImpl(this, object); 293 } 294 295 /** 296 * A sensible definition of {@link #hashCode} as {@code entrySet().hashCode()} . If you override 297 * {@link #entrySet}, you may wish to override {@link #hashCode} to forward to this 298 * implementation. 299 * 300 * @since 7.0 301 */ 302 protected int standardHashCode() { 303 return entrySet().hashCode(); 304 } 305 306 /** 307 * A sensible definition of {@link #toString} as {@code entrySet().toString()} . If you override 308 * {@link #entrySet}, you may wish to override {@link #toString} to forward to this 309 * implementation. 310 * 311 * @since 7.0 312 */ 313 @Override 314 protected String standardToString() { 315 return entrySet().toString(); 316 } 317}