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 017package com.google.common.collect; 018 019import com.google.common.annotations.GwtCompatible; 020import com.google.common.base.Objects; 021import com.google.errorprone.annotations.CanIgnoreReturnValue; 022import java.util.Collection; 023import java.util.Iterator; 024import org.checkerframework.checker.nullness.qual.Nullable; 025 026/** 027 * A collection which forwards all its method calls to another collection. Subclasses should 028 * override one or more methods to modify the behavior of the backing collection as desired per the 029 * <a href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>. 030 * 031 * <p><b>Warning:</b> The methods of {@code ForwardingCollection} forward <b>indiscriminately</b> to 032 * the methods of the delegate. For example, overriding {@link #add} alone <b>will not</b> change 033 * the behavior of {@link #addAll}, which can lead to unexpected behavior. In this case, you should 034 * override {@code addAll} as well, either providing your own implementation, or delegating to the 035 * provided {@code standardAddAll} method. 036 * 037 * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code 038 * default} methods. Instead, it inherits their default implementations. When those implementations 039 * invoke methods, they invoke methods on the {@code ForwardingCollection}. 040 * 041 * <p>The {@code standard} methods are not guaranteed to be thread-safe, even when all of the 042 * methods that they depend on are thread-safe. 043 * 044 * @author Kevin Bourrillion 045 * @author Louis Wasserman 046 * @since 2.0 047 */ 048@GwtCompatible 049public abstract class ForwardingCollection<E> extends ForwardingObject implements Collection<E> { 050 // TODO(lowasser): identify places where thread safety is actually lost 051 052 /** Constructor for use by subclasses. */ 053 protected ForwardingCollection() {} 054 055 @Override 056 protected abstract Collection<E> delegate(); 057 058 @Override 059 public Iterator<E> iterator() { 060 return delegate().iterator(); 061 } 062 063 @Override 064 public int size() { 065 return delegate().size(); 066 } 067 068 @CanIgnoreReturnValue 069 @Override 070 public boolean removeAll(Collection<?> collection) { 071 return delegate().removeAll(collection); 072 } 073 074 @Override 075 public boolean isEmpty() { 076 return delegate().isEmpty(); 077 } 078 079 @Override 080 public boolean contains(Object object) { 081 return delegate().contains(object); 082 } 083 084 @CanIgnoreReturnValue 085 @Override 086 public boolean add(E element) { 087 return delegate().add(element); 088 } 089 090 @CanIgnoreReturnValue 091 @Override 092 public boolean remove(Object object) { 093 return delegate().remove(object); 094 } 095 096 @Override 097 public boolean containsAll(Collection<?> collection) { 098 return delegate().containsAll(collection); 099 } 100 101 @CanIgnoreReturnValue 102 @Override 103 public boolean addAll(Collection<? extends E> collection) { 104 return delegate().addAll(collection); 105 } 106 107 @CanIgnoreReturnValue 108 @Override 109 public boolean retainAll(Collection<?> collection) { 110 return delegate().retainAll(collection); 111 } 112 113 @Override 114 public void clear() { 115 delegate().clear(); 116 } 117 118 @Override 119 public Object[] toArray() { 120 return delegate().toArray(); 121 } 122 123 @CanIgnoreReturnValue 124 @Override 125 public <T> T[] toArray(T[] array) { 126 return delegate().toArray(array); 127 } 128 129 /** 130 * A sensible definition of {@link #contains} in terms of {@link #iterator}. If you override 131 * {@link #iterator}, you may wish to override {@link #contains} to forward to this 132 * implementation. 133 * 134 * @since 7.0 135 */ 136 protected boolean standardContains(@Nullable Object object) { 137 return Iterators.contains(iterator(), object); 138 } 139 140 /** 141 * A sensible definition of {@link #containsAll} in terms of {@link #contains} . If you override 142 * {@link #contains}, you may wish to override {@link #containsAll} to forward to this 143 * implementation. 144 * 145 * @since 7.0 146 */ 147 protected boolean standardContainsAll(Collection<?> collection) { 148 return Collections2.containsAllImpl(this, collection); 149 } 150 151 /** 152 * A sensible definition of {@link #addAll} in terms of {@link #add}. If you override {@link 153 * #add}, you may wish to override {@link #addAll} to forward to this implementation. 154 * 155 * @since 7.0 156 */ 157 protected boolean standardAddAll(Collection<? extends E> collection) { 158 return Iterators.addAll(this, collection.iterator()); 159 } 160 161 /** 162 * A sensible definition of {@link #remove} in terms of {@link #iterator}, using the iterator's 163 * {@code remove} method. If you override {@link #iterator}, you may wish to override {@link 164 * #remove} to forward to this implementation. 165 * 166 * @since 7.0 167 */ 168 protected boolean standardRemove(@Nullable Object object) { 169 Iterator<E> iterator = iterator(); 170 while (iterator.hasNext()) { 171 if (Objects.equal(iterator.next(), object)) { 172 iterator.remove(); 173 return true; 174 } 175 } 176 return false; 177 } 178 179 /** 180 * A sensible definition of {@link #removeAll} in terms of {@link #iterator}, using the iterator's 181 * {@code remove} method. If you override {@link #iterator}, you may wish to override {@link 182 * #removeAll} to forward to this implementation. 183 * 184 * @since 7.0 185 */ 186 protected boolean standardRemoveAll(Collection<?> collection) { 187 return Iterators.removeAll(iterator(), collection); 188 } 189 190 /** 191 * A sensible definition of {@link #retainAll} in terms of {@link #iterator}, using the iterator's 192 * {@code remove} method. If you override {@link #iterator}, you may wish to override {@link 193 * #retainAll} to forward to this implementation. 194 * 195 * @since 7.0 196 */ 197 protected boolean standardRetainAll(Collection<?> collection) { 198 return Iterators.retainAll(iterator(), collection); 199 } 200 201 /** 202 * A sensible definition of {@link #clear} in terms of {@link #iterator}, using the iterator's 203 * {@code remove} method. If you override {@link #iterator}, you may wish to override {@link 204 * #clear} to forward to this implementation. 205 * 206 * @since 7.0 207 */ 208 protected void standardClear() { 209 Iterators.clear(iterator()); 210 } 211 212 /** 213 * A sensible definition of {@link #isEmpty} as {@code !iterator().hasNext}. If you override 214 * {@link #isEmpty}, you may wish to override {@link #isEmpty} to forward to this implementation. 215 * Alternately, it may be more efficient to implement {@code isEmpty} as {@code size() == 0}. 216 * 217 * @since 7.0 218 */ 219 protected boolean standardIsEmpty() { 220 return !iterator().hasNext(); 221 } 222 223 /** 224 * A sensible definition of {@link #toString} in terms of {@link #iterator}. If you override 225 * {@link #iterator}, you may wish to override {@link #toString} to forward to this 226 * implementation. 227 * 228 * @since 7.0 229 */ 230 protected String standardToString() { 231 return Collections2.toStringImpl(this); 232 } 233 234 /** 235 * A sensible definition of {@link #toArray()} in terms of {@link #toArray(Object[])}. If you 236 * override {@link #toArray(Object[])}, you may wish to override {@link #toArray} to forward to 237 * this implementation. 238 * 239 * @since 7.0 240 */ 241 protected Object[] standardToArray() { 242 Object[] newArray = new Object[size()]; 243 return toArray(newArray); 244 } 245 246 /** 247 * A sensible definition of {@link #toArray(Object[])} in terms of {@link #size} and {@link 248 * #iterator}. If you override either of these methods, you may wish to override {@link #toArray} 249 * to forward to this implementation. 250 * 251 * @since 7.0 252 */ 253 protected <T> T[] standardToArray(T[] array) { 254 return ObjectArrays.toArrayImpl(this, array); 255 } 256}