1090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson/* 2090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Copyright (C) 2007 Google Inc. 3090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 4090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Licensed under the Apache License, Version 2.0 (the "License"); 5090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * you may not use this file except in compliance with the License. 6090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * You may obtain a copy of the License at 7090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 8090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * http://www.apache.org/licenses/LICENSE-2.0 9090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 10090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Unless required by applicable law or agreed to in writing, software 11090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * distributed under the License is distributed on an "AS IS" BASIS, 12090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * See the License for the specific language governing permissions and 14090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * limitations under the License. 15090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 16090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 17090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonpackage com.google.common.collect; 18090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 19090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport com.google.common.annotations.GwtCompatible; 20090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 21090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport java.io.Serializable; 22090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 23090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson/** 24090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * An abstract base class for implementing the <a 25090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>. 26090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * The {@link #delegate()} method must be overridden to return the instance 27090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * being decorated. 28090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 29090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * This class does <i>not</i> forward the {@code hashCode} and {@code equals} 30090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * methods through to the backing object, but relies on {@code Object}'s 31090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * implementation. This is necessary to preserve the symmetry of {@code equals}. 32090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Custom definitions of equality are usually based on an interface, such as 33090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * {@code Set} or {@code List}, so that the implementation of {@code equals} can 34090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * cast the object being tested for equality to the custom interface. {@code 35090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * ForwardingObject} implements no such custom interfaces directly; they 36090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * are implemented only in subclasses. Therefore, forwarding {@code equals} 37090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * would break symmetry, as the forwarding object might consider itself equal to 38090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * the object being tested, but the reverse could not be true. This behavior is 39090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * consistent with the JDK's collection wrappers, such as 40090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * {@link java.util.Collections#unmodifiableCollection}. Use an 41090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * interface-specific subclass of {@code ForwardingObject}, such as {@link 42090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * ForwardingList}, to preserve equality behavior, or override {@code equals} 43090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * directly. 44090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 45090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p>The {@code toString} method is forwarded to the delegate. Although this 46090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * class does not implement {@link Serializable}, a serializable subclass may be 47090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * created since this class has a parameter-less constructor. 48090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 49090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @author Mike Bostock 50bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @since 2010.01.04 <b>stable</b> (imported from Google Collections Library) 51090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 52090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson@GwtCompatible 53090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonpublic abstract class ForwardingObject { 54090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 55090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** Sole constructor. */ 56090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson protected ForwardingObject() {} 57090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 58090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 59090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Returns the backing delegate instance that methods are forwarded to. 60090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Abstract subclasses generally override this method with an abstract method 61090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * that has a more specific return type, such as {@link 62090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * ForwardingSet#delegate}. Concrete subclasses override this method to supply 63090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * the instance being decorated. 64090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 65090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson protected abstract Object delegate(); 66090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 67090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 68090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Returns the string representation generated by the delegate's 69090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * {@code toString} method. 70090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 71090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson @Override public String toString() { 72090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return delegate().toString(); 73090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 74090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 75090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /* No equals or hashCode. See class comments for details. */ 76090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson} 77