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 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 ForwardingCollection<E> implements Multiset<E> { 052 053 /** Constructor for use by subclasses. */ 054 protected ForwardingMultiset() {} 055 056 @Override 057 protected abstract Multiset<E> delegate(); 058 059 @Override 060 public int count(Object element) { 061 return delegate().count(element); 062 } 063 064 @CanIgnoreReturnValue 065 @Override 066 public int add(E element, int occurrences) { 067 return delegate().add(element, occurrences); 068 } 069 070 @CanIgnoreReturnValue 071 @Override 072 public int remove(Object element, int occurrences) { 073 return delegate().remove(element, occurrences); 074 } 075 076 @Override 077 public Set<E> elementSet() { 078 return delegate().elementSet(); 079 } 080 081 @Override 082 public Set<Entry<E>> entrySet() { 083 return delegate().entrySet(); 084 } 085 086 @Override 087 public boolean equals(@Nullable Object object) { 088 return object == this || delegate().equals(object); 089 } 090 091 @Override 092 public int hashCode() { 093 return delegate().hashCode(); 094 } 095 096 @CanIgnoreReturnValue 097 @Override 098 public int setCount(E element, int count) { 099 return delegate().setCount(element, count); 100 } 101 102 @CanIgnoreReturnValue 103 @Override 104 public boolean setCount(E element, int oldCount, int newCount) { 105 return delegate().setCount(element, oldCount, newCount); 106 } 107 108 /** 109 * A sensible definition of {@link #contains} in terms of {@link #count}. If you override {@link 110 * #count}, you may wish to override {@link #contains} to forward to this implementation. 111 * 112 * @since 7.0 113 */ 114 @Override 115 protected boolean standardContains(@Nullable Object object) { 116 return count(object) > 0; 117 } 118 119 /** 120 * A sensible definition of {@link #clear} in terms of the {@code iterator} method of {@link 121 * #entrySet}. If you override {@link #entrySet}, you may wish to override {@link #clear} to 122 * forward to this implementation. 123 * 124 * @since 7.0 125 */ 126 @Override 127 protected void standardClear() { 128 Iterators.clear(entrySet().iterator()); 129 } 130 131 /** 132 * A sensible, albeit inefficient, definition of {@link #count} in terms of {@link #entrySet}. If 133 * you override {@link #entrySet}, you may wish to override {@link #count} to forward to this 134 * implementation. 135 * 136 * @since 7.0 137 */ 138 @Beta 139 protected int standardCount(@Nullable 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(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 @Beta 168 @Override 169 protected boolean standardAddAll(Collection<? extends E> elementsToAdd) { 170 return Multisets.addAllImpl(this, elementsToAdd); 171 } 172 173 /** 174 * A sensible definition of {@link #remove(Object)} in terms of {@link #remove(Object, int)}. If 175 * you override {@link #remove(Object, int)}, you may wish to override {@link #remove(Object)} to 176 * forward to this implementation. 177 * 178 * @since 7.0 179 */ 180 @Override 181 protected boolean standardRemove(Object element) { 182 return remove(element, 1) > 0; 183 } 184 185 /** 186 * A sensible definition of {@link #removeAll} in terms of the {@code removeAll} method of {@link 187 * #elementSet}. If you override {@link #elementSet}, you may wish to override {@link #removeAll} 188 * to forward to this implementation. 189 * 190 * @since 7.0 191 */ 192 @Override 193 protected boolean standardRemoveAll(Collection<?> elementsToRemove) { 194 return Multisets.removeAllImpl(this, elementsToRemove); 195 } 196 197 /** 198 * A sensible definition of {@link #retainAll} in terms of the {@code retainAll} method of {@link 199 * #elementSet}. If you override {@link #elementSet}, you may wish to override {@link #retainAll} 200 * to forward to this implementation. 201 * 202 * @since 7.0 203 */ 204 @Override 205 protected boolean standardRetainAll(Collection<?> elementsToRetain) { 206 return Multisets.retainAllImpl(this, elementsToRetain); 207 } 208 209 /** 210 * A sensible definition of {@link #setCount(Object, int)} in terms of {@link #count(Object)}, 211 * {@link #add(Object, int)}, and {@link #remove(Object, int)}. {@link #entrySet()}. If you 212 * override any of these methods, you may wish to override {@link #setCount(Object, int)} to 213 * forward to this implementation. 214 * 215 * @since 7.0 216 */ 217 protected int standardSetCount(E element, int count) { 218 return Multisets.setCountImpl(this, element, count); 219 } 220 221 /** 222 * A sensible definition of {@link #setCount(Object, int, int)} in terms of {@link #count(Object)} 223 * and {@link #setCount(Object, int)}. If you override either of these methods, you may wish to 224 * override {@link #setCount(Object, int, int)} to forward to this implementation. 225 * 226 * @since 7.0 227 */ 228 protected boolean standardSetCount(E element, int oldCount, int newCount) { 229 return Multisets.setCountImpl(this, element, oldCount, newCount); 230 } 231 232 /** 233 * A sensible implementation of {@link Multiset#elementSet} in terms of the following methods: 234 * {@link ForwardingMultiset#clear}, {@link ForwardingMultiset#contains}, {@link 235 * ForwardingMultiset#containsAll}, {@link ForwardingMultiset#count}, {@link 236 * ForwardingMultiset#isEmpty}, the {@link Set#size} and {@link Set#iterator} methods of {@link 237 * ForwardingMultiset#entrySet}, and {@link ForwardingMultiset#remove(Object, int)}. In many 238 * situations, you may wish to override {@link ForwardingMultiset#elementSet} to forward to this 239 * implementation or a subclass thereof. 240 * 241 * @since 10.0 242 */ 243 @Beta 244 protected class StandardElementSet extends Multisets.ElementSet<E> { 245 /** Constructor for use by subclasses. */ 246 public StandardElementSet() {} 247 248 @Override 249 Multiset<E> multiset() { 250 return ForwardingMultiset.this; 251 } 252 253 @Override 254 public Iterator<E> iterator() { 255 return Multisets.elementIterator(multiset().entrySet().iterator()); 256 } 257 } 258 259 /** 260 * A sensible definition of {@link #iterator} in terms of {@link #entrySet} and {@link 261 * #remove(Object)}. If you override either of these methods, you may wish to override {@link 262 * #iterator} to forward to this implementation. 263 * 264 * @since 7.0 265 */ 266 protected Iterator<E> standardIterator() { 267 return Multisets.iteratorImpl(this); 268 } 269 270 /** 271 * A sensible, albeit inefficient, definition of {@link #size} in terms of {@link #entrySet}. If 272 * you override {@link #entrySet}, you may wish to override {@link #size} to forward to this 273 * implementation. 274 * 275 * @since 7.0 276 */ 277 protected int standardSize() { 278 return Multisets.linearTimeSizeImpl(this); 279 } 280 281 /** 282 * A sensible, albeit inefficient, definition of {@link #equals} in terms of {@code 283 * entrySet().size()} and {@link #count}. If you override either of these methods, you may wish to 284 * override {@link #equals} to forward to this implementation. 285 * 286 * @since 7.0 287 */ 288 protected boolean standardEquals(@Nullable Object object) { 289 return Multisets.equalsImpl(this, object); 290 } 291 292 /** 293 * A sensible definition of {@link #hashCode} as {@code entrySet().hashCode()} . If you override 294 * {@link #entrySet}, you may wish to override {@link #hashCode} to forward to this 295 * implementation. 296 * 297 * @since 7.0 298 */ 299 protected int standardHashCode() { 300 return entrySet().hashCode(); 301 } 302 303 /** 304 * A sensible definition of {@link #toString} as {@code entrySet().toString()} . If you override 305 * {@link #entrySet}, you may wish to override {@link #toString} to forward to this 306 * implementation. 307 * 308 * @since 7.0 309 */ 310 @Override 311 protected String standardToString() { 312 return entrySet().toString(); 313 } 314}