    001    // Copyright 2011 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
    015    package org.apache.tapestry5.func;
    016
    017    import java.util.Comparator;
    018    import java.util.List;
    019    import java.util.Set;
    020
    021    /**
    022     * @param <T>
    023     *            the type of data in the flow
    024     * @param <FT>
    025     *            the type of flow (either Flow<T> or ZippedFlow<Tuple<T, ?>)
    026     * @since 5.3
    027     */
    028    public interface FlowOperations<T, FT> extends Iterable<T>
    029    {
    030        /**
    031         * Filters values, keeping only values where the predicate is true, returning a new Flow with
    032         * just the retained values.
    033         */
    034        FT filter(Predicate<? super T> predicate);
    035
    036        /**
    037         * Removes values where the predicate returns true, returning a new Flow with just the remaining
    038         * values.
    039         */
    040        FT remove(Predicate<? super T> predicate);
    041
    042        /**
    043         * Applies the worker to each element in the Flow, then returns the flow for further behaviors.
    044         * <p>
    045         * Each is a non-lazy operation; it will fully realize the values of the Flow.
    046         */
    047        FT each(Worker<? super T> worker);
    048
    049        /**
    050         * Converts the Flow into an unmodifiable list of values. This is a non-lazy operation that will
    051         * fully realize the values of the Flow.
    052         */
    053        List<T> toList();
    054
    055        /**
    056         * Converts the Flow into an unmodifiable set of values. This is a non-lazy operation that will
    057         * fully realize the values of the Flow.
    058         */
    059        Set<T> toSet();
    060
    061        /** Returns a new flow with the same elements but in reverse order. */
    062        FT reverse();
    063
    064        /**
    065         * Returns true if the Flow contains no values. This <em>may</em> realize the first value in the
    066         * Flow.
    067         */
    068        boolean isEmpty();
    069
    070        /**
    071         * Returns the first element in the Flow. Returns null for empty flows, but remember that null
    072         * is a valid element within a flow, so use {@link #isEmpty()} to determine if a flow is actually
    073         * empty. The first element can be realized without realizing the full Flow.
    074         */
    075        T first();
    076
    077        /**
    078         * Returns a new Flow containing all but the first element in this flow. If this flow has only a
    079         * single element, or is empty, this will return an empty Flow.
    080         */
    081        FT rest();
    082
    083        /**
    084         * Returns the number of values in this flow. This forces the realization of much of the flow
    085         * (i.e., because each value will need to be passed through any {@link Predicate}s).
    086         */
    087        int count();
    088
    089        /**
    090         * Sorts this flow using the comparator, forming a new flow. This is a non-lazy operation; it
    091         * will fully realize the elements of the Flow.
    092         */
    093        FT sort(Comparator<T> comparator);
    094
    095        /**
    096         * Returns a new flow containing just the first elements from this Flow.
    097         *
    098         * @param length
    099         *            maximum number of values in the Flow
    100         */
    101        FT take(int length);
    102
    103        /**
    104         * Returns a new flow with the first elements omitted.
    105         *
    106         * @param length
    107         *            number of values to drop
    108         */
    109        FT drop(int length);
    110
    111        /**
    112         * Returns a new Flow with the elements in the list appended to this Flow. This is a lazy
    113         * operation.
    114         */
    115        FT concat(List<? extends T> list);
    116
    117        /**
    118         * Applies a Reducer to the values of the Flow. The Reducer is passed the initial value
    119         * and the first element from the Flow. The result is captured as the accumulator and passed
    120         * to the Reducer with the next value from the Flow, and so on. The final accumulator
    121         * value is returned. If the flow is empty, the initial value is returned.
    122         * <p>
    123         * Reducing is a non-lazy operation; it will fully realize the values of the Flow.
    124         */
    125        <A> A reduce(Reducer<A, T> reducer, A initial);
    126
    127        /**
    128         * Removes null elements from the flow (null tuples from a ZippedFlow), leaving just the
    129         * non-null elements. This is a lazy operation.
    130         *
    131         * @since 5.3
    132         */
    133        FT removeNulls();
    134    }