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