    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 */
    017
    018package org.apache.commons.collections4.iterators;
    019
    020import java.util.Iterator;
    021import java.util.Objects;
    022
    023import org.apache.commons.collections4.Transformer;
    024
    025/**
    026 * Decorates an iterator such that each element returned is transformed.
    027 *
    028 * @param <I> The type of the input to the function.
    029 * @param <O> The type of the result of the function.
    030 * @since 1.0
    031 */
    032public class TransformIterator<I, O> implements Iterator<O> {
    033
    034    /** The iterator being used */
    035    private Iterator<? extends I> iterator;
    036    /** The transformer being used */
    037    private Transformer<? super I, ? extends O> transformer;
    038
    039    /**
    040     * Constructs a new {@code TransformIterator} that will not function until the {@link #setIterator(Iterator) setIterator} and
    041     * {@link #setTransformer(Transformer)} methods are invoked.
    042     */
    043    public TransformIterator() {
    044    }
    045
    046    /**
    047     * Constructs a new {@code TransformIterator} that won't transform elements from the given iterator.
    048     *
    049     * @param iterator The iterator to use.
    050     */
    051    public TransformIterator(final Iterator<? extends I> iterator) {
    052        this(iterator, null);
    053    }
    054
    055    /**
    056     * Constructs a new {@code TransformIterator} that will use the given iterator and transformer. If the given transformer is null, then objects will not be
    057     * transformed.
    058     *
    059     * @param iterator    The iterator to use, may not be null.
    060     * @param transformer The transformer to use, may be null to pass elements through unchanged
    061     */
    062    public TransformIterator(final Iterator<? extends I> iterator, final Transformer<? super I, ? extends O> transformer) {
    063        this.iterator = Objects.requireNonNull(iterator, "iterator");
    064        this.transformer = transformer;
    065    }
    066
    067    /**
    068     * Gets the iterator this iterator is using.
    069     *
    070     * @return The iterator.
    071     */
    072    public Iterator<? extends I> getIterator() {
    073        return iterator;
    074    }
    075
    076    /**
    077     * Gets the transformer this iterator is using.
    078     *
    079     * @return The transformer, may be null.
    080     */
    081    public Transformer<? super I, ? extends O> getTransformer() {
    082        return transformer;
    083    }
    084
    085    @Override
    086    public boolean hasNext() {
    087        return iterator.hasNext();
    088    }
    089
    090    /**
    091     * Gets the next object from the iteration, transforming it using the current transformer. If the transformer is null, no transformation occurs and the
    092     * object from the iterator is returned directly.
    093     *
    094     * @return The next object.
    095     * @throws java.util.NoSuchElementException if there are no more elements.
    096     */
    097    @Override
    098    public O next() {
    099        return transform(iterator.next());
    100    }
    101
    102    @Override
    103    public void remove() {
    104        iterator.remove();
    105    }
    106
    107    /**
    108     * Sets the iterator for this iterator to use. If iteration has started, this effectively resets the iterator.
    109     *
    110     * @param iterator The iterator to use.
    111     */
    112    public void setIterator(final Iterator<? extends I> iterator) {
    113        this.iterator = iterator;
    114    }
    115
    116    /**
    117     * Sets the transformer this the iterator to use. A null transformer is a no-op transformer.
    118     *
    119     * @param transformer The transformer to use, may be null to pass elements through unchanged.
    120     */
    121    public void setTransformer(final Transformer<? super I, ? extends O> transformer) {
    122        this.transformer = transformer;
    123    }
    124
    125    /**
    126     * Transforms the given object using the transformer. If the transformer is null, the original object is returned as-is.
    127     *
    128     * @param source The object to transform, may be null.
    129     * @return The transformed object, the original object the transformer is null.
    130     */
    131    @SuppressWarnings("unchecked")
    132    protected O transform(final I source) {
    133        return transformer == null ? (O) source : transformer.apply(source);
    134    }
    135}