001    /*
002     * Licensed under the Apache License, Version 2.0 (the "License");
003     * you may not use this file except in compliance with the License.
004     * You may obtain a copy of the License at
005     *
006     *      http://www.apache.org/licenses/LICENSE-2.0
007     *
008     * Unless required by applicable law or agreed to in writing, software
009     * distributed under the License is distributed on an "AS IS" BASIS,
010     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
011     * See the License for the specific language governing permissions and
012     * limitations under the License.
013     */
014    package org.apache.commons.functor.generator;
015    
016    import java.util.Collection;
017    
018    import org.apache.commons.functor.UnaryFunction;
019    import org.apache.commons.functor.UnaryProcedure;
020    
021    /**
022     * The Generator interface defines a number of useful actions applying UnaryFunctors
023     * to each in a series of argument Objects.
024     *
025     * @param <E> the type of elements held in this generator.
026     * @version $Revision: 1160786 $ $Date: 2011-08-23 18:40:12 +0200 (Tue, 23 Aug 2011) $
027     * @author Jason Horman (jason@jhorman.org)
028     * @author Rodney Waldhoff
029     */
030    public interface Generator<E> {
031        /**
032         * Generators must implement this method.
033         * @param proc UnaryProcedure to run
034         */
035        void run(UnaryProcedure<? super E> proc);
036    
037        /**
038         * Stop the generator. Will stop the wrapped generator if one was set.
039         */
040        void stop();
041    
042        /**
043         * Check if the generator is stopped.
044         * @return true if stopped
045         */
046        boolean isStopped();
047    
048        /**
049         * Transforms this generator using the passed in
050         * transformer. An example transformer might turn the contents of the
051         * generator into a {@link Collection} of elements.
052         * @param <Z> the returned value type of the input {@link UnaryFunction}.
053         * @param transformer UnaryFunction to apply to this
054         * @return transformation result
055         */
056        <Z> Z to(UnaryFunction<Generator<? extends E>, ? extends Z> transformer);
057    
058        /**
059         * Same as to(new CollectionTransformer(collection)).
060         * @param collection Collection to which my elements should be added
061         * @return <code>collection</code>
062         */
063        Collection<? super E> to(Collection<? super E> collection);
064    
065        /**
066         * Same as to(new CollectionTransformer()).
067         * @return Collection
068         */
069        Collection<? super E> toCollection();
070    }