    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.GwtCompatible;
    020
    021    import java.io.Serializable;
    022
    023    /**
    024     * An abstract base class for implementing the <a
    025     * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>.
    026     * The {@link #delegate()} method must be overridden to return the instance
    027     * being decorated.
    028     *
    029     * <p>This class does <i>not</i> forward the {@code hashCode} and {@code equals}
    030     * methods through to the backing object, but relies on {@code Object}'s
    031     * implementation. This is necessary to preserve the symmetry of {@code equals}.
    032     * Custom definitions of equality are usually based on an interface, such as
    033     * {@code Set} or {@code List}, so that the implementation of {@code equals} can
    034     * cast the object being tested for equality to the custom interface. {@code
    035     * ForwardingObject} implements no such custom interfaces directly; they
    036     * are implemented only in subclasses. Therefore, forwarding {@code equals}
    037     * would break symmetry, as the forwarding object might consider itself equal to
    038     * the object being tested, but the reverse could not be true. This behavior is
    039     * consistent with the JDK's collection wrappers, such as
    040     * {@link java.util.Collections#unmodifiableCollection}. Use an
    041     * interface-specific subclass of {@code ForwardingObject}, such as {@link
    042     * ForwardingList}, to preserve equality behavior, or override {@code equals}
    043     * directly.
    044     *
    045     * <p>The {@code toString} method is forwarded to the delegate. Although this
    046     * class does not implement {@link Serializable}, a serializable subclass may be
    047     * created since this class has a parameter-less constructor.
    048     *
    049     * @author Mike Bostock
    050     * @since 2.0 (imported from Google Collections Library)
    051     */
    052    @GwtCompatible
    053    public abstract class ForwardingObject {
    054
    055      /** Constructor for use by subclasses. */
    056      protected ForwardingObject() {}
    057
    058      /**
    059       * Returns the backing delegate instance that methods are forwarded to.
    060       * Abstract subclasses generally override this method with an abstract method
    061       * that has a more specific return type, such as {@link
    062       * ForwardingSet#delegate}. Concrete subclasses override this method to supply
    063       * the instance being decorated.
    064       */
    065      protected abstract Object delegate();
    066
    067      /**
    068       * Returns the string representation generated by the delegate's
    069       * {@code toString} method.
    070       */
    071      @Override public String toString() {
    072        return delegate().toString();
    073      }
    074
    075      /* No equals or hashCode. See class comments for details. */
    076    }