20 * |
20 * |
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
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 |
22 * or visit www.oracle.com if you need additional information or have any |
23 * questions. |
23 * questions. |
24 */ |
24 */ |
|
25 |
25 /** |
26 /** |
26 * <em>Functional interfaces</em> provide typing for lambda expressions. Each |
27 * <em>Functional interfaces</em> provide target types for lambda expressions |
27 * functional interface provides a single abstract method to which the lambda |
28 * and method references. Each functional interface has a single abstract method |
28 * expression's parameter and return types are matched. |
29 * to which the lambda expression's parameter and return types are matched or |
|
30 * adapted. Functional interfaces can provide a target type in multiple contexts, |
|
31 * such as assignment context, method invocation, or cast context: |
29 * |
32 * |
30 * <p>The interfaces in this package are all functional interfaces used with the |
33 * <pre> |
31 * collections and streams frameworks. The operation identified by each |
34 * Predicate<String> p = String::isEmpty; |
32 * interface is generally applied to a collection or stream of objects. |
|
33 * |
35 * |
34 * <p>All functional interface implementations are expected to ensure that: |
36 * stream.filter(e -> e.getSize() > 10)... |
|
37 * |
|
38 * stream.map((ToIntFunction) e -> e.getSize())... |
|
39 * </pre> |
|
40 * |
|
41 * <p>The interfaces in this package are functional interfaces used by the JDK, |
|
42 * and are available to be used by user code as well. While they do not identify |
|
43 * a complete set of function shapes to which lambda expressions might be adapted, |
|
44 * they provide enough to cover common requirements. |
|
45 * |
|
46 * <p>The interfaces in this package are annotated with @{link FunctionalInterface}. |
|
47 * This annotation is not a requirement for the compiler to recognize an interface |
|
48 * as a functional interface, but merely an aid to capture design intent and enlist the |
|
49 * help of the compiler in identifying accidental violations of design intent. |
|
50 * |
|
51 * <p>The functional interfaces in this package follow an extensible naming convention, |
|
52 * as follows: |
|
53 * |
35 * <ul> |
54 * <ul> |
36 * <li>When used for aggregate operations upon many elements it should not be |
55 * <li>There are several basic function shapes, including {@link java.util.function.Function} ({@code T -> R}), |
37 * assumed that the operation will be called upon elements in any specific order. |
56 * {@link java.util.function.Consumer} ({@code T -> void}), |
38 * </li> |
57 * {@link java.util.function.Predicate} ({@code T -> boolean}), |
39 * <li>{@code null} values are accepted and returned by these functional |
58 * and {@link java.util.function.Supplier} ({@code () -> T}). |
40 * interfaces according to the constraints of the specification in which the |
59 * </li> |
41 * functional interfaces are used. The functional interfaces themselves do not |
60 * <li>Function shapes have a natural arity based on how they are most commonly used. |
42 * constrain or mandate use of {@code null} values. Most usages of the |
61 * The basic shapes can be modified by an arity prefix to indicate a different arity, |
43 * functional interfaces will define the role, if any, of {@code null} for that |
62 * such as {@link java.util.function.BiFunction} ({@code (T, U) -> R}). |
44 * context. |
63 * </li> |
45 * </li> |
64 * <li>There are additional derived function shapes which extend the basic function |
|
65 * shapes, including {@link java.util.function.UnaryOperator} (extends {@code Function}) and |
|
66 * {@link java.util.function.BinaryOperator} (extends {@code BiFunction}). |
|
67 * </li> |
|
68 * <li>Type parameters of functional interfaces can be specialized to primitives with |
|
69 * additional type prefixes. To specialize the return type for a type that has both |
|
70 * generic return type and generic arguments, we prefix {@code ToXxx}, as in |
|
71 * {@link java.util.function.ToIntFunction}. Otherwise, type arguments are specialized left-to-right, |
|
72 * as in {@link java.util.function.DoubleConsumer} or {@link java.util.function.ObjIntConsumer}. |
|
73 * (The type prefix {@code Obj} is used to indicate that we don't want to specialize this parameter, |
|
74 * but want to move on to the next parameter.) These schemes can be combined as in {@code IntToDoubleFunction}. |
|
75 * </li> |
|
76 * <li>If there are specialization prefixes for all arguments, the arity prefix may be left |
|
77 * out (as in {@link java.util.function.ObjIntConsumer}). |
|
78 * </li> |
46 * </ul> |
79 * </ul> |
|
80 * |
|
81 * @see java.lang.FunctionalInterface |
47 */ |
82 */ |
48 package java.util.function; |
83 package java.util.function; |