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.Function;
019import org.apache.commons.functor.Procedure;
020
021/**
022 * The Generator interface defines a number of useful actions applying Procedures
023 * to each in a series of argument Objects.
024 *
025 * @param <E> the type of elements held in this generator.
026 * @version $Revision: 1522355 $ $Date: 2013-09-12 06:29:46 +0200 (Do, 12 Sep 2013) $
027 */
028public interface Generator<E> {
029    /**
030     * Generators must implement this method.
031     * @param proc Procedure to run
032     */
033    void run(Procedure<? super E> proc);
034
035    /**
036     * Transforms this generator using the passed in
037     * transformer. An example transformer might turn the contents of the
038     * generator into a {@link Collection} of elements.
039     * @param <Z> the returned value type of the input {@link Function}
040     * @param transformer Function to apply to this
041     * @return transformation result
042     */
043    <Z> Z to(Function<Generator<? extends E>, ? extends Z> transformer);
044
045    /**
046     * Same as to(new CollectionTransformer(collection)).
047     * @param <C> the returned collection type
048     * @param collection Collection to which my elements should be added
049     * @return <code>collection</code>
050     */
051    <C extends Collection<? super E>> C to(C collection);
052
053    /**
054     * Same as to(new CollectionTransformer()).
055     * @return Collection
056     */
057    Collection<? super E> toCollection();
058}