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