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.Objects;
30 import java.util.Set;
31 import java.util.function.BiConsumer;
32 import java.util.function.BinaryOperator;
33 import java.util.function.Function;
34 import java.util.function.Supplier;
35
36 /**
37 * A <a href="package-summary.html#Reduction">mutable reduction operation</a> that
38 * accumulates input elements into a mutable result container, optionally transforming
39 * the accumulated result into a final representation after all input elements
40 * have been processed. Reduction operations can be performed either sequentially
41 * or in parallel.
42 *
43 * <p>Examples of mutable reduction operations include:
44 * accumulating elements into a {@code Collection}; concatenating
45 * strings using a {@code StringBuilder}; computing summary information about
46 * elements such as sum, min, max, or average; computing "pivot table" summaries
47 * such as "maximum valued transaction by seller", etc. The class {@link Collectors}
48 * provides implementations of many common mutable reductions.
49 *
50 * <p>A {@code Collector} is specified by four functions that work together to
51 * accumulate entries into a mutable result container, and optionally perform
52 * a final transform on the result. They are: <ul>
53 * <li>creation of a new result container ({@link #supplier()})</li>
54 * <li>incorporating a new data element into a result container ({@link #accumulator()})</li>
186 * }</pre>
187 *
188 * @see Stream#collect(Collector)
189 * @see Collectors
190 *
191 * @param <T> the type of input elements to the reduction operation
192 * @param <A> the mutable accumulation type of the reduction operation (often
193 * hidden as an implementation detail)
194 * @param <R> the result type of the reduction operation
195 * @since 1.8
196 */
197 public interface Collector<T, A, R> {
198 /**
199 * A function that creates and returns a new mutable result container.
200 *
201 * @return a function which returns a new, mutable result container
202 */
203 Supplier<A> supplier();
204
205 /**
206 * A function that folds a value into a mutable result container.
207 *
208 * @return a function which folds a value into a mutable result container
209 */
210 BiConsumer<A, T> accumulator();
211
212 /**
213 * A function that accepts two partial results and merges them. The
214 * combiner function may fold state from one argument into the other and
215 * return that, or may return a new result container.
216 *
217 * @return a function which combines two partial results into a combined
218 * result
219 */
220 BinaryOperator<A> combiner();
221
222 /**
223 * Perform the final transformation from the intermediate accumulation type
224 * {@code A} to the final result type {@code R}.
225 *
244 * Returns a new {@code Collector} described by the given {@code supplier},
245 * {@code accumulator}, and {@code combiner} functions. The resulting
246 * {@code Collector} has the {@code Collector.Characteristics.IDENTITY_FINISH}
247 * characteristic.
248 *
249 * @param supplier The supplier function for the new collector
250 * @param accumulator The accumulator function for the new collector
251 * @param combiner The combiner 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 <R> The type of intermediate accumulation result, and final result,
256 * for the new collector
257 * @throws NullPointerException if any argument is null
258 * @return the new {@code Collector}
259 */
260 public static<T, R> Collector<T, R, R> of(Supplier<R> supplier,
261 BiConsumer<R, T> accumulator,
262 BinaryOperator<R> combiner,
263 Characteristics... characteristics) {
264 Objects.requireNonNull(supplier);
265 Objects.requireNonNull(accumulator);
266 Objects.requireNonNull(combiner);
267 Objects.requireNonNull(characteristics);
268 Set<Characteristics> cs = (characteristics.length == 0)
269 ? Collectors.CH_ID
270 : Collections.unmodifiableSet(EnumSet.of(Collector.Characteristics.IDENTITY_FINISH,
271 characteristics));
272 return new Collectors.CollectorImpl<>(supplier, accumulator, combiner, cs);
273 }
274
275 /**
276 * Returns a new {@code Collector} described by the given {@code supplier},
277 * {@code accumulator}, {@code combiner}, and {@code finisher} functions.
278 *
279 * @param supplier The supplier function for the new collector
280 * @param accumulator The accumulator function for the new collector
281 * @param combiner The combiner function for the new collector
282 * @param finisher The finisher function for the new collector
283 * @param characteristics The collector characteristics for the new
284 * collector
285 * @param <T> The type of input elements for the new collector
286 * @param <A> The intermediate accumulation type of the new collector
287 * @param <R> The final result type of the new collector
288 * @throws NullPointerException if any argument is null
289 * @return the new {@code Collector}
290 */
291 public static<T, A, R> Collector<T, A, R> of(Supplier<A> supplier,
292 BiConsumer<A, T> accumulator,
293 BinaryOperator<A> combiner,
294 Function<A, R> finisher,
295 Characteristics... characteristics) {
296 Objects.requireNonNull(supplier);
297 Objects.requireNonNull(accumulator);
298 Objects.requireNonNull(combiner);
299 Objects.requireNonNull(finisher);
300 Objects.requireNonNull(characteristics);
301 Set<Characteristics> cs = Collectors.CH_NOID;
302 if (characteristics.length > 0) {
303 cs = EnumSet.noneOf(Characteristics.class);
304 Collections.addAll(cs, characteristics);
305 cs = Collections.unmodifiableSet(cs);
306 }
307 return new Collectors.CollectorImpl<>(supplier, accumulator, combiner, finisher, cs);
308 }
309
310 /**
311 * Characteristics indicating properties of a {@code Collector}, which can
312 * be used to optimize reduction implementations.
313 */
314 enum Characteristics {
315 /**
316 * Indicates that this collector is <em>concurrent</em>, meaning that
317 * the result container can support the accumulator function being
318 * called concurrently with the same result container from multiple
319 * threads.
320 *
321 * <p>If a {@code CONCURRENT} collector is not also {@code UNORDERED},
322 * then it should only be evaluated concurrently if applied to an
323 * unordered data source.
324 */
325 CONCURRENT,
326
327 /**
|
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.Objects;
30 import java.util.Set;
31 import java.util.function.*;
32
33 /**
34 * A <a href="package-summary.html#Reduction">mutable reduction operation</a> that
35 * accumulates input elements into a mutable result container, optionally transforming
36 * the accumulated result into a final representation after all input elements
37 * have been processed. Reduction operations can be performed either sequentially
38 * or in parallel.
39 *
40 * <p>Examples of mutable reduction operations include:
41 * accumulating elements into a {@code Collection}; concatenating
42 * strings using a {@code StringBuilder}; computing summary information about
43 * elements such as sum, min, max, or average; computing "pivot table" summaries
44 * such as "maximum valued transaction by seller", etc. The class {@link Collectors}
45 * provides implementations of many common mutable reductions.
46 *
47 * <p>A {@code Collector} is specified by four functions that work together to
48 * accumulate entries into a mutable result container, and optionally perform
49 * a final transform on the result. They are: <ul>
50 * <li>creation of a new result container ({@link #supplier()})</li>
51 * <li>incorporating a new data element into a result container ({@link #accumulator()})</li>
183 * }</pre>
184 *
185 * @see Stream#collect(Collector)
186 * @see Collectors
187 *
188 * @param <T> the type of input elements to the reduction operation
189 * @param <A> the mutable accumulation type of the reduction operation (often
190 * hidden as an implementation detail)
191 * @param <R> the result type of the reduction operation
192 * @since 1.8
193 */
194 public interface Collector<T, A, R> {
195 /**
196 * A function that creates and returns a new mutable result container.
197 *
198 * @return a function which returns a new, mutable result container
199 */
200 Supplier<A> supplier();
201
202 /**
203 * A function that creates and returns a new mutable result container,
204 * when applied with an initial capacity.
205 *
206 * @return a function which returns a new, mutable result container
207 */
208 default IntFunction<A> sizedSupplier() {
209 return ignored -> supplier().get();
210 }
211
212 /**
213 * A function that folds a value into a mutable result container.
214 *
215 * @return a function which folds a value into a mutable result container
216 */
217 BiConsumer<A, T> accumulator();
218
219 /**
220 * A function that accepts two partial results and merges them. The
221 * combiner function may fold state from one argument into the other and
222 * return that, or may return a new result container.
223 *
224 * @return a function which combines two partial results into a combined
225 * result
226 */
227 BinaryOperator<A> combiner();
228
229 /**
230 * Perform the final transformation from the intermediate accumulation type
231 * {@code A} to the final result type {@code R}.
232 *
251 * Returns a new {@code Collector} described by the given {@code supplier},
252 * {@code accumulator}, and {@code combiner} functions. The resulting
253 * {@code Collector} has the {@code Collector.Characteristics.IDENTITY_FINISH}
254 * characteristic.
255 *
256 * @param supplier The supplier function for the new collector
257 * @param accumulator The accumulator function for the new collector
258 * @param combiner The combiner function for the new collector
259 * @param characteristics The collector characteristics for the new
260 * collector
261 * @param <T> The type of input elements for the new collector
262 * @param <R> The type of intermediate accumulation result, and final result,
263 * for the new collector
264 * @throws NullPointerException if any argument is null
265 * @return the new {@code Collector}
266 */
267 public static<T, R> Collector<T, R, R> of(Supplier<R> supplier,
268 BiConsumer<R, T> accumulator,
269 BinaryOperator<R> combiner,
270 Characteristics... characteristics) {
271 return of(ignored -> supplier.get(), supplier, accumulator, combiner, characteristics);
272 }
273
274 /**
275 * Returns a new {@code Collector} described by the given {@code supplier},
276 * {@code accumulator}, {@code combiner}, and {@code finisher} functions.
277 *
278 * @param supplier The supplier function for the new collector
279 * @param accumulator The accumulator function for the new collector
280 * @param combiner The combiner function for the new collector
281 * @param finisher The finisher function for the new collector
282 * @param characteristics The collector characteristics for the new
283 * collector
284 * @param <T> The type of input elements for the new collector
285 * @param <A> The intermediate accumulation type of the new collector
286 * @param <R> The final result type of the new collector
287 * @throws NullPointerException if any argument is null
288 * @return the new {@code Collector}
289 */
290 public static<T, A, R> Collector<T, A, R> of(Supplier<A> supplier,
291 BiConsumer<A, T> accumulator,
292 BinaryOperator<A> combiner,
293 Function<A, R> finisher,
294 Characteristics... characteristics) {
295 return of(ignored -> supplier.get(), supplier, accumulator, combiner, finisher, characteristics);
296 }
297
298 /**
299 * Returns a new {@code Collector} described by the given {@code supplier},
300 * {@code accumulator}, {@code combiner}, and {@code finisher} functions.
301 *
302 * @param sizedSupplier The sized supplier function for the new collector
303 * @param supplier The supplier function for the new collector
304 * @param accumulator The accumulator function for the new collector
305 * @param combiner The combiner function for the new collector
306 * @param characteristics The collector characteristics for the new
307 * collector
308 * @param <T> The type of input elements for the new collector
309 * @param <A> The intermediate accumulation type of the new collector
310 * @param <R> The final result type of the new collector
311 * @throws NullPointerException if any argument is null
312 * @return the new {@code Collector}
313 */
314 public static<T, A, R> Collector<T, A, R> of(IntFunction<A> sizedSupplier,
315 Supplier<A> supplier,
316 BiConsumer<A, T> accumulator,
317 BinaryOperator<A> combiner,
318 Characteristics... characteristics) {
319 Objects.requireNonNull(sizedSupplier);
320 Objects.requireNonNull(supplier);
321 Objects.requireNonNull(accumulator);
322 Objects.requireNonNull(combiner);
323 Objects.requireNonNull(characteristics);
324 Set<Characteristics> cs = (characteristics.length == 0)
325 ? Collectors.CH_ID
326 : Collections.unmodifiableSet(EnumSet.of(Collector.Characteristics.IDENTITY_FINISH,
327 characteristics));
328 return new Collectors.CollectorImpl<>(sizedSupplier, supplier, accumulator, combiner, cs);
329 }
330
331 /**
332 * Returns a new {@code Collector} described by the given {@code supplier},
333 * {@code accumulator}, {@code combiner}, and {@code finisher} functions.
334 *
335 * @param sizedSupplier The sized supplier function for the new collector
336 * @param supplier The supplier function for the new collector
337 * @param accumulator The accumulator function for the new collector
338 * @param combiner The combiner function for the new collector
339 * @param finisher The finisher function for the new collector
340 * @param characteristics The collector characteristics for the new
341 * collector
342 * @param <T> The type of input elements for the new collector
343 * @param <A> The intermediate accumulation type of the new collector
344 * @param <R> The final result type of the new collector
345 * @throws NullPointerException if any argument is null
346 * @return the new {@code Collector}
347 */
348 public static<T, A, R> Collector<T, A, R> of(IntFunction<A> sizedSupplier,
349 Supplier<A> supplier,
350 BiConsumer<A, T> accumulator,
351 BinaryOperator<A> combiner,
352 Function<A, R> finisher,
353 Characteristics... characteristics) {
354 Objects.requireNonNull(sizedSupplier);
355 Objects.requireNonNull(supplier);
356 Objects.requireNonNull(accumulator);
357 Objects.requireNonNull(combiner);
358 Objects.requireNonNull(finisher);
359 Objects.requireNonNull(characteristics);
360 Set<Characteristics> cs = Collectors.CH_NOID;
361 if (characteristics.length > 0) {
362 cs = EnumSet.noneOf(Characteristics.class);
363 Collections.addAll(cs, characteristics);
364 cs = Collections.unmodifiableSet(cs);
365 }
366 return new Collectors.CollectorImpl<>(sizedSupplier, supplier, accumulator, combiner, finisher, cs);
367 }
368
369 /**
370 * Characteristics indicating properties of a {@code Collector}, which can
371 * be used to optimize reduction implementations.
372 */
373 enum Characteristics {
374 /**
375 * Indicates that this collector is <em>concurrent</em>, meaning that
376 * the result container can support the accumulator function being
377 * called concurrently with the same result container from multiple
378 * threads.
379 *
380 * <p>If a {@code CONCURRENT} collector is not also {@code UNORDERED},
381 * then it should only be evaluated concurrently if applied to an
382 * unordered data source.
383 */
384 CONCURRENT,
385
386 /**
|