1 /* 2 * Copyright (C) 2007 Google Inc. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.google.common.collect; 18 19 import com.google.common.annotations.GwtCompatible; 20 21 import java.io.Serializable; 22 23 /** 24 * An abstract base class for implementing the <a 25 * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>. 26 * The {@link #delegate()} method must be overridden to return the instance 27 * being decorated. 28 * 29 * This class does <i>not</i> forward the {@code hashCode} and {@code equals} 30 * methods through to the backing object, but relies on {@code Object}'s 31 * implementation. This is necessary to preserve the symmetry of {@code equals}. 32 * Custom definitions of equality are usually based on an interface, such as 33 * {@code Set} or {@code List}, so that the implementation of {@code equals} can 34 * cast the object being tested for equality to the custom interface. {@code 35 * ForwardingObject} implements no such custom interfaces directly; they 36 * are implemented only in subclasses. Therefore, forwarding {@code equals} 37 * would break symmetry, as the forwarding object might consider itself equal to 38 * the object being tested, but the reverse could not be true. This behavior is 39 * consistent with the JDK's collection wrappers, such as 40 * {@link java.util.Collections#unmodifiableCollection}. Use an 41 * interface-specific subclass of {@code ForwardingObject}, such as {@link 42 * ForwardingList}, to preserve equality behavior, or override {@code equals} 43 * directly. 44 * 45 * <p>The {@code toString} method is forwarded to the delegate. Although this 46 * class does not implement {@link Serializable}, a serializable subclass may be 47 * created since this class has a parameter-less constructor. 48 * 49 * @author Mike Bostock 50 * @since 2010.01.04 <b>stable</b> (imported from Google Collections Library) 51 */ 52 @GwtCompatible 53 public abstract class ForwardingObject { 54 55 /** Sole constructor. */ ForwardingObject()56 protected ForwardingObject() {} 57 58 /** 59 * Returns the backing delegate instance that methods are forwarded to. 60 * Abstract subclasses generally override this method with an abstract method 61 * that has a more specific return type, such as {@link 62 * ForwardingSet#delegate}. Concrete subclasses override this method to supply 63 * the instance being decorated. 64 */ delegate()65 protected abstract Object delegate(); 66 67 /** 68 * Returns the string representation generated by the delegate's 69 * {@code toString} method. 70 */ toString()71 @Override public String toString() { 72 return delegate().toString(); 73 } 74 75 /* No equals or hashCode. See class comments for details. */ 76 } 77