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.multiset;
018
019import java.io.IOException;
020import java.io.ObjectInputStream;
021import java.io.ObjectOutputStream;
022import java.util.Collection;
023import java.util.Iterator;
024import java.util.Set;
025import java.util.function.Predicate;
026
027import org.apache.commons.collections4.MultiSet;
028import org.apache.commons.collections4.Unmodifiable;
029import org.apache.commons.collections4.iterators.UnmodifiableIterator;
030import org.apache.commons.collections4.set.UnmodifiableSet;
031
032/**
033 * Decorates another {@link MultiSet} to ensure it can't be altered.
034 * <p>
035 * Attempts to modify it will result in an UnsupportedOperationException.
036 * </p>
037 *
038 * @param <E> The type held in the multiset
039 * @since 4.1
040 */
041public final class UnmodifiableMultiSet<E>
042        extends AbstractMultiSetDecorator<E> implements Unmodifiable {
043
044    /** Serialization version */
045    private static final long serialVersionUID = 20150611L;
046
047    /**
048     * Factory method to create an unmodifiable multiset.
049     * <p>
050     * If the multiset passed in is already unmodifiable, it is returned.
051     * </p>
052     *
053     * @param <E>  the type of the elements in the multiset
054     * @param multiset  The multiset to decorate, may not be null
055     * @return An unmodifiable MultiSet
056     * @throws NullPointerException if multiset is null
057     */
058    public static <E> MultiSet<E> unmodifiableMultiSet(final MultiSet<? extends E> multiset) {
059        if (multiset instanceof Unmodifiable) {
060            @SuppressWarnings("unchecked") // safe to upcast
061            final MultiSet<E> tmpMultiSet = (MultiSet<E>) multiset;
062            return tmpMultiSet;
063        }
064        return new UnmodifiableMultiSet<>(multiset);
065    }
066
067    /**
068     * Constructor that wraps (not copies).
069     *
070     * @param multiset  The multiset to decorate, may not be null
071     * @throws NullPointerException if multiset is null
072     */
073    @SuppressWarnings("unchecked") // safe to upcast
074    private UnmodifiableMultiSet(final MultiSet<? extends E> multiset) {
075        super((MultiSet<E>) multiset);
076    }
077
078    /**
079     * Always throws {@link UnsupportedOperationException}.
080     *
081     * @param object Ignored.
082     * @throws UnsupportedOperationException Always thrown.
083     */
084    @Override
085    public boolean add(final E object) {
086        throw new UnsupportedOperationException();
087    }
088
089    /**
090     * Always throws {@link UnsupportedOperationException}.
091     *
092     * @param object Ignored.
093     * @param count Ignored.
094     * @throws UnsupportedOperationException Always thrown.
095     */
096    @Override
097    public int add(final E object, final int count) {
098        throw new UnsupportedOperationException();
099    }
100
101    /**
102     * Always throws {@link UnsupportedOperationException}.
103     *
104     * @param coll Ignored.
105     * @throws UnsupportedOperationException Always thrown.
106     */
107    @Override
108    public boolean addAll(final Collection<? extends E> coll) {
109        throw new UnsupportedOperationException();
110    }
111
112    /**
113     * Always throws {@link UnsupportedOperationException}.
114     *
115     * @throws UnsupportedOperationException Always thrown.
116     */
117    @Override
118    public void clear() {
119        throw new UnsupportedOperationException();
120    }
121
122    @Override
123    public Set<MultiSet.Entry<E>> entrySet() {
124        return UnmodifiableSet.unmodifiableSet(decorated().entrySet());
125    }
126
127    @Override
128    public Iterator<E> iterator() {
129        return UnmodifiableIterator.<E>unmodifiableIterator(decorated().iterator());
130    }
131
132    /**
133     * Deserializes the collection in using a custom routine.
134     *
135     * @param in  The input stream
136     * @throws IOException Thrown if an error occurs while reading from the stream
137     * @throws ClassNotFoundException if an object read from the stream cannot be loaded
138     * @throws ClassCastException if deserialized object has wrong type
139     */
140    @SuppressWarnings("unchecked") // will throw CCE, see Javadoc
141    private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
142        in.defaultReadObject();
143        setCollection((Collection<E>) in.readObject());
144    }
145
146    /**
147     * Always throws {@link UnsupportedOperationException}.
148     *
149     * @param object Ignored.
150     * @throws UnsupportedOperationException Always thrown.
151     */
152    @Override
153    public boolean remove(final Object object) {
154        throw new UnsupportedOperationException();
155    }
156
157    /**
158     * Always throws {@link UnsupportedOperationException}.
159     *
160     * @param object Ignored.
161     * @param count Ignored.
162     * @throws UnsupportedOperationException Always thrown.
163     */
164    @Override
165    public int remove(final Object object, final int count) {
166        throw new UnsupportedOperationException();
167    }
168
169    /**
170     * Always throws {@link UnsupportedOperationException}.
171     *
172     * @param coll Ignored.
173     * @throws UnsupportedOperationException Always thrown.
174     */
175    @Override
176    public boolean removeAll(final Collection<?> coll) {
177        throw new UnsupportedOperationException();
178    }
179
180    /**
181     * Always throws {@link UnsupportedOperationException}.
182     *
183     * @param filter Ignored.
184     * @throws UnsupportedOperationException Always thrown.
185     * @since 4.4
186     */
187    @Override
188    public boolean removeIf(final Predicate<? super E> filter) {
189        throw new UnsupportedOperationException();
190    }
191
192    /**
193     * Always throws {@link UnsupportedOperationException}.
194     *
195     * @param coll Ignored.
196     * @throws UnsupportedOperationException Always thrown.
197     */
198    @Override
199    public boolean retainAll(final Collection<?> coll) {
200        throw new UnsupportedOperationException();
201    }
202
203    /**
204     * Always throws {@link UnsupportedOperationException}.
205     *
206     * @param object Ignored.
207     * @param count Ignored.
208     * @throws UnsupportedOperationException Always thrown.
209     */
210    @Override
211    public int setCount(final E object, final int count) {
212        throw new UnsupportedOperationException();
213    }
214
215    @Override
216    public Set<E> uniqueSet() {
217        return UnmodifiableSet.unmodifiableSet(decorated().uniqueSet());
218    }
219
220    /**
221     * Serializes this object to an ObjectOutputStream.
222     *
223     * @param out The target ObjectOutputStream.
224     * @throws IOException thrown when an I/O errors occur writing to the target stream.
225     */
226    private void writeObject(final ObjectOutputStream out) throws IOException {
227        out.defaultWriteObject();
228        out.writeObject(decorated());
229    }
230
231}