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