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}