com.jongsoft.lang.collection.Pipeline Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of language Show documentation

Java Language Extensions

The newest version!

package com.jongsoft.lang.collection;

import java.util.Iterator;
import java.util.function.Consumer;
import java.util.function.Function;
import java.util.function.Predicate;

import com.jongsoft.lang.Streamable;

/**
 * A pipeline is a set of commands that will be applied on top any {@link Collection}. Each command is lazy and will
 * only get executed once the pipe is terminated.
 * 
 *     Note that a pipeline can be split by re-using the intermediate operation. Each pipeline after the split will
 *     yield a different result and not modify the steps in between.
 * 
 * Example:
 * {@code
 *    Pipeline intermediatePipe = API.List(1, 2, 3, 4)
 *          .pipeline()
 *          .filter(x -> x % 2 == 0);
 *
 *    Pipeline stringPipe = intermediatePipe.map(String::valueOf);
 *    Pipeline finalPipe = intermediatePipe.map(x -> x * x / 3);
 *
 * }
 *
 * @param  the type of elements contained in the original collection
 * @since 1.0.6
 */
public interface Pipeline extends Foldable, Streamable {

    /**
     * Consumes each element in the pipeline using the provided consume operation. This is a terminal operation.
     *
     * @param consumer the consumer
     * @throws NullPointerException if the {@code consumer} is null
     */
    void consume(Consumer consumer);

    @Override
    Pipeline filter(Predicate predicate);

    /**
     * This will return the iterator for this pipelines elements. This is a terminal operation.
     *
     * @return the iterator for all elements in the pipeline
     */
    @Override
    Iterator iterator();

    @Override
     Pipeline map(Function mapper);

    /**
     * Reject all values that match the provided predicate. This is the logical inverse of the operation
     * {@link #filter(Predicate)}.
     *
     * @param predicate the predicate to use
     * @return a pipeline instruction rejecting all values matching the predicate
     */
    Pipeline reject(Predicate predicate);

}