1 /*

     2  * Copyright (c) 2011, 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 

    26 /**

    27  * <em>Functional interfaces</em> provide target types for lambda expressions

    28  * and method references.  Each functional interface has a single abstract

    29  * method, called the <em>functional method</em> for that functional interface,

    30  * to which the lambda expression's parameter and return types are matched or

    31  * adapted.  Functional interfaces can provide a target type in multiple

    32  * contexts, such as assignment context, method invocation, or cast context:

    33  *

    34  * <pre>{@code

    35  *     // Assignment context

    36  *     Predicate<String> p = String::isEmpty;

    37  *

    38  *     // Method invocation context

    39  *     stream.filter(e -> e.getSize() > 10)...

    40  *

    41  *     // Cast context

    42  *     stream.map((ToIntFunction) e -> e.getSize())...

    43  * }</pre>

    44  *

    45  * <p>The interfaces in this package are general purpose functional interfaces

    46  * used by the JDK, and are available to be used by user code as well.  While

    47  * they do not identify a complete set of function shapes to which lambda

    48  * expressions might be adapted, they provide enough to cover common

    49  * requirements. Other functional interfaces provided for specific purposes,

    50  * such as {@link java.io.FileFilter}, are defined in the packages where they

    51  * are used.

    52  *

    53  * <p>The interfaces in this package are annotated with

    54  * {@link java.lang.FunctionalInterface}. This annotation is not a requirement

    55  * for the compiler to recognize an interface as a functional interface, but

    56  * merely an aid to capture design intent and enlist the help of the compiler in

    57  * identifying accidental violations of design intent.

    58  *

    59  * <p>Functional interfaces often represent abstract concepts like functions,

    60  * actions, or predicates.  In documenting functional interfaces, or referring

    61  * to variables typed as functional interfaces, it is common to refer directly

    62  * to those abstract concepts, for example using "this function" instead of

    63  * "the function represented by this object".  When an API method is said to

    64  * accept or return a functional interface in this manner, such as "applies the

    65  * provided function to...", this is understood to mean a <i>non-null</i>

    66  * reference to an object implementing the appropriate functional interface,

    67  * unless potential nullity is explicitly specified.

    68  *

    69  * <p>The functional interfaces in this package follow an extensible naming

    70  * convention, as follows:

    71  *

    72  * <ul>

    73  *     <li>There are several basic function shapes, including

    74  *     {@link java.util.function.Function} (unary function from {@code T} to {@code R}),

    75  *     {@link java.util.function.Consumer} (unary function from {@code T} to {@code void}),

    76  *     {@link java.util.function.Predicate} (unary function from {@code T} to {@code boolean}),

    77  *     and {@link java.util.function.Supplier} (nilary function to {@code R}).

    78  *     </li>

    79  *

    80  *     <li>Function shapes have a natural arity based on how they are most

    81  *     commonly used.  The basic shapes can be modified by an arity prefix to

    82  *     indicate a different arity, such as

    83  *     {@link java.util.function.BiFunction} (binary function from {@code T} and

    84  *     {@code U} to {@code R}).

    85  *     </li>

    86  *

    87  *     <li>There are additional derived function shapes which extend the basic

    88  *     function shapes, including {@link java.util.function.UnaryOperator}

    89  *     (extends {@code Function}) and {@link java.util.function.BinaryOperator}

    90  *     (extends {@code BiFunction}).

    91  *     </li>

    92  *

    93  *     <li>Type parameters of functional interfaces can be specialized to

    94  *     primitives with additional type prefixes.  To specialize the return type

    95  *     for a type that has both generic return type and generic arguments, we

    96  *     prefix {@code ToXxx}, as in {@link java.util.function.ToIntFunction}.

    97  *     Otherwise, type arguments are specialized left-to-right, as in

    98  *     {@link java.util.function.DoubleConsumer}

    99  *     or {@link java.util.function.ObjIntConsumer}.

   100  *     (The type prefix {@code Obj} is used to indicate that we don't want to

   101  *     specialize this parameter, but want to move on to the next parameter,

   102  *     as in {@link java.util.function.ObjIntConsumer}.)

   103  *     These schemes can be combined, as in {@code IntToDoubleFunction}.

   104  *     </li>

   105  *

   106  *     <li>If there are specialization prefixes for all arguments, the arity

   107  *     prefix may be left out (as in {@link java.util.function.ObjIntConsumer}).

   108  *     </li>

   109  * </ul>

   110  *

   111  * @see java.lang.FunctionalInterface

   112  * @since 1.8

   113  */

   114 package java.util.function;