001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      https://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.collections4.set;
018
019import java.util.Collection;
020import java.util.Iterator;
021import java.util.Set;
022import java.util.function.Predicate;
023
024import org.apache.commons.collections4.Unmodifiable;
025import org.apache.commons.collections4.iterators.UnmodifiableIterator;
026
027/**
028 * Decorates another {@code Set} to ensure it can't be altered.
029 * <p>
030 * This class is Serializable from Commons Collections 3.1.
031 * </p>
032 * <p>
033 * Attempts to modify it will result in an UnsupportedOperationException.
034 * </p>
035 *
036 * @param <E> The type of the elements in this set
037 * @since 3.0
038 */
039public final class UnmodifiableSet<E>
040        extends AbstractSerializableSetDecorator<E>
041        implements Unmodifiable {
042
043    /** Serialization version */
044    private static final long serialVersionUID = 6499119872185240161L;
045
046    /**
047     * Factory method to create an unmodifiable set.
048     *
049     * @param <E> The element type
050     * @param set  The set to decorate, must not be null
051     * @return A new unmodifiable set
052     * @throws NullPointerException if set is null
053     * @since 4.0
054     */
055    public static <E> Set<E> unmodifiableSet(final Set<? extends E> set) {
056        if (set instanceof Unmodifiable) {
057            @SuppressWarnings("unchecked") // safe to upcast
058            final Set<E> tmpSet = (Set<E>) set;
059            return tmpSet;
060        }
061        return new UnmodifiableSet<>(set);
062    }
063
064    /**
065     * Constructor that wraps (not copies).
066     *
067     * @param set  The set to decorate, must not be null
068     * @throws NullPointerException if set is null
069     */
070    @SuppressWarnings("unchecked") // safe to upcast
071    private UnmodifiableSet(final Set<? extends E> set) {
072        super((Set<E>) set);
073    }
074
075    /**
076     * Always throws {@link UnsupportedOperationException}.
077     *
078     * @param object Ignored.
079     * @throws UnsupportedOperationException Always thrown.
080     */
081    @Override
082    public boolean add(final E object) {
083        throw new UnsupportedOperationException();
084    }
085
086    /**
087     * Always throws {@link UnsupportedOperationException}.
088     *
089     * @param coll Ignored.
090     * @throws UnsupportedOperationException Always thrown.
091     */
092    @Override
093    public boolean addAll(final Collection<? extends E> coll) {
094        throw new UnsupportedOperationException();
095    }
096
097    /**
098     * Always throws {@link UnsupportedOperationException}.
099     *
100     * @throws UnsupportedOperationException Always thrown.
101     */
102    @Override
103    public void clear() {
104        throw new UnsupportedOperationException();
105    }
106
107    @Override
108    public Iterator<E> iterator() {
109        return UnmodifiableIterator.unmodifiableIterator(decorated().iterator());
110    }
111
112    /**
113     * Always throws {@link UnsupportedOperationException}.
114     *
115     * @param object Ignored.
116     * @throws UnsupportedOperationException Always thrown.
117     */
118    @Override
119    public boolean remove(final Object object) {
120        throw new UnsupportedOperationException();
121    }
122
123    /**
124     * Always throws {@link UnsupportedOperationException}.
125     *
126     * @param coll Ignored.
127     * @throws UnsupportedOperationException Always thrown.
128     */
129    @Override
130    public boolean removeAll(final Collection<?> coll) {
131        throw new UnsupportedOperationException();
132    }
133
134    /**
135     * Always throws {@link UnsupportedOperationException}.
136     *
137     * @param filter Ignored.
138     * @throws UnsupportedOperationException Always thrown.
139     * @since 4.4
140     */
141    @Override
142    public boolean removeIf(final Predicate<? super E> filter) {
143        throw new UnsupportedOperationException();
144    }
145
146    /**
147     * Always throws {@link UnsupportedOperationException}.
148     *
149     * @param coll Ignored.
150     * @throws UnsupportedOperationException Always thrown.
151     */
152    @Override
153    public boolean retainAll(final Collection<?> coll) {
154        throw new UnsupportedOperationException();
155    }
156
157}