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.errorprone.annotations.CanIgnoreReturnValue;
022import java.util.Collection;
023import java.util.Iterator;
024import java.util.List;
025import java.util.ListIterator;
026import javax.annotation.Nullable;
027
028/**
029 * A list which forwards all its method calls to another list. Subclasses should
030 * override one or more methods to modify the behavior of the backing list as
031 * desired per the <a
032 * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>.
033 *
034 * <p>This class does not implement {@link java.util.RandomAccess}. If the
035 * delegate supports random access, the {@code ForwardingList} subclass should
036 * implement the {@code RandomAccess} interface.
037 *
038 * <p><b>Warning:</b> The methods of {@code ForwardingList} forward
039 * <b>indiscriminately</b> to the methods of the delegate. For example,
040 * overriding {@link #add} alone <b>will not</b> change the behavior of {@link
041 * #addAll}, which can lead to unexpected behavior. In this case, you should
042 * override {@code addAll} as well, either providing your own implementation, or
043 * delegating to the provided {@code standardAddAll} method.
044 *
045 * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code
046 * default} methods. Instead, it inherits their default implementations. When those implementations
047 * invoke methods, they invoke methods on the {@code ForwardingList}.
048 *
049 * <p>The {@code standard} methods and any collection views they return are not
050 * guaranteed to be thread-safe, even when all of the methods that they depend
051 * on are thread-safe.
052 *
053 * @author Mike Bostock
054 * @author Louis Wasserman
055 * @since 2.0
056 */
057@GwtCompatible
058public abstract class ForwardingList<E> extends ForwardingCollection<E> implements List<E> {
059  // TODO(lowasser): identify places where thread safety is actually lost
060
061  /** Constructor for use by subclasses. */
062  protected ForwardingList() {}
063
064  @Override
065  protected abstract List<E> delegate();
066
067  @Override
068  public void add(int index, E element) {
069    delegate().add(index, element);
070  }
071
072  @CanIgnoreReturnValue
073  @Override
074  public boolean addAll(int index, Collection<? extends E> elements) {
075    return delegate().addAll(index, elements);
076  }
077
078  @Override
079  public E get(int index) {
080    return delegate().get(index);
081  }
082
083  @Override
084  public int indexOf(Object element) {
085    return delegate().indexOf(element);
086  }
087
088  @Override
089  public int lastIndexOf(Object element) {
090    return delegate().lastIndexOf(element);
091  }
092
093  @Override
094  public ListIterator<E> listIterator() {
095    return delegate().listIterator();
096  }
097
098  @Override
099  public ListIterator<E> listIterator(int index) {
100    return delegate().listIterator(index);
101  }
102
103  @CanIgnoreReturnValue
104  @Override
105  public E remove(int index) {
106    return delegate().remove(index);
107  }
108
109  @CanIgnoreReturnValue
110  @Override
111  public E set(int index, E element) {
112    return delegate().set(index, element);
113  }
114
115  @Override
116  public List<E> subList(int fromIndex, int toIndex) {
117    return delegate().subList(fromIndex, toIndex);
118  }
119
120  @Override
121  public boolean equals(@Nullable Object object) {
122    return object == this || delegate().equals(object);
123  }
124
125  @Override
126  public int hashCode() {
127    return delegate().hashCode();
128  }
129
130  /**
131   * A sensible default implementation of {@link #add(Object)}, in terms of
132   * {@link #add(int, Object)}. If you override {@link #add(int, Object)}, you
133   * may wish to override {@link #add(Object)} to forward to this
134   * implementation.
135   *
136   * @since 7.0
137   */
138  protected boolean standardAdd(E element) {
139    add(size(), element);
140    return true;
141  }
142
143  /**
144   * A sensible default implementation of {@link #addAll(int, Collection)}, in
145   * terms of the {@code add} method of {@link #listIterator(int)}. If you
146   * override {@link #listIterator(int)}, you may wish to override {@link
147   * #addAll(int, Collection)} to forward to this implementation.
148   *
149   * @since 7.0
150   */
151  protected boolean standardAddAll(int index, Iterable<? extends E> elements) {
152    return Lists.addAllImpl(this, index, elements);
153  }
154
155  /**
156   * A sensible default implementation of {@link #indexOf}, in terms of {@link
157   * #listIterator()}. If you override {@link #listIterator()}, you may wish to
158   * override {@link #indexOf} to forward to this implementation.
159   *
160   * @since 7.0
161   */
162  protected int standardIndexOf(@Nullable Object element) {
163    return Lists.indexOfImpl(this, element);
164  }
165
166  /**
167   * A sensible default implementation of {@link #lastIndexOf}, in terms of
168   * {@link #listIterator(int)}. If you override {@link #listIterator(int)}, you
169   * may wish to override {@link #lastIndexOf} to forward to this
170   * implementation.
171   *
172   * @since 7.0
173   */
174  protected int standardLastIndexOf(@Nullable Object element) {
175    return Lists.lastIndexOfImpl(this, element);
176  }
177
178  /**
179   * A sensible default implementation of {@link #iterator}, in terms of
180   * {@link #listIterator()}. If you override {@link #listIterator()}, you may
181   * wish to override {@link #iterator} to forward to this implementation.
182   *
183   * @since 7.0
184   */
185  protected Iterator<E> standardIterator() {
186    return listIterator();
187  }
188
189  /**
190   * A sensible default implementation of {@link #listIterator()}, in terms of
191   * {@link #listIterator(int)}. If you override {@link #listIterator(int)}, you
192   * may wish to override {@link #listIterator()} to forward to this
193   * implementation.
194   *
195   * @since 7.0
196   */
197  protected ListIterator<E> standardListIterator() {
198    return listIterator(0);
199  }
200
201  /**
202   * A sensible default implementation of {@link #listIterator(int)}, in terms
203   * of {@link #size}, {@link #get(int)}, {@link #set(int, Object)}, {@link
204   * #add(int, Object)}, and {@link #remove(int)}. If you override any of these
205   * methods, you may wish to override {@link #listIterator(int)} to forward to
206   * this implementation.
207   *
208   * @since 7.0
209   */
210  @Beta
211  protected ListIterator<E> standardListIterator(int start) {
212    return Lists.listIteratorImpl(this, start);
213  }
214
215  /**
216   * A sensible default implementation of {@link #subList(int, int)}. If you
217   * override any other methods, you may wish to override {@link #subList(int,
218   * int)} to forward to this implementation.
219   *
220   * @since 7.0
221   */
222  @Beta
223  protected List<E> standardSubList(int fromIndex, int toIndex) {
224    return Lists.subListImpl(this, fromIndex, toIndex);
225  }
226
227  /**
228   * A sensible definition of {@link #equals(Object)} in terms of {@link #size}
229   * and {@link #iterator}. If you override either of those methods, you may
230   * wish to override {@link #equals(Object)} to forward to this implementation.
231   *
232   * @since 7.0
233   */
234  @Beta
235  protected boolean standardEquals(@Nullable Object object) {
236    return Lists.equalsImpl(this, object);
237  }
238
239  /**
240   * A sensible definition of {@link #hashCode} in terms of {@link #iterator}.
241   * If you override {@link #iterator}, you may wish to override {@link
242   * #hashCode} to forward to this implementation.
243   *
244   * @since 7.0
245   */
246  @Beta
247  protected int standardHashCode() {
248    return Lists.hashCodeImpl(this);
249  }
250}