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 23 import java.util.Collection; 24 import java.util.Iterator; 25 import java.util.Set; 26 27 import javax.annotation.Nullable; 28 29 /** 30 * A multiset which forwards all its method calls to another multiset. 31 * Subclasses should override one or more methods to modify the behavior of the 32 * backing multiset as desired per the <a 33 * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>. 34 * 35 * <p><b>Warning:</b> The methods of {@code ForwardingMultiset} forward 36 * <b>indiscriminately</b> to the methods of the delegate. For example, 37 * overriding {@link #add(Object, int)} alone <b>will not</b> change the 38 * behavior of {@link #add(Object)}, which can lead to unexpected behavior. In 39 * this case, you should override {@code add(Object)} as well, either providing 40 * your own implementation, or delegating to the provided {@code standardAdd} 41 * method. 42 * 43 * <p>The {@code standard} methods and any collection views they return are not 44 * guaranteed to be thread-safe, even when all of the methods that they depend 45 * on are thread-safe. 46 * 47 * @author Kevin Bourrillion 48 * @author Louis Wasserman 49 * @since 2.0 (imported from Google Collections Library) 50 */ 51 @GwtCompatible 52 public abstract class ForwardingMultiset<E> extends ForwardingCollection<E> 53 implements Multiset<E> { 54 55 /** Constructor for use by subclasses. */ 56 protected ForwardingMultiset() {} 57 58 @Override protected abstract Multiset<E> delegate(); 59 60 @Override 61 public int count(Object element) { 62 return delegate().count(element); 63 } 64 65 @Override 66 public int add(E element, int occurrences) { 67 return delegate().add(element, occurrences); 68 } 69 70 @Override 71 public int remove(Object element, int occurrences) { 72 return delegate().remove(element, occurrences); 73 } 74 75 @Override 76 public Set<E> elementSet() { 77 return delegate().elementSet(); 78 } 79 80 @Override 81 public Set<Entry<E>> entrySet() { 82 return delegate().entrySet(); 83 } 84 85 @Override public boolean equals(@Nullable Object object) { 86 return object == this || delegate().equals(object); 87 } 88 89 @Override public int hashCode() { 90 return delegate().hashCode(); 91 } 92 93 @Override 94 public int setCount(E element, int count) { 95 return delegate().setCount(element, count); 96 } 97 98 @Override 99 public boolean setCount(E element, int oldCount, int newCount) { 100 return delegate().setCount(element, oldCount, newCount); 101 } 102 103 /** 104 * A sensible definition of {@link #contains} in terms of {@link #count}. If 105 * you override {@link #count}, you may wish to override {@link #contains} to 106 * forward to this implementation. 107 * 108 * @since 7.0 109 */ 110 @Override @Beta protected boolean standardContains(@Nullable Object object) { 111 return count(object) > 0; 112 } 113 114 /** 115 * A sensible definition of {@link #clear} in terms of the {@code iterator} 116 * method of {@link #entrySet}. If you override {@link #entrySet}, you may 117 * wish to override {@link #clear} to forward to this implementation. 118 * 119 * @since 7.0 120 */ 121 @Override @Beta protected void standardClear() { 122 Iterator<Entry<E>> entryIterator = entrySet().iterator(); 123 while (entryIterator.hasNext()) { 124 entryIterator.next(); 125 entryIterator.remove(); 126 } 127 } 128 129 /** 130 * A sensible, albeit inefficient, definition of {@link #count} in terms of 131 * {@link #entrySet}. If you override {@link #entrySet}, you may wish to 132 * override {@link #count} to forward to this implementation. 133 * 134 * @since 7.0 135 */ 136 @Beta protected int standardCount(@Nullable Object object) { 137 for (Entry<?> entry : this.entrySet()) { 138 if (Objects.equal(entry.getElement(), object)) { 139 return entry.getCount(); 140 } 141 } 142 return 0; 143 } 144 145 /** 146 * A sensible definition of {@link #add(Object)} in terms of {@link 147 * #add(Object, int)}. If you override {@link #add(Object, int)}, you may 148 * wish to override {@link #add(Object)} to forward to this implementation. 149 * 150 * @since 7.0 151 */ 152 @Beta protected boolean standardAdd(E element) { 153 add(element, 1); 154 return true; 155 } 156 157 /** 158 * A sensible definition of {@link #addAll(Collection)} in terms of {@link 159 * #add(Object)} and {@link #add(Object, int)}. If you override either of 160 * these methods, you may wish to override {@link #addAll(Collection)} to 161 * forward to this implementation. 162 * 163 * @since 7.0 164 */ 165 @Beta @Override protected boolean standardAddAll( 166 Collection<? extends E> elementsToAdd) { 167 return Multisets.addAllImpl(this, elementsToAdd); 168 } 169 170 /** 171 * A sensible definition of {@link #remove(Object)} in terms of {@link 172 * #remove(Object, int)}. If you override {@link #remove(Object, int)}, you 173 * may wish to override {@link #remove(Object)} to forward to this 174 * implementation. 175 * 176 * @since 7.0 177 */ 178 @Beta @Override protected boolean standardRemove(Object element) { 179 return remove(element, 1) > 0; 180 } 181 182 /** 183 * A sensible definition of {@link #removeAll} in terms of the {@code 184 * removeAll} method of {@link #elementSet}. If you override {@link 185 * #elementSet}, you may wish to override {@link #removeAll} to forward to 186 * this implementation. 187 * 188 * @since 7.0 189 */ 190 @Beta @Override protected boolean standardRemoveAll( 191 Collection<?> elementsToRemove) { 192 return Multisets.removeAllImpl(this, elementsToRemove); 193 } 194 195 /** 196 * A sensible definition of {@link #retainAll} in terms of the {@code 197 * retainAll} method of {@link #elementSet}. If you override {@link 198 * #elementSet}, you may wish to override {@link #retainAll} to forward to 199 * this implementation. 200 * 201 * @since 7.0 202 */ 203 @Beta @Override protected boolean standardRetainAll( 204 Collection<?> elementsToRetain) { 205 return Multisets.retainAllImpl(this, elementsToRetain); 206 } 207 208 /** 209 * A sensible definition of {@link #setCount(Object, int)} in terms of {@link 210 * #count(Object)}, {@link #add(Object, int)}, and {@link #remove(Object, 211 * int)}. {@link #entrySet()}. If you override any of these methods, you may 212 * wish to override {@link #setCount(Object, int)} to forward to this 213 * implementation. 214 * 215 * @since 7.0 216 */ 217 @Beta 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 223 * {@link #count(Object)} and {@link #setCount(Object, int)}. If you override 224 * either of these methods, you may wish to override {@link #setCount(Object, 225 * int, int)} to forward to this implementation. 226 * 227 * @since 7.0 228 */ 229 @Beta protected boolean standardSetCount( 230 E element, int oldCount, int newCount) { 231 return Multisets.setCountImpl(this, element, oldCount, newCount); 232 } 233 234 /** 235 * A sensible implementation of {@link Multiset#elementSet} in terms of the 236 * following methods: {@link ForwardingMultiset#clear}, {@link 237 * ForwardingMultiset#contains}, {@link ForwardingMultiset#containsAll}, 238 * {@link ForwardingMultiset#count}, {@link ForwardingMultiset#isEmpty}, the 239 * {@link Set#size} and {@link Set#iterator} methods of {@link 240 * ForwardingMultiset#entrySet}, and {@link ForwardingMultiset#remove(Object, 241 * int)}. In many situations, you may wish to override {@link 242 * ForwardingMultiset#elementSet} to forward to this implementation or a 243 * subclass thereof. 244 * 245 * @since 10.0 246 */ 247 @Beta 248 protected class StandardElementSet extends Multisets.ElementSet<E> { 249 public StandardElementSet() {} 250 251 @Override 252 Multiset<E> multiset() { 253 return ForwardingMultiset.this; 254 } 255 } 256 257 /** 258 * A sensible definition of {@link #iterator} in terms of {@link #entrySet} 259 * and {@link #remove(Object)}. If you override either of these methods, you 260 * may wish to override {@link #iterator} to forward to this implementation. 261 * 262 * @since 7.0 263 */ 264 @Beta protected Iterator<E> standardIterator() { 265 return Multisets.iteratorImpl(this); 266 } 267 268 /** 269 * A sensible, albeit inefficient, definition of {@link #size} in terms of 270 * {@link #entrySet}. If you override {@link #entrySet}, you may wish to 271 * override {@link #size} to forward to this implementation. 272 * 273 * @since 7.0 274 */ 275 @Beta protected int standardSize() { 276 return Multisets.sizeImpl(this); 277 } 278 279 /** 280 * A sensible, albeit inefficient, definition of {@link #size} in terms of 281 * {@code entrySet().size()} and {@link #count}. If you override either of 282 * these methods, you may wish to override {@link #size} to forward to this 283 * implementation. 284 * 285 * @since 7.0 286 */ 287 @Beta protected boolean standardEquals(@Nullable Object object) { 288 return Multisets.equalsImpl(this, object); 289 } 290 291 /** 292 * A sensible definition of {@link #hashCode} as {@code entrySet().hashCode()} 293 * . If you override {@link #entrySet}, you may wish to override {@link 294 * #hashCode} to forward to this implementation. 295 * 296 * @since 7.0 297 */ 298 @Beta protected int standardHashCode() { 299 return entrySet().hashCode(); 300 } 301 302 /** 303 * A sensible definition of {@link #toString} as {@code entrySet().toString()} 304 * . If you override {@link #entrySet}, you may wish to override {@link 305 * #toString} to forward to this implementation. 306 * 307 * @since 7.0 308 */ 309 @Beta @Override protected String standardToString() { 310 return entrySet().toString(); 311 } 312 } 313
