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 *      http://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.queue;
018
019import java.io.IOException;
020import java.io.ObjectInputStream;
021import java.io.ObjectOutputStream;
022import java.util.Collection;
023import java.util.Iterator;
024import java.util.Queue;
025
026import org.apache.commons.collections4.Unmodifiable;
027import org.apache.commons.collections4.iterators.UnmodifiableIterator;
028
029/**
030 * Decorates another {@link Queue} to ensure it can't be altered.
031 * <p>
032 * Attempts to modify it will result in an UnsupportedOperationException.
033 *
034 * @param <E> the type of elements held in this queue
035 * @since 4.0
036 */
037public final class UnmodifiableQueue<E>
038        extends AbstractQueueDecorator<E>
039        implements Unmodifiable {
040
041    /** Serialization version */
042    private static final long serialVersionUID = 1832948656215393357L;
043
044    /**
045     * Factory method to create an unmodifiable queue.
046     * <p>
047     * If the queue passed in is already unmodifiable, it is returned.
048     *
049     * @param <E> the type of the elements in the queue
050     * @param queue  the queue to decorate, must not be null
051     * @return an unmodifiable Queue
052     * @throws NullPointerException if queue is null
053     */
054    public static <E> Queue<E> unmodifiableQueue(final Queue<? extends E> queue) {
055        if (queue instanceof Unmodifiable) {
056            @SuppressWarnings("unchecked") // safe to upcast
057            final Queue<E> tmpQueue = (Queue<E>) queue;
058            return tmpQueue;
059        }
060        return new UnmodifiableQueue<>(queue);
061    }
062
063    //-----------------------------------------------------------------------
064    /**
065     * Constructor that wraps (not copies).
066     *
067     * @param queue  the queue to decorate, must not be null
068     * @throws NullPointerException if queue is null
069     */
070    @SuppressWarnings("unchecked") // safe to upcast
071    private UnmodifiableQueue(final Queue<? extends E> queue) {
072        super((Queue<E>) queue);
073    }
074
075    //-----------------------------------------------------------------------
076    /**
077     * Write the collection out using a custom routine.
078     *
079     * @param out  the output stream
080     * @throws IOException if an I/O error occurs while writing to the output stream
081     */
082    private void writeObject(final ObjectOutputStream out) throws IOException {
083        out.defaultWriteObject();
084        out.writeObject(decorated());
085    }
086
087    /**
088     * Read the collection in using a custom routine.
089     *
090     * @param in  the input stream
091     * @throws IOException if an I/O error occurs while reading from the input stream
092     * @throws ClassNotFoundException if the class of a serialized object can not be found
093     */
094    @SuppressWarnings("unchecked")
095    private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
096        in.defaultReadObject();
097        setCollection((Collection<E>) in.readObject());
098    }
099
100    //-----------------------------------------------------------------------
101    @Override
102    public Iterator<E> iterator() {
103        return UnmodifiableIterator.unmodifiableIterator(decorated().iterator());
104    }
105
106    @Override
107    public boolean add(final Object object) {
108        throw new UnsupportedOperationException();
109    }
110
111    @Override
112    public boolean addAll(final Collection<? extends E> coll) {
113        throw new UnsupportedOperationException();
114    }
115
116    @Override
117    public void clear() {
118        throw new UnsupportedOperationException();
119    }
120
121    @Override
122    public boolean remove(final Object object) {
123        throw new UnsupportedOperationException();
124    }
125
126    @Override
127    public boolean removeAll(final Collection<?> coll) {
128        throw new UnsupportedOperationException();
129    }
130
131    @Override
132    public boolean retainAll(final Collection<?> coll) {
133        throw new UnsupportedOperationException();
134    }
135
136    //-----------------------------------------------------------------------
137
138    @Override
139    public boolean offer(final E obj) {
140        throw new UnsupportedOperationException();
141    }
142
143    @Override
144    public E poll() {
145        throw new UnsupportedOperationException();
146    }
147
148    @Override
149    public E remove() {
150        throw new UnsupportedOperationException();
151    }
152
153}