    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.list;
    018
    019import java.util.Collection;
    020import java.util.Iterator;
    021import java.util.List;
    022import java.util.ListIterator;
    023import java.util.function.Predicate;
    024
    025import org.apache.commons.collections4.Unmodifiable;
    026import org.apache.commons.collections4.iterators.UnmodifiableIterator;
    027import org.apache.commons.collections4.iterators.UnmodifiableListIterator;
    028
    029/**
    030 * Decorates another {@code List} to ensure it can't be altered.
    031 * <p>
    032 * This class is Serializable from Commons Collections 3.1.
    033 * </p>
    034 * <p>
    035 * Attempts to modify it will result in an UnsupportedOperationException.
    036 * </p>
    037 *
    038 * @param <E> The type of the elements in the list.
    039 * @since 3.0
    040 */
    041public final class UnmodifiableList<E>
    042        extends AbstractSerializableListDecorator<E>
    043        implements Unmodifiable {
    044
    045    /** Serialization version */
    046    private static final long serialVersionUID = 6595182819922443652L;
    047
    048    /**
    049     * Factory method to create an unmodifiable list.
    050     *
    051     * @param <E> The type of the elements in the list
    052     * @param list  The list to decorate, must not be null
    053     * @return A new unmodifiable list
    054     * @throws NullPointerException if list is null
    055     * @since 4.0
    056     */
    057    public static <E> List<E> unmodifiableList(final List<? extends E> list) {
    058        if (list instanceof Unmodifiable) {
    059            @SuppressWarnings("unchecked") // safe to upcast
    060            final List<E> tmpList = (List<E>) list;
    061            return tmpList;
    062        }
    063        return new UnmodifiableList<>(list);
    064    }
    065
    066    /**
    067     * Constructor that wraps (not copies).
    068     *
    069     * @param list  The list to decorate, must not be null
    070     * @throws NullPointerException if list is null
    071     */
    072    @SuppressWarnings("unchecked") // safe to upcast
    073    public UnmodifiableList(final List<? extends E> list) {
    074        super((List<E>) list);
    075    }
    076
    077    /**
    078     * Always throws {@link UnsupportedOperationException}.
    079     *
    080     * @param index Ignored.
    081     * @param object Ignored.
    082     * @throws UnsupportedOperationException Always thrown.
    083     */
    084    @Override
    085    public void add(final int index, final E object) {
    086        throw new UnsupportedOperationException();
    087    }
    088
    089    /**
    090     * Always throws {@link UnsupportedOperationException}.
    091     *
    092     * @param object Ignored.
    093     * @throws UnsupportedOperationException Always thrown.
    094     */
    095    @Override
    096    public boolean add(final Object object) {
    097        throw new UnsupportedOperationException();
    098    }
    099
    100    /**
    101     * Always throws {@link UnsupportedOperationException}.
    102     *
    103     * @param coll Ignored.
    104     * @throws UnsupportedOperationException Always thrown.
    105     */
    106    @Override
    107    public boolean addAll(final Collection<? extends E> coll) {
    108        throw new UnsupportedOperationException();
    109    }
    110
    111    /**
    112     * Always throws {@link UnsupportedOperationException}.
    113     *
    114     * @param index Ignored.
    115     * @param coll Ignored.
    116     * @throws UnsupportedOperationException Always thrown.
    117     */
    118    @Override
    119    public boolean addAll(final int index, final Collection<? extends E> coll) {
    120        throw new UnsupportedOperationException();
    121    }
    122
    123    /**
    124     * Always throws {@link UnsupportedOperationException}.
    125     *
    126     * @throws UnsupportedOperationException Always thrown.
    127     */
    128    @Override
    129    public void clear() {
    130        throw new UnsupportedOperationException();
    131    }
    132
    133    @Override
    134    public Iterator<E> iterator() {
    135        return UnmodifiableIterator.unmodifiableIterator(decorated().iterator());
    136    }
    137
    138    @Override
    139    public ListIterator<E> listIterator() {
    140        return UnmodifiableListIterator.unmodifiableListIterator(decorated().listIterator());
    141    }
    142
    143    @Override
    144    public ListIterator<E> listIterator(final int index) {
    145        return UnmodifiableListIterator.unmodifiableListIterator(decorated().listIterator(index));
    146    }
    147
    148    /**
    149     * Always throws {@link UnsupportedOperationException}.
    150     *
    151     * @param index Ignored.
    152     * @throws UnsupportedOperationException Always thrown.
    153     */
    154    @Override
    155    public E remove(final int index) {
    156        throw new UnsupportedOperationException();
    157    }
    158
    159    /**
    160     * Always throws {@link UnsupportedOperationException}.
    161     *
    162     * @param object Ignored.
    163     * @throws UnsupportedOperationException Always thrown.
    164     */
    165    @Override
    166    public boolean remove(final Object object) {
    167        throw new UnsupportedOperationException();
    168    }
    169
    170    /**
    171     * Always throws {@link UnsupportedOperationException}.
    172     *
    173     * @param coll Ignored.
    174     * @throws UnsupportedOperationException Always thrown.
    175     */
    176    @Override
    177    public boolean removeAll(final Collection<?> coll) {
    178        throw new UnsupportedOperationException();
    179    }
    180
    181    /**
    182     * Always throws {@link UnsupportedOperationException}.
    183     *
    184     * @param filter Ignored.
    185     * @throws UnsupportedOperationException Always thrown.
    186     * @since 4.4
    187     */
    188    @Override
    189    public boolean removeIf(final Predicate<? super E> filter) {
    190        throw new UnsupportedOperationException();
    191    }
    192
    193    /**
    194     * Always throws {@link UnsupportedOperationException}.
    195     *
    196     * @param coll Ignored.
    197     * @throws UnsupportedOperationException Always thrown.
    198     */
    199    @Override
    200    public boolean retainAll(final Collection<?> coll) {
    201        throw new UnsupportedOperationException();
    202    }
    203
    204    /**
    205     * Always throws {@link UnsupportedOperationException}.
    206     *
    207     * @param index Ignored.
    208     * @param object Ignored.
    209     * @throws UnsupportedOperationException Always thrown.
    210     */
    211    @Override
    212    public E set(final int index, final E object) {
    213        throw new UnsupportedOperationException();
    214    }
    215
    216    @Override
    217    public List<E> subList(final int fromIndex, final int toIndex) {
    218        return new UnmodifiableList<>(decorated().subList(fromIndex, toIndex));
    219    }
    220
    221}