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 */
014package org.apache.commons.functor.generator;
015
016import java.util.Collection;
017
018import org.apache.commons.functor.UnaryFunction;
019import 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: 1370922 $ $Date: 2012-08-08 15:53:37 -0400 (Wed, 08 Aug 2012) $
027 */
028public interface Generator<E> {
029    /**
030     * Generators must implement this method.
031     * @param proc UnaryProcedure to run
032     */
033    void run(UnaryProcedure<? super E> proc);
034
035    /**
036     * Stop the generator. Will stop the wrapped generator if one was set.
037     */
038    void stop();
039
040    /**
041     * Check if the generator is stopped.
042     * @return true if stopped
043     */
044    boolean isStopped();
045
046    /**
047     * Transforms this generator using the passed in
048     * transformer. An example transformer might turn the contents of the
049     * generator into a {@link Collection} of elements.
050     * @param <Z> the returned value type of the input {@link UnaryFunction}.
051     * @param transformer UnaryFunction to apply to this
052     * @return transformation result
053     */
054    <Z> Z to(UnaryFunction<Generator<? extends E>, ? extends Z> transformer);
055
056    /**
057     * Same as to(new CollectionTransformer(collection)).
058     * @param collection Collection to which my elements should be added
059     * @return <code>collection</code>
060     */
061    <C extends Collection<? super E>> C to(C collection);
062
063    /**
064     * Same as to(new CollectionTransformer()).
065     * @return Collection
066     */
067    Collection<? super E> toCollection();
068}