    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.list;
    018
    019import java.util.Collection;
    020import java.util.List;
    021import java.util.ListIterator;
    022
    023import org.apache.commons.collections4.Predicate;
    024import org.apache.commons.collections4.collection.PredicatedCollection;
    025import org.apache.commons.collections4.iterators.AbstractListIteratorDecorator;
    026
    027/**
    028 * Decorates another {@code List} to validate that all additions
    029 * match a specified predicate.
    030 * <p>
    031 * This list exists to provide validation for the decorated list.
    032 * It is normally created to decorate an empty list.
    033 * If an object cannot be added to the list, an IllegalArgumentException is thrown.
    034 * </p>
    035 * <p>
    036 * One usage would be to ensure that no null entries are added to the list.
    037 * </p>
    038 * <pre>
    039 * {@code
    040 * List<String> list =
    041 *   PredicatedList.predicatedList(new ArrayList<String>(), PredicateUtils.notNullPredicate());
    042 * }
    043 * </pre>
    044 * <p>
    045 * This class is Serializable from Commons Collections 3.1.
    046 * </p>
    047 *
    048 * @since 3.0
    049 */
    050public class PredicatedList<E> extends PredicatedCollection<E> implements List<E> {
    051
    052    /**
    053     * Inner class Iterator for the PredicatedList
    054     */
    055    protected class PredicatedListIterator extends AbstractListIteratorDecorator<E> {
    056
    057        /**
    058         * Create a new predicated list iterator.
    059         *
    060         * @param iterator  the list iterator to decorate
    061         */
    062        protected PredicatedListIterator(final ListIterator<E> iterator) {
    063            super(iterator);
    064        }
    065
    066        @Override
    067        public void add(final E object) {
    068            validate(object);
    069            getListIterator().add(object);
    070        }
    071
    072        @Override
    073        public void set(final E object) {
    074            validate(object);
    075            getListIterator().set(object);
    076        }
    077    }
    078
    079    /** Serialization version */
    080    private static final long serialVersionUID = -5722039223898659102L;
    081
    082    /**
    083     * Factory method to create a predicated (validating) list.
    084     * <p>
    085     * If there are any elements already in the list being decorated, they
    086     * are validated.
    087     *
    088     * @param <T> the type of the elements in the list
    089     * @param list  the list to decorate, must not be null
    090     * @param predicate  the predicate to use for validation, must not be null
    091     * @return a new predicated list
    092     * @throws NullPointerException if list or predicate is null
    093     * @throws IllegalArgumentException if the list contains invalid elements
    094     * @since 4.0
    095     */
    096    public static <T> PredicatedList<T> predicatedList(final List<T> list, final Predicate<? super T> predicate) {
    097        return new PredicatedList<>(list, predicate);
    098    }
    099
    100    /**
    101     * Constructor that wraps (not copies).
    102     * <p>
    103     * If there are any elements already in the list being decorated, they
    104     * are validated.
    105     *
    106     * @param list  the list to decorate, must not be null
    107     * @param predicate  the predicate to use for validation, must not be null
    108     * @throws NullPointerException if list or predicate is null
    109     * @throws IllegalArgumentException if the list contains invalid elements
    110     */
    111    protected PredicatedList(final List<E> list, final Predicate<? super E> predicate) {
    112        super(list, predicate);
    113    }
    114
    115    @Override
    116    public void add(final int index, final E object) {
    117        validate(object);
    118        decorated().add(index, object);
    119    }
    120
    121    @Override
    122    public boolean addAll(final int index, final Collection<? extends E> coll) {
    123        for (final E aColl : coll) {
    124            validate(aColl);
    125        }
    126        return decorated().addAll(index, coll);
    127    }
    128
    129    /**
    130     * Gets the list being decorated.
    131     *
    132     * @return the decorated list
    133     */
    134    @Override
    135    protected List<E> decorated() {
    136        return (List<E>) super.decorated();
    137    }
    138
    139    @Override
    140    public boolean equals(final Object object) {
    141        return object == this || decorated().equals(object);
    142    }
    143
    144    @Override
    145    public E get(final int index) {
    146        return decorated().get(index);
    147    }
    148
    149    @Override
    150    public int hashCode() {
    151        return decorated().hashCode();
    152    }
    153
    154    @Override
    155    public int indexOf(final Object object) {
    156        return decorated().indexOf(object);
    157    }
    158
    159    @Override
    160    public int lastIndexOf(final Object object) {
    161        return decorated().lastIndexOf(object);
    162    }
    163
    164    @Override
    165    public ListIterator<E> listIterator() {
    166        return listIterator(0);
    167    }
    168
    169    @Override
    170    public ListIterator<E> listIterator(final int i) {
    171        return new PredicatedListIterator(decorated().listIterator(i));
    172    }
    173
    174    @Override
    175    public E remove(final int index) {
    176        return decorated().remove(index);
    177    }
    178
    179    @Override
    180    public E set(final int index, final E object) {
    181        validate(object);
    182        return decorated().set(index, object);
    183    }
    184
    185    @Override
    186    public List<E> subList(final int fromIndex, final int toIndex) {
    187        final List<E> sub = decorated().subList(fromIndex, toIndex);
    188        return new PredicatedList<>(sub, predicate);
    189    }
    190
    191}