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:

    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.

    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  *

    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>