    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 * @param <E> the type of the elements in the list.
    049 * @since 3.0
    050 */
    051public class PredicatedList<E> extends PredicatedCollection<E> implements List<E> {
    052
    053    /**
    054     * Inner class Iterator for the PredicatedList
    055     */
    056    protected class PredicatedListIterator extends AbstractListIteratorDecorator<E> {
    057
    058        /**
    059         * Create a new predicated list iterator.
    060         *
    061         * @param iterator  the list iterator to decorate
    062         */
    063        protected PredicatedListIterator(final ListIterator<E> iterator) {
    064            super(iterator);
    065        }
    066
    067        @Override
    068        public void add(final E object) {
    069            validate(object);
    070            getListIterator().add(object);
    071        }
    072
    073        @Override
    074        public void set(final E object) {
    075            validate(object);
    076            getListIterator().set(object);
    077        }
    078    }
    079
    080    /** Serialization version */
    081    private static final long serialVersionUID = -5722039223898659102L;
    082
    083    /**
    084     * Factory method to create a predicated (validating) list.
    085     * <p>
    086     * If there are any elements already in the list being decorated, they
    087     * are validated.
    088     *
    089     * @param <T> the type of the elements in the list
    090     * @param list  the list to decorate, must not be null
    091     * @param predicate  the predicate to use for validation, must not be null
    092     * @return a new predicated list
    093     * @throws NullPointerException if list or predicate is null
    094     * @throws IllegalArgumentException if the list contains invalid elements
    095     * @since 4.0
    096     */
    097    public static <T> PredicatedList<T> predicatedList(final List<T> list, final Predicate<? super T> predicate) {
    098        return new PredicatedList<>(list, predicate);
    099    }
    100
    101    /**
    102     * Constructor that wraps (not copies).
    103     * <p>
    104     * If there are any elements already in the list being decorated, they
    105     * are validated.
    106     *
    107     * @param list  the list to decorate, must not be null
    108     * @param predicate  the predicate to use for validation, must not be null
    109     * @throws NullPointerException if list or predicate is null
    110     * @throws IllegalArgumentException if the list contains invalid elements
    111     */
    112    protected PredicatedList(final List<E> list, final Predicate<? super E> predicate) {
    113        super(list, predicate);
    114    }
    115
    116    @Override
    117    public void add(final int index, final E object) {
    118        validate(object);
    119        decorated().add(index, object);
    120    }
    121
    122    @Override
    123    public boolean addAll(final int index, final Collection<? extends E> coll) {
    124        for (final E aColl : coll) {
    125            validate(aColl);
    126        }
    127        return decorated().addAll(index, coll);
    128    }
    129
    130    /**
    131     * Gets the list being decorated.
    132     *
    133     * @return the decorated list
    134     */
    135    @Override
    136    protected List<E> decorated() {
    137        return (List<E>) super.decorated();
    138    }
    139
    140    @Override
    141    public boolean equals(final Object object) {
    142        return object == this || decorated().equals(object);
    143    }
    144
    145    @Override
    146    public E get(final int index) {
    147        return decorated().get(index);
    148    }
    149
    150    @Override
    151    public int hashCode() {
    152        return decorated().hashCode();
    153    }
    154
    155    @Override
    156    public int indexOf(final Object object) {
    157        return decorated().indexOf(object);
    158    }
    159
    160    @Override
    161    public int lastIndexOf(final Object object) {
    162        return decorated().lastIndexOf(object);
    163    }
    164
    165    @Override
    166    public ListIterator<E> listIterator() {
    167        return listIterator(0);
    168    }
    169
    170    @Override
    171    public ListIterator<E> listIterator(final int i) {
    172        return new PredicatedListIterator(decorated().listIterator(i));
    173    }
    174
    175    @Override
    176    public E remove(final int index) {
    177        return decorated().remove(index);
    178    }
    179
    180    @Override
    181    public E set(final int index, final E object) {
    182        validate(object);
    183        return decorated().set(index, object);
    184    }
    185
    186    @Override
    187    public List<E> subList(final int fromIndex, final int toIndex) {
    188        final List<E> sub = decorated().subList(fromIndex, toIndex);
    189        return new PredicatedList<>(sub, predicate);
    190    }
    191
    192}