    001// Copyright 2011, 2012 The Apache Software Foundation
    002//
    003// Licensed under the Apache License, Version 2.0 (the "License");
    004// you may not use this file except in compliance with the License.
    005// You may obtain a copy of the License at
    006//
    007// http://www.apache.org/licenses/LICENSE-2.0
    008//
    009// Unless required by applicable law or agreed to in writing, software
    010// distributed under the License is distributed on an "AS IS" BASIS,
    011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    012// See the License for the specific language governing permissions and
    013// limitations under the License.
    014
    015package org.apache.tapestry5.func;
    016
    017import java.util.Collection;
    018import java.util.Comparator;
    019import java.util.List;
    020import java.util.Set;
    021
    022/**
    023 * @param <T>
    024 *         the type of data in the flow
    025 * @param <FT>
    026 *         the type of flow (either Flow<T> or ZippedFlow<Tuple<T, ?>)
    027 * @since 5.3
    028 */
    029public interface FlowOperations<T, FT> extends Iterable<T>
    030{
    031    /**
    032     * Filters values, keeping only values where the predicate is true, returning a new Flow with
    033     * just the retained values.
    034     */
    035    FT filter(Predicate<? super T> predicate);
    036
    037    /**
    038     * Removes values where the predicate returns true, returning a new Flow with just the remaining
    039     * values.
    040     */
    041    FT remove(Predicate<? super T> predicate);
    042
    043    /**
    044     * Applies the worker to each element in the Flow, then returns the flow for further behaviors.
    045     * <p/>
    046     * Each is a non-lazy operation; it will fully realize the values of the Flow.
    047     */
    048    FT each(Worker<? super T> worker);
    049
    050    /**
    051     * Converts the Flow into an unmodifiable list of values. This is a non-lazy operation that will
    052     * fully realize the values of the Flow.
    053     */
    054    List<T> toList();
    055
    056    /**
    057     * Converts the Flow into an unmodifiable set of values. This is a non-lazy operation that will
    058     * fully realize the values of the Flow.
    059     */
    060    Set<T> toSet();
    061
    062    /**
    063     * Returns a new flow with the same elements but in reverse order.
    064     */
    065    FT reverse();
    066
    067    /**
    068     * Returns true if the Flow contains no values. This <em>may</em> realize the first value in the
    069     * Flow.
    070     */
    071    boolean isEmpty();
    072
    073    /**
    074     * Returns the first element in the Flow. Returns null for empty flows, but remember that null
    075     * is a valid element within a flow, so use {@link #isEmpty()} to determine if a flow is actually
    076     * empty. The first element can be realized without realizing the full Flow.
    077     */
    078    T first();
    079
    080    /**
    081     * Returns a new Flow containing all but the first element in this flow. If this flow has only a
    082     * single element, or is empty, this will return an empty Flow.
    083     */
    084    FT rest();
    085
    086    /**
    087     * Returns the number of values in this flow. This forces the realization of much of the flow
    088     * (i.e., because each value will need to be passed through any {@link Predicate}s).
    089     */
    090    int count();
    091
    092    /**
    093     * Sorts this flow using the comparator, forming a new flow. This is a non-lazy operation; it
    094     * will fully realize the elements of the Flow.
    095     */
    096    FT sort(Comparator<T> comparator);
    097
    098    /**
    099     * Returns a new flow containing just the first elements from this Flow.
    100     *
    101     * @param length
    102     *         maximum number of values in the Flow
    103     */
    104    FT take(int length);
    105
    106    /**
    107     * Returns a new flow with the first elements omitted.
    108     *
    109     * @param length
    110     *         number of values to drop
    111     */
    112    FT drop(int length);
    113
    114    /**
    115     * Returns a new Flow with the elements in the collection appended to this Flow. This is a lazy
    116     * operation.
    117     * <p/>
    118     * Note that the type of this method changed from {@code List} to {@link Collection} in Tapestry 5.4. This
    119     * is considered a compatible change.
    120     *
    121     * @param collection
    122     *         collection of elements to be appended
    123     */
    124    FT concat(Collection<? extends T> collection);
    125
    126    /**
    127     * Applies a Reducer to the values of the Flow. The Reducer is passed the initial value
    128     * and the first element from the Flow. The result is captured as the accumulator and passed
    129     * to the Reducer with the next value from the Flow, and so on. The final accumulator
    130     * value is returned. If the flow is empty, the initial value is returned.
    131     * <p/>
    132     * Reducing is a non-lazy operation; it will fully realize the values of the Flow.
    133     */
    134    <A> A reduce(Reducer<A, T> reducer, A initial);
    135
    136    /**
    137     * Removes null elements from the flow (null tuples from a ZippedFlow), leaving just the
    138     * non-null elements. This is a lazy operation.
    139     *
    140     * @since 5.3
    141     */
    142    FT removeNulls();
    143}