1 /* 2 * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 package java.util.stream; 26 27 import java.util.Collections; 28 import java.util.EnumSet; 29 import java.util.Set; 30 import java.util.function.BiConsumer; 31 import java.util.function.BinaryOperator; 32 import java.util.function.Function; 33 import java.util.function.Supplier; 34 35 /** 36 * A <a href="package-summary.html#Reduction">reduction operation</a> that 37 * folds input elements into a mutable result container, optionally transforming 38 * the accumulated result into a final representation after all input elements 39 * have been processed. 40 * 41 * <p>Examples of mutable reduction operations include: 42 * accumulating elements into a {@code Collection}; concatenating 43 * strings using a {@code StringBuilder}; computing summary information about 44 * elements such as sum, min, max, or average; computing "pivot table" summaries 45 * such as "maximum valued transaction by seller", etc. Reduction operations 46 * can be performed either sequentially or in parallel. 47 * 48 * <p>The following are examples of using the predefined {@code Collector} 49 * implementations in {@link Collectors} with the {@code Stream} API to perform 50 * mutable reduction tasks: 51 * <pre>{@code 52 * // Accumulate names into a List 53 * List<String> list = people.stream().map(Person::getName).collect(Collectors.toList()); 54 * 55 * // Accumulate names into a TreeSet 56 * Set<String> list = people.stream().map(Person::getName).collect(Collectors.toCollection(TreeSet::new)); 57 * 58 * // Convert elements to strings and concatenate them, separated by commas 59 * String joined = things.stream() 60 * .map(Object::toString) 61 * .collect(Collectors.joining(", ")); 62 * 63 * // Find highest-paid employee 64 * Employee highestPaid = employees.stream() 65 * .collect(Collectors.maxBy(Comparators.comparing(Employee::getSalary))) 66 * .get(); 67 * 68 * // Group employees by department 69 * Map<Department, List<Employee>> byDept 70 * = employees.stream() 71 * .collect(Collectors.groupingBy(Employee::getDepartment)); 72 * 73 * // Find highest-paid employee by department 74 * Map<Department, Optional<Employee>> highestPaidByDept 75 * = employees.stream() 76 * .collect(Collectors.groupingBy(Employee::getDepartment, 77 * Collectors.maxBy(Comparators.comparing(Employee::getSalary)))); 78 * 79 * // Partition students into passing and failing 80 * Map<Boolean, List<Student>> passingFailing = 81 * students.stream() 82 * .collect(Collectors.partitioningBy(s -> s.getGrade() >= PASS_THRESHOLD)); 83 * 84 * }</pre> 85 * 86 * <p>A {@code Collector} is specified by four functions that work together to 87 * accumulate entries into a mutable result container, and optionally perform 88 * a final transform on the result. They are: creation of a new result container, 89 * incorporating a new data element into a result container, combining two 90 * result containers into one, and performing a final transform on the container. 91 * The combiner function is used during parallel operations, where 92 * subsets of the input are accumulated into separate result 93 * containers, and then the subresults merged into a combined result. The 94 * combiner function may merge one set of subresults into the other and return 95 * that, or it may return a new object to describe the combined results. 96 * 97 * <p>Collectors also have a set of characteristics, such as 98 * {@link Characteristics#CONCURRENT}. These characteristics provide 99 * hints that can be used by a reduction implementation to provide better 100 * performance. 101 * 102 * <p>Libraries that implement reduction based on {@code Collector}, such as 103 * {@link Stream#collect(Collector)}, must adhere to the following constraints: 104 * <ul> 105 * <li>The first argument passed to the accumulator function, both 106 * arguments passed to the combiner function, and the argument passed to the 107 * finisher function must be the result of a previous invocation of the 108 * result supplier, accumulator, or combiner functions.</li> 109 * <li>The implementation should not do anything with the result of any of 110 * the result supplier, accumulator, or combiner functions other than to 111 * pass them again to the accumulator, combiner, or finisher functions, 112 * or return them to the caller of the reduction operation.</li> 113 * <li>If a result is passed to the combiner or finisher 114 * function, and the same object is not returned from that function, it is 115 * never used again.</li> 116 * <li>Once a result is passed to the combiner or finisher function, it 117 * is never passed to the accumulator function again.</li> 118 * <li>For non-concurrent collectors, any result returned from the result 119 * supplier, accumulator, or combiner functions must be serially 120 * thread-confined. This enables collection to occur in parallel without 121 * the {@code Collector} needing to implement any additional synchronization. 122 * The reduction implementation must manage that the input is properly 123 * partitioned, that partitions are processed in isolation, and combining 124 * happens only after accumulation is complete.</li> 125 * <li>For concurrent collectors, an implementation is free to (but not 126 * required to) implement reduction concurrently. A concurrent reduction 127 * is one where the accumulator function is called concurrently from 128 * multiple threads, using the same concurrently-modifiable result container, 129 * rather than keeping the result isolated during accumulation. 130 * A concurrent reduction should only be applied if the collector has the 131 * {@link Characteristics#UNORDERED} characteristics or if the 132 * originating data is unordered.</li> 133 * </ul> 134 * 135 * @apiNote 136 * Performing a reduction operation with a {@code Collector} should produce a 137 * result equivalent to: 138 * <pre>{@code 139 * R container = collector.supplier().get(); 140 * for (T t : data) 141 * collector.accumulator().accept(container, t); 142 * return collector.finisher().apply(container); 143 * }</pre> 144 * 145 * <p>However, the library is free to partition the input, perform the reduction 146 * on the partitions, and then use the combiner function to combine the partial 147 * results to achieve a parallel reduction. Depending on the specific reduction 148 * operation, this may perform better or worse, depending on the relative cost 149 * of the accumulator and combiner functions. 150 * 151 * <p>An example of an operation that can be easily modeled by {@code Collector} 152 * is accumulating elements into a {@code TreeSet}. In this case, the {@code 153 * resultSupplier()} function is {@code () -> new Treeset<T>()}, the 154 * {@code accumulator} function is 155 * {@code (set, element) -> set.add(element) }, and the combiner 156 * function is {@code (left, right) -> { left.addAll(right); return left; }}. 157 * (This behavior is implemented by 158 * {@code Collectors.toCollection(TreeSet::new)}). 159 * 160 * TODO Associativity and commutativity 161 * 162 * @see Stream#collect(Collector) 163 * @see Collectors 164 * 165 * @param <T> the type of input elements to the reduction operation 166 * @param <A> the mutable accumulation type of the reduction operation (often 167 * hidden as an implementation detail) 168 * @param <R> the result type of the reduction operation 169 * @since 1.8 170 */ 171 public interface Collector<T, A, R> { 172 /** 173 * A function that creates and returns a new mutable result container. 174 * 175 * @return a function which returns a new, mutable result container 176 */ 177 Supplier<A> supplier(); 178 179 /** 180 * A function that folds a new value into a mutable result container. 181 * 182 * @return a function which folds a new value into a mutable result container 183 */ 184 BiConsumer<A, T> accumulator(); 185 186 /** 187 * A function that accepts two partial results and merges them. The 188 * combiner function may fold state from one argument into the other and 189 * return that, or may return a new result object. 190 * 191 * @return a function which combines two partial results into a cumulative 192 * result 193 */ 194 BinaryOperator<A> combiner(); 195 196 /** 197 * Perform the final transformation from the intermediate accumulation type 198 * {@code A} to the final result representation {@code R}. 199 * 200 * <p>If the characteristic {@code IDENTITY_TRANSFORM} is 201 * set, this function may be presumed to be an identity transform with an 202 * unchecked cast from {@code A} to {@code R}. 203 * 204 * @return a function which transforms the intermediate result to the final 205 * result 206 */ 207 Function<A, R> finisher(); 208 209 /** 210 * Returns a {@code Set} of {@code Collector.Characteristics} indicating 211 * the characteristics of this Collector. This set should be immutable. 212 * 213 * @return an immutable set of collector characteristics 214 */ 215 Set<Characteristics> characteristics(); 216 217 /** 218 * Returns a new {@code Collector} described by the given {@code supplier}, 219 * {@code accumulator}, and {@code combiner} functions. The resulting 220 * {@code Collector} has the {@code Collector.Characteristics.IDENTITY_FINISH} 221 * characteristic. 222 * 223 * @param supplier The supplier function for the new collector 224 * @param accumulator The accumulator function for the new collector 225 * @param combiner The combiner function for the new collector 226 * @param characteristics The collector characteristics for the new 227 * collector 228 * @param <T> The type of input elements for the new collector 229 * @param <R> The type of intermediate accumulation result, and final result, 230 * for the new collector 231 * @return the new {@code Collector} 232 */ 233 public static<T, R> Collector<T, R, R> of(Supplier<R> supplier, 234 BiConsumer<R, T> accumulator, 235 BinaryOperator<R> combiner, 236 Characteristics... characteristics) { 237 Set<Characteristics> cs = (characteristics.length == 0) 238 ? Collectors.CH_ID 239 : Collections.unmodifiableSet(EnumSet.of(Collector.Characteristics.IDENTITY_FINISH, 240 characteristics)); 241 return new Collectors.CollectorImpl<>(supplier, accumulator, combiner, cs); 242 } 243 244 /** 245 * Returns a new {@code Collector} described by the given {@code supplier}, 246 * {@code accumulator}, {@code combiner}, and {@code finisher} functions. 247 * 248 * @param supplier The supplier function for the new collector 249 * @param accumulator The accumulator function for the new collector 250 * @param combiner The combiner function for the new collector 251 * @param finisher The finisher function for the new collector 252 * @param characteristics The collector characteristics for the new 253 * collector 254 * @param <T> The type of input elements for the new collector 255 * @param <A> The intermediate accumulation type of the new collector 256 * @param <R> The final result type of the new collector 257 * @return the new {@code Collector} 258 */ 259 public static<T, A, R> Collector<T, A, R> of(Supplier<A> supplier, 260 BiConsumer<A, T> accumulator, 261 BinaryOperator<A> combiner, 262 Function<A, R> finisher, 263 Characteristics... characteristics) { 264 Set<Characteristics> cs = Collectors.CH_NOID; 265 if (characteristics.length > 0) { 266 cs = EnumSet.noneOf(Characteristics.class); 267 Collections.addAll(cs, characteristics); 268 cs = Collections.unmodifiableSet(cs); 269 } 270 return new Collectors.CollectorImpl<>(supplier, accumulator, combiner, finisher, cs); 271 } 272 273 /** 274 * Characteristics indicating properties of a {@code Collector}, which can 275 * be used to optimize reduction implementations. 276 */ 277 enum Characteristics { 278 /** 279 * Indicates that this collector is <em>concurrent</em>, meaning that 280 * the result container can support the accumulator function being 281 * called concurrently with the same result container from multiple 282 * threads. 283 * 284 * <p>If a {@code CONCURRENT} collector is not also {@code UNORDERED}, 285 * then it should only be evaluated concurrently if applied to an 286 * unordered data source. 287 */ 288 CONCURRENT, 289 290 /** 291 * Indicates that the result container has no intrinsic order, such as 292 * a {@link Set}. 293 */ 294 UNORDERED, 295 296 /** 297 * Indicates that the finisher function is the identity function and 298 * can be elided. If set, it must be the case that an unchecked cast 299 * from A to R will succeed. 300 */ 301 IDENTITY_FINISH 302 } 303 }