    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.collection;
    018
    019import java.util.ArrayList;
    020import java.util.Collection;
    021import java.util.List;
    022
    023import org.apache.commons.collections4.Transformer;
    024
    025/**
    026 * Decorates another {@link Collection} to transform objects that are added.
    027 * <p>
    028 * The add methods are affected by this class.
    029 * Thus objects must be removed or searched for using their transformed form.
    030 * For example, if the transformation converts Strings to Integers, you must
    031 * use the Integer form to remove objects.
    032 * <p>
    033 * This class is Serializable from Commons Collections 3.1.
    034 *
    035 * @param <E> the type of the elements in the collection
    036 * @since 3.0
    037 */
    038public class TransformedCollection<E> extends AbstractCollectionDecorator<E> {
    039
    040    /** Serialization version */
    041    private static final long serialVersionUID = 8692300188161871514L;
    042
    043    /** The transformer to use */
    044    protected final Transformer<? super E, ? extends E> transformer;
    045
    046    /**
    047     * Factory method to create a transforming collection.
    048     * <p>
    049     * If there are any elements already in the collection being decorated, they
    050     * are NOT transformed.
    051     * Contrast this with {@link #transformedCollection(Collection, Transformer)}.
    052     *
    053     * @param <E> the type of the elements in the collection
    054     * @param coll  the collection to decorate, must not be null
    055     * @param transformer  the transformer to use for conversion, must not be null
    056     * @return a new transformed collection
    057     * @throws NullPointerException if collection or transformer is null
    058     * @since 4.0
    059     */
    060    public static <E> TransformedCollection<E> transformingCollection(final Collection<E> coll,
    061            final Transformer<? super E, ? extends E> transformer) {
    062        return new TransformedCollection<>(coll, transformer);
    063    }
    064
    065    /**
    066     * Factory method to create a transforming collection that will transform
    067     * existing contents of the specified collection.
    068     * <p>
    069     * If there are any elements already in the collection being decorated, they
    070     * will be transformed by this method.
    071     * Contrast this with {@link #transformingCollection(Collection, Transformer)}.
    072     *
    073     * @param <E> the type of the elements in the collection
    074     * @param collection  the collection to decorate, must not be null
    075     * @param transformer  the transformer to use for conversion, must not be null
    076     * @return a new transformed Collection
    077     * @throws NullPointerException if collection or transformer is null
    078     * @since 4.0
    079     */
    080    public static <E> TransformedCollection<E> transformedCollection(final Collection<E> collection,
    081            final Transformer<? super E, ? extends E> transformer) {
    082
    083        final TransformedCollection<E> decorated = new TransformedCollection<>(collection, transformer);
    084        // null collection & transformer are disallowed by the constructor call above
    085        if (collection.size() > 0) {
    086            @SuppressWarnings("unchecked") // collection is of type E
    087            final E[] values = (E[]) collection.toArray(); // NOPMD - false positive for generics
    088            collection.clear();
    089            for (final E value : values) {
    090                decorated.decorated().add(transformer.transform(value));
    091            }
    092        }
    093        return decorated;
    094    }
    095
    096    //-----------------------------------------------------------------------
    097    /**
    098     * Constructor that wraps (not copies).
    099     * <p>
    100     * If there are any elements already in the collection being decorated, they
    101     * are NOT transformed.
    102     *
    103     * @param coll  the collection to decorate, must not be null
    104     * @param transformer  the transformer to use for conversion, must not be null
    105     * @throws NullPointerException if collection or transformer is null
    106     */
    107    protected TransformedCollection(final Collection<E> coll, final Transformer<? super E, ? extends E> transformer) {
    108        super(coll);
    109        if (transformer == null) {
    110            throw new NullPointerException("Transformer must not be null");
    111        }
    112        this.transformer = transformer;
    113    }
    114
    115    /**
    116     * Transforms an object.
    117     * <p>
    118     * The transformer itself may throw an exception if necessary.
    119     *
    120     * @param object  the object to transform
    121     * @return a transformed object
    122     */
    123    protected E transform(final E object) {
    124        return transformer.transform(object);
    125    }
    126
    127    /**
    128     * Transforms a collection.
    129     * <p>
    130     * The transformer itself may throw an exception if necessary.
    131     *
    132     * @param coll  the collection to transform
    133     * @return a transformed object
    134     */
    135    protected Collection<E> transform(final Collection<? extends E> coll) {
    136        final List<E> list = new ArrayList<>(coll.size());
    137        for (final E item : coll) {
    138            list.add(transform(item));
    139        }
    140        return list;
    141    }
    142
    143    //-----------------------------------------------------------------------
    144    @Override
    145    public boolean add(final E object) {
    146        return decorated().add(transform(object));
    147    }
    148
    149    @Override
    150    public boolean addAll(final Collection<? extends E> coll) {
    151        return decorated().addAll(transform(coll));
    152    }
    153
    154}