    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} and {@link #get(int)}. If you override either of these
    197       * methods you may wish to override {@link #listIterator(int)} to forward to
    198       * this implementation.
    199       *
    200       * @since 7.0
    201       */
    202      @Beta protected ListIterator<E> standardListIterator(int start) {
    203        return Lists.listIteratorImpl(this, start);
    204      }
    205
    206      /**
    207       * A sensible default implementation of {@link #subList(int, int)}. If you
    208       * override any other methods, you may wish to override {@link #subList(int,
    209       * int)} to forward to this implementation.
    210       *
    211       * @since 7.0
    212       */
    213      @Beta protected List<E> standardSubList(int fromIndex, int toIndex) {
    214        return Lists.subListImpl(this, fromIndex, toIndex);
    215      }
    216
    217      /**
    218       * A sensible definition of {@link #equals(Object)} in terms of {@link #size}
    219       * and {@link #iterator}. If you override either of those methods, you may
    220       * wish to override {@link #equals(Object)} to forward to this implementation.
    221       *
    222       * @since 7.0
    223       */
    224      @Beta protected boolean standardEquals(@Nullable Object object) {
    225        return Lists.equalsImpl(this, object);
    226      }
    227
    228      /**
    229       * A sensible definition of {@link #hashCode} in terms of {@link #iterator}.
    230       * If you override {@link #iterator}, you may wish to override {@link
    231       * #hashCode} to forward to this implementation.
    232       *
    233       * @since 7.0
    234       */
    235      @Beta protected int standardHashCode() {
    236        return Lists.hashCodeImpl(this);
    237      }
    238    }