001 /*
002 * Copyright (C) 2008 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
017 package com.google.common.collect;
018
019 import com.google.common.annotations.GwtCompatible;
020
021 import java.io.Serializable;
022 import java.util.Collection;
023 import java.util.Iterator;
024
025 import javax.annotation.Nullable;
026
027 /**
028 * An immutable collection. Does not permit null elements.
029 *
030 * <p>In addition to the {@link Collection} methods, this class has an {@link
031 * #asList()} method, which returns a list view of the collection's elements.
032 *
033 * <p><b>Note:</b> Although this class is not final, it cannot be subclassed
034 * outside of this package as it has no public or protected constructors. Thus,
035 * instances of this type are guaranteed to be immutable.
036 *
037 * @author Jesse Wilson
038 * @since 2.0 (imported from Google Collections Library)
039 */
040 @GwtCompatible(emulated = true)
041 @SuppressWarnings("serial") // we're overriding default serialization
042 public abstract class ImmutableCollection<E>
043 implements Collection<E>, Serializable {
044 static final ImmutableCollection<Object> EMPTY_IMMUTABLE_COLLECTION
045 = new EmptyImmutableCollection();
046
047 ImmutableCollection() {}
048
049 /**
050 * Returns an unmodifiable iterator across the elements in this collection.
051 */
052 @Override
053 public abstract UnmodifiableIterator<E> iterator();
054
055 @Override
056 public Object[] toArray() {
057 return ObjectArrays.toArrayImpl(this);
058 }
059
060 @Override
061 public <T> T[] toArray(T[] other) {
062 return ObjectArrays.toArrayImpl(this, other);
063 }
064
065 @Override
066 public boolean contains(@Nullable Object object) {
067 return object != null && Iterators.contains(iterator(), object);
068 }
069
070 @Override
071 public boolean containsAll(Collection<?> targets) {
072 return Collections2.containsAllImpl(this, targets);
073 }
074
075 @Override
076 public boolean isEmpty() {
077 return size() == 0;
078 }
079
080 @Override public String toString() {
081 return Collections2.toStringImpl(this);
082 }
083
084 /**
085 * Guaranteed to throw an exception and leave the collection unmodified.
086 *
087 * @throws UnsupportedOperationException always
088 */
089 @Override
090 public final boolean add(E e) {
091 throw new UnsupportedOperationException();
092 }
093
094 /**
095 * Guaranteed to throw an exception and leave the collection unmodified.
096 *
097 * @throws UnsupportedOperationException always
098 */
099 @Override
100 public final boolean remove(Object object) {
101 throw new UnsupportedOperationException();
102 }
103
104 /**
105 * Guaranteed to throw an exception and leave the collection unmodified.
106 *
107 * @throws UnsupportedOperationException always
108 */
109 @Override
110 public final boolean addAll(Collection<? extends E> newElements) {
111 throw new UnsupportedOperationException();
112 }
113
114 /**
115 * Guaranteed to throw an exception and leave the collection unmodified.
116 *
117 * @throws UnsupportedOperationException always
118 */
119 @Override
120 public final boolean removeAll(Collection<?> oldElements) {
121 throw new UnsupportedOperationException();
122 }
123
124 /**
125 * Guaranteed to throw an exception and leave the collection unmodified.
126 *
127 * @throws UnsupportedOperationException always
128 */
129 @Override
130 public final boolean retainAll(Collection<?> elementsToKeep) {
131 throw new UnsupportedOperationException();
132 }
133
134 /**
135 * Guaranteed to throw an exception and leave the collection unmodified.
136 *
137 * @throws UnsupportedOperationException always
138 */
139 @Override
140 public final void clear() {
141 throw new UnsupportedOperationException();
142 }
143
144 /*
145 * TODO(kevinb): Restructure code so ImmutableList doesn't contain this
146 * variable, which it doesn't use.
147 */
148 private transient ImmutableList<E> asList;
149
150 /**
151 * Returns a list view of the collection.
152 *
153 * @since 2.0
154 */
155 public ImmutableList<E> asList() {
156 ImmutableList<E> list = asList;
157 return (list == null) ? (asList = createAsList()) : list;
158 }
159
160 ImmutableList<E> createAsList() {
161 switch (size()) {
162 case 0:
163 return ImmutableList.of();
164 case 1:
165 return ImmutableList.of(iterator().next());
166 default:
167 return new ImmutableAsList<E>(toArray(), this);
168 }
169 }
170
171 abstract boolean isPartialView();
172
173 private static class EmptyImmutableCollection
174 extends ImmutableCollection<Object> {
175 @Override
176 public int size() {
177 return 0;
178 }
179
180 @Override public boolean isEmpty() {
181 return true;
182 }
183
184 @Override public boolean contains(@Nullable Object object) {
185 return false;
186 }
187
188 @Override public UnmodifiableIterator<Object> iterator() {
189 return Iterators.EMPTY_ITERATOR;
190 }
191
192 private static final Object[] EMPTY_ARRAY = new Object[0];
193
194 @Override public Object[] toArray() {
195 return EMPTY_ARRAY;
196 }
197
198 @Override public <T> T[] toArray(T[] array) {
199 if (array.length > 0) {
200 array[0] = null;
201 }
202 return array;
203 }
204
205 @Override ImmutableList<Object> createAsList() {
206 return ImmutableList.of();
207 }
208
209 @Override boolean isPartialView() {
210 return false;
211 }
212 }
213
214 /**
215 * Nonempty collection stored in an array.
216 */
217 private static class ArrayImmutableCollection<E>
218 extends ImmutableCollection<E> {
219 private final E[] elements;
220
221 ArrayImmutableCollection(E[] elements) {
222 this.elements = elements;
223 }
224
225 @Override
226 public int size() {
227 return elements.length;
228 }
229
230 @Override public boolean isEmpty() {
231 return false;
232 }
233
234 @Override public UnmodifiableIterator<E> iterator() {
235 return Iterators.forArray(elements);
236 }
237
238 @Override ImmutableList<E> createAsList() {
239 return elements.length == 1 ? new SingletonImmutableList<E>(elements[0])
240 : new RegularImmutableList<E>(elements);
241 }
242
243 @Override boolean isPartialView() {
244 return false;
245 }
246 }
247
248 /*
249 * Serializes ImmutableCollections as their logical contents. This ensures
250 * that implementation types do not leak into the serialized representation.
251 */
252 private static class SerializedForm implements Serializable {
253 final Object[] elements;
254 SerializedForm(Object[] elements) {
255 this.elements = elements;
256 }
257 Object readResolve() {
258 return elements.length == 0
259 ? EMPTY_IMMUTABLE_COLLECTION
260 : new ArrayImmutableCollection<Object>(Platform.clone(elements));
261 }
262 private static final long serialVersionUID = 0;
263 }
264
265 Object writeReplace() {
266 return new SerializedForm(toArray());
267 }
268
269 /**
270 * Abstract base class for builders of {@link ImmutableCollection} types.
271 *
272 * @since 10.0
273 */
274 public abstract static class Builder<E> {
275
276 Builder() {
277 }
278
279 /**
280 * Adds {@code element} to the {@code ImmutableCollection} being built.
281 *
282 * <p>Note that each builder class covariantly returns its own type from
283 * this method.
284 *
285 * @param element the element to add
286 * @return this {@code Builder} instance
287 * @throws NullPointerException if {@code element} is null
288 */
289 public abstract Builder<E> add(E element);
290
291 /**
292 * Adds each element of {@code elements} to the {@code ImmutableCollection}
293 * being built.
294 *
295 * <p>Note that each builder class overrides this method in order to
296 * covariantly return its own type.
297 *
298 * @param elements the elements to add
299 * @return this {@code Builder} instance
300 * @throws NullPointerException if {@code elements} is null or contains a
301 * null element
302 */
303 public Builder<E> add(E... elements) {
304 for (E element : elements) {
305 add(element);
306 }
307 return this;
308 }
309
310 /**
311 * Adds each element of {@code elements} to the {@code ImmutableCollection}
312 * being built.
313 *
314 * <p>Note that each builder class overrides this method in order to
315 * covariantly return its own type.
316 *
317 * @param elements the elements to add
318 * @return this {@code Builder} instance
319 * @throws NullPointerException if {@code elements} is null or contains a
320 * null element
321 */
322 public Builder<E> addAll(Iterable<? extends E> elements) {
323 for (E element : elements) {
324 add(element);
325 }
326 return this;
327 }
328
329 /**
330 * Adds each element of {@code elements} to the {@code ImmutableCollection}
331 * being built.
332 *
333 * <p>Note that each builder class overrides this method in order to
334 * covariantly return its own type.
335 *
336 * @param elements the elements to add
337 * @return this {@code Builder} instance
338 * @throws NullPointerException if {@code elements} is null or contains a
339 * null element
340 */
341 public Builder<E> addAll(Iterator<? extends E> elements) {
342 while (elements.hasNext()) {
343 add(elements.next());
344 }
345 return this;
346 }
347
348 /**
349 * Returns a newly-created {@code ImmutableCollection} of the appropriate
350 * type, containing the elements provided to this builder.
351 *
352 * <p>Note that each builder class covariantly returns the appropriate type
353 * of {@code ImmutableCollection} from this method.
354 */
355 public abstract ImmutableCollection<E> build();
356 }
357 }