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