1 /* 2 * Copyright (c) 2010, 2011, 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.functions; 26 27 /** 28 * Reduce an input object by combining with a base object. 29 * 30 * <p>All reducer implementations are expected to: 31 * <ul> 32 * <li>Provide stable results such that for any {@code a} and {@code b} the 33 * result of two {@code reduce} operations are always equivalent. ie.<pre> 34 * Foo one = reducer.reduce(a,b); 35 * Foo two = reducer.reduce(a,b); 36 * 37 * assert one.equals(two) && two.equals(one); 38 * </pre></li> 39 * <li>The reducer should not modify the input object in any way that would 40 * change the result.</li> 41 * <li>When used for aggregate operations upon many elements reducers 42 * should not assume that the {@code reduce} operation will be called upon 43 * elements in any specific orderie.<pre> 44 * Foo one = reducer.reduce(a,reducer.reduce(b,c)); 45 * Foo two = reducer.reduce(b,reducer.reduce(a,c)); 46 * 47 * assert one.equals(two) && two.equals(one); 48 * </pre>/li> 49 * </ul> 50 51 * @param <T> the type of input objects provided to {@code reduce}. 52 * @param <U> the type of the base value and output objects from {@code reduce}. 53 * This may be the same type as {@code <T>}. 54 */ 55 public interface Reducer<T, U> { 56 57 /** 58 * Produce a reduced output using the provided input and base objects. 59 * 60 * @param base the reduction base. 61 * @param t the input object. 62 * @return reduced output. 63 */ 64 U reduce(U base, T t); 65 66 /** 67 * Returns a reducer which conditionally performs reduce on the input from 68 * {@code <U>} to {@code <T>}. The reduce is only performed if the provided 69 * predicate returns {@code true} for the input {@code <U>}. 70 * @param predicate A Predicate for {@code <U>} values. 71 * @return A reducer which conditionally performing reduction from {@code <U>} to 72 * {@code <T>} if the {@code <U>} input value satisfies a predicate. 73 */ 74 Reducer<T, U> compose(Predicate<? super T> predicate) default Reducers.compose; 75 76 /** 77 * Returns a reducer which performs a mapping of inputs from {@code <V>} to 78 * {@code <T>} before reducing to the result. 79 * @param <V> Type of input objects. 80 * @param mapper A mapper from {@code <V>} to {@code <U>}. 81 * @return A reducer which performing a mapping from {@code <U>} to 82 * {@code <V>}prior to reducing from {@code <U>} to {@code <T>}. 83 */ 84 <V> Reducer<V, U> compose(Mapper<? super V, ? extends T> mapper) default Reducers.compose; 85 }