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}