1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.collections4.collection;
18
19 import java.util.Collection;
20 import java.util.Iterator;
21 import java.util.function.Predicate;
22
23 import org.apache.commons.collections4.Unmodifiable;
24 import org.apache.commons.collections4.iterators.UnmodifiableIterator;
25
26 /**
27 * Decorates another {@link Collection} to ensure it can't be altered.
28 * <p>
29 * This class is Serializable from Commons Collections 3.1.
30 * </p>
31 * <p>
32 * Attempts to modify it will result in an UnsupportedOperationException.
33 * </p>
34 *
35 * @param <E> The type of the elements in the collection.
36 * @since 3.0
37 */
38 public final class UnmodifiableCollection<E>
39 extends AbstractCollectionDecorator<E>
40 implements Unmodifiable {
41
42 /** Serialization version */
43 private static final long serialVersionUID = -239892006883819945L;
44
45 /**
46 * Creates an unmodifiable collection.
47 * <p>
48 * If the collection passed in is already unmodifiable, it is returned.
49 * </p>
50 *
51 * @param <T> The type of the elements in the collection.
52 * @param coll The collection to decorate, must not be null.
53 * @return An unmodifiable collection.
54 * @throws NullPointerException if collection is null.
55 * @since 4.0
56 */
57 public static <T> Collection<T> unmodifiableCollection(final Collection<? extends T> coll) {
58 if (coll instanceof Unmodifiable) {
59 @SuppressWarnings("unchecked") // safe to upcast
60 final Collection<T> tmpColl = (Collection<T>) coll;
61 return tmpColl;
62 }
63 return new UnmodifiableCollection<>(coll);
64 }
65
66 /**
67 * Constructs and wraps (not copies).
68 *
69 * @param coll The collection to decorate, must not be null.
70 * @throws NullPointerException if collection is null.
71 */
72 @SuppressWarnings("unchecked") // safe to upcast
73 private UnmodifiableCollection(final Collection<? extends E> coll) {
74 super((Collection<E>) coll);
75 }
76
77 /**
78 * Always throws {@link UnsupportedOperationException}.
79 *
80 * @param object Ignored.
81 * @throws UnsupportedOperationException Always thrown.
82 */
83 @Override
84 public boolean add(final E object) {
85 throw new UnsupportedOperationException();
86 }
87
88 /**
89 * Always throws {@link UnsupportedOperationException}.
90 *
91 * @throws UnsupportedOperationException Always thrown.
92 */
93 @Override
94 public boolean addAll(final Collection<? extends E> coll) {
95 throw new UnsupportedOperationException();
96 }
97
98 /**
99 * Always throws {@link UnsupportedOperationException}.
100 *
101 * @throws UnsupportedOperationException Always thrown.
102 */
103 @Override
104 public void clear() {
105 throw new UnsupportedOperationException();
106 }
107
108 @Override
109 public Iterator<E> iterator() {
110 return UnmodifiableIterator.unmodifiableIterator(decorated().iterator());
111 }
112
113 /**
114 * Always throws {@link UnsupportedOperationException}.
115 *
116 * @param object Ignored.
117 * @throws UnsupportedOperationException Always thrown.
118 */
119 @Override
120 public boolean remove(final Object object) {
121 throw new UnsupportedOperationException();
122 }
123
124 /**
125 * Always throws {@link UnsupportedOperationException}.
126 *
127 * @param coll Ignored.
128 * @throws UnsupportedOperationException Always thrown.
129 */
130 @Override
131 public boolean removeAll(final Collection<?> coll) {
132 throw new UnsupportedOperationException();
133 }
134
135 /**
136 * Always throws {@link UnsupportedOperationException}.
137 *
138 * @param filter Ignored.
139 * @throws UnsupportedOperationException Always thrown.
140 * @since 4.4
141 */
142 @Override
143 public boolean removeIf(final Predicate<? super E> filter) {
144 throw new UnsupportedOperationException();
145 }
146
147 /**
148 * Always throws {@link UnsupportedOperationException}.
149 *
150 * @param coll Ignored.
151 * @throws UnsupportedOperationException Always thrown.
152 */
153 @Override
154 public boolean retainAll(final Collection<?> coll) {
155 throw new UnsupportedOperationException();
156 }
157
158 }