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 org.jspecify.annotations.Nullable;
025
026/**
027 * A collection which forwards all its method calls to another collection. Subclasses should
028 * override one or more methods to modify the behavior of the backing collection as desired per the
029 * <a href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>.
030 *
031 * <p><b>Warning:</b> The methods of {@code ForwardingCollection} forward <b>indiscriminately</b> to
032 * the methods of the delegate. For example, overriding {@link #add} alone <b>will not</b> change
033 * the behavior of {@link #addAll}, which can lead to unexpected behavior. In this case, you should
034 * override {@code addAll} as well, either providing your own implementation, or delegating to the
035 * provided {@code standardAddAll} method.
036 *
037 * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code
038 * default} methods. Instead, it inherits their default implementations. When those implementations
039 * invoke methods, they invoke methods on the {@code ForwardingCollection}.
040 *
041 * <p>The {@code standard} methods are not guaranteed to be thread-safe, even when all of the
042 * methods that they depend on are thread-safe.
043 *
044 * @author Kevin Bourrillion
045 * @author Louis Wasserman
046 * @since 2.0
047 */
048@GwtCompatible
049public abstract class ForwardingCollection<E extends @Nullable Object> extends ForwardingObject
050    implements Collection<E> {
051  // TODO(lowasser): identify places where thread safety is actually lost
052
053  /** Constructor for use by subclasses. */
054  protected ForwardingCollection() {}
055
056  @Override
057  protected abstract Collection<E> delegate();
058
059  @Override
060  public Iterator<E> iterator() {
061    return delegate().iterator();
062  }
063
064  @Override
065  public int size() {
066    return delegate().size();
067  }
068
069  @CanIgnoreReturnValue
070  @Override
071  public boolean removeAll(Collection<?> collection) {
072    return delegate().removeAll(collection);
073  }
074
075  @Override
076  public boolean isEmpty() {
077    return delegate().isEmpty();
078  }
079
080  @Override
081  public boolean contains(@Nullable Object object) {
082    return delegate().contains(object);
083  }
084
085  @CanIgnoreReturnValue
086  @Override
087  public boolean add(@ParametricNullness E element) {
088    return delegate().add(element);
089  }
090
091  @CanIgnoreReturnValue
092  @Override
093  public boolean remove(@Nullable Object object) {
094    return delegate().remove(object);
095  }
096
097  @Override
098  public boolean containsAll(Collection<?> collection) {
099    return delegate().containsAll(collection);
100  }
101
102  @CanIgnoreReturnValue
103  @Override
104  public boolean addAll(Collection<? extends E> collection) {
105    return delegate().addAll(collection);
106  }
107
108  @CanIgnoreReturnValue
109  @Override
110  public boolean retainAll(Collection<?> collection) {
111    return delegate().retainAll(collection);
112  }
113
114  @Override
115  public void clear() {
116    delegate().clear();
117  }
118
119  @Override
120  public @Nullable Object[] toArray() {
121    return delegate().toArray();
122  }
123
124  @CanIgnoreReturnValue
125  @Override
126  @SuppressWarnings("nullness") // b/192354773 in our checker affects toArray declarations
127  public <T extends @Nullable Object> T[] toArray(T[] array) {
128    return delegate().toArray(array);
129  }
130
131  /**
132   * A sensible definition of {@link #contains} in terms of {@link #iterator}. If you override
133   * {@link #iterator}, you may wish to override {@link #contains} to forward to this
134   * implementation.
135   *
136   * @since 7.0
137   */
138  protected boolean standardContains(@Nullable Object object) {
139    return Iterators.contains(iterator(), object);
140  }
141
142  /**
143   * A sensible definition of {@link #containsAll} in terms of {@link #contains} . If you override
144   * {@link #contains}, you may wish to override {@link #containsAll} to forward to this
145   * implementation.
146   *
147   * @since 7.0
148   */
149  protected boolean standardContainsAll(Collection<?> collection) {
150    return Collections2.containsAllImpl(this, collection);
151  }
152
153  /**
154   * A sensible definition of {@link #addAll} in terms of {@link #add}. If you override {@link
155   * #add}, you may wish to override {@link #addAll} to forward to this implementation.
156   *
157   * @since 7.0
158   */
159  protected boolean standardAddAll(Collection<? extends E> collection) {
160    return Iterators.addAll(this, collection.iterator());
161  }
162
163  /**
164   * A sensible definition of {@link #remove} in terms of {@link #iterator}, using the iterator's
165   * {@code remove} method. If you override {@link #iterator}, you may wish to override {@link
166   * #remove} to forward to this implementation.
167   *
168   * @since 7.0
169   */
170  protected boolean standardRemove(@Nullable Object object) {
171    Iterator<E> iterator = iterator();
172    while (iterator.hasNext()) {
173      if (Objects.equal(iterator.next(), object)) {
174        iterator.remove();
175        return true;
176      }
177    }
178    return false;
179  }
180
181  /**
182   * A sensible definition of {@link #removeAll} in terms of {@link #iterator}, using the iterator's
183   * {@code remove} method. If you override {@link #iterator}, you may wish to override {@link
184   * #removeAll} to forward to this implementation.
185   *
186   * @since 7.0
187   */
188  protected boolean standardRemoveAll(Collection<?> collection) {
189    return Iterators.removeAll(iterator(), collection);
190  }
191
192  /**
193   * A sensible definition of {@link #retainAll} in terms of {@link #iterator}, using the iterator's
194   * {@code remove} method. If you override {@link #iterator}, you may wish to override {@link
195   * #retainAll} to forward to this implementation.
196   *
197   * @since 7.0
198   */
199  protected boolean standardRetainAll(Collection<?> collection) {
200    return Iterators.retainAll(iterator(), collection);
201  }
202
203  /**
204   * A sensible definition of {@link #clear} in terms of {@link #iterator}, using the iterator's
205   * {@code remove} method. If you override {@link #iterator}, you may wish to override {@link
206   * #clear} to forward to this implementation.
207   *
208   * @since 7.0
209   */
210  protected void standardClear() {
211    Iterators.clear(iterator());
212  }
213
214  /**
215   * A sensible definition of {@link #isEmpty} as {@code !iterator().hasNext}. If you override
216   * {@link #isEmpty}, you may wish to override {@link #isEmpty} to forward to this implementation.
217   * Alternately, it may be more efficient to implement {@code isEmpty} as {@code size() == 0}.
218   *
219   * @since 7.0
220   */
221  protected boolean standardIsEmpty() {
222    return !iterator().hasNext();
223  }
224
225  /**
226   * A sensible definition of {@link #toString} in terms of {@link #iterator}. If you override
227   * {@link #iterator}, you may wish to override {@link #toString} to forward to this
228   * implementation.
229   *
230   * @since 7.0
231   */
232  protected String standardToString() {
233    return Collections2.toStringImpl(this);
234  }
235
236  /**
237   * A sensible definition of {@link #toArray()} in terms of {@link #toArray(Object[])}. If you
238   * override {@link #toArray(Object[])}, you may wish to override {@link #toArray} to forward to
239   * this implementation.
240   *
241   * @since 7.0
242   */
243  protected @Nullable Object[] standardToArray() {
244    @Nullable Object[] newArray = new @Nullable Object[size()];
245    return toArray(newArray);
246  }
247
248  /**
249   * A sensible definition of {@link #toArray(Object[])} in terms of {@link #size} and {@link
250   * #iterator}. If you override either of these methods, you may wish to override {@link #toArray}
251   * to forward to this implementation.
252   *
253   * @since 7.0
254   */
255  protected <T extends @Nullable Object> T[] standardToArray(T[] array) {
256    return ObjectArrays.toArrayImpl(this, array);
257  }
258}