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 import com.google.errorprone.annotations.CanIgnoreReturnValue;
23 import java.util.Collection;
24 import java.util.Iterator;
25 import java.util.Set;
26 import javax.annotation.CheckForNull;
27 import org.checkerframework.checker.nullness.qual.Nullable;
28
29 /**
30 * A multiset which forwards all its method calls to another multiset. Subclasses should override
31 * one or more methods to modify the behavior of the backing multiset as desired per the <a
32 * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>.
33 *
34 * <p><b>Warning:</b> The methods of {@code ForwardingMultiset} forward <b>indiscriminately</b> to
35 * the methods of the delegate. For example, overriding {@link #add(Object, int)} alone <b>will
36 * not</b> change the behavior of {@link #add(Object)}, which can lead to unexpected behavior. In
37 * this case, you should override {@code add(Object)} as well, either providing your own
38 * implementation, or delegating to the provided {@code standardAdd} method.
39 *
40 * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code
41 * default} methods. Instead, it inherits their default implementations. When those implementations
42 * invoke methods, they invoke methods on the {@code ForwardingMultiset}.
43 *
44 * <p>The {@code standard} methods and any collection views they return are not guaranteed to be
45 * thread-safe, even when all of the methods that they depend on are thread-safe.
46 *
47 * @author Kevin Bourrillion
48 * @author Louis Wasserman
49 * @since 2.0
50 */
51 @GwtCompatible
52 @ElementTypesAreNonnullByDefault
53 public abstract class ForwardingMultiset<E extends @Nullable Object> extends ForwardingCollection<E>
54 implements Multiset<E> {
55
56 /** Constructor for use by subclasses. */
57 protected ForwardingMultiset() {}
58
59 @Override
60 protected abstract Multiset<E> delegate();
61
62 @Override
63 public int count(@CheckForNull Object element) {
64 return delegate().count(element);
65 }
66
67 @CanIgnoreReturnValue
68 @Override
69 public int add(@ParametricNullness E element, int occurrences) {
70 return delegate().add(element, occurrences);
71 }
72
73 @CanIgnoreReturnValue
74 @Override
75 public int remove(@CheckForNull Object element, int occurrences) {
76 return delegate().remove(element, occurrences);
77 }
78
79 @Override
80 public Set<E> elementSet() {
81 return delegate().elementSet();
82 }
83
84 @Override
85 public Set<Entry<E>> entrySet() {
86 return delegate().entrySet();
87 }
88
89 @Override
90 public boolean equals(@CheckForNull Object object) {
91 return object == this || delegate().equals(object);
92 }
93
94 @Override
95 public int hashCode() {
96 return delegate().hashCode();
97 }
98
99 @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 }