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