com.google.common.collect
Class ForwardingObject

java.lang.Object
  extended by com.google.common.collect.ForwardingObject
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
ForwardingCollection, ForwardingMap, ForwardingMultimap

public abstract class ForwardingObject
extends Object
implements Serializable

An abstract base class for implementing the decorator pattern. It is not strictly necessary to override any methods on this class, though typical implementations override delegate() to specify the correct return type, and add type-specific forwarding methods.

As a contrived example, to decorate an object to use the default implementation of toString(), you might say:

  return new ForwardingObject(object) {
      @Override public String toString() {
        return delegate().getClass().getName() + '@'
            + Integer.toHexString(hashCode());
      }
    };
This class does not forward the hashCode and equals methods through to the backing object, but relies on Object's implementation. This is necessary to preserve the symmetry of equals. Custom definitions of equality are usually based on an interface, such as Set or List, so that the implementation of equals can cast the object being tested for equality to the custom interface. ForwardingObject implements no such custom interfaces directly; they are implemented only in subclasses. Therefore, forwarding equals would break symmetry, as the forwarding object might consider itself equal to the object being tested, but the reverse could not be true. This behavior is consistent with the JDK's collection wrappers, such as Collections.unmodifiableCollection(java.util.Collection). Use an interface-specific subclass of ForwardingObject, such as ForwardingList, to preserve equality behavior, or override equals directly.

The toString method is forwarded to the delegate. Although this class implements Serializable, instances will be serializable only when the delegate is serializable.

Author:
Mike Bostock
See Also:
Serialized Form

Constructor Summary
protected ForwardingObject(Object delegate)
          Constructs a new object which forwards all methods to the specified delegate.
 
Method Summary
protected  Object delegate()
          Returns the backing delegate object.
 String toString()
          Returns the string representation generated by the delegate's toString method.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ForwardingObject

protected ForwardingObject(Object delegate)
Constructs a new object which forwards all methods to the specified delegate.

Parameters:
delegate - the backing object to which methods are forwarded.
Throws:
NullPointerException - if delegate is null.
Method Detail

delegate

protected Object delegate()
Returns the backing delegate object. This method should be overridden to specify the correct return type. For example:
  @SuppressWarnings("unchecked")
  @Override protected Foo delegate() {
    return (Foo) super.delegate();
  }
This method should always return the same delegate instance that was passed to the constructor.


toString

public String toString()
Returns the string representation generated by the delegate's toString method.

Overrides:
toString in class Object