1 /*
2 * Copyright (c) 2011, 2012, 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".
64 *
65 * <p>The functional interfaces in this package follow an extensible naming
66 * convention, as follows:
67 *
68 * <ul>
69 * <li>There are several basic function shapes, including
70 * {@link java.util.function.Function} (unary function from {@code T} to {@code R}),
71 * {@link java.util.function.Consumer} (unary function from {@code T} to {@code void}),
72 * {@link java.util.function.Predicate} (unary function from {@code T} to {@code boolean}),
73 * and {@link java.util.function.Supplier} (nilary function to {@code R}).
74 * </li>
75 *
76 * <li>Function shapes have a natural arity based on how they are most
77 * commonly used. The basic shapes can be modified by an arity prefix to
78 * indicate a different arity, such as
79 * {@link java.util.function.BiFunction} (binary function from {@code T} and
80 * {@code U} to {@code R}).
81 * </li>
82 *
83 * <li>There are additional derived function shapes which extend the basic
84 * function shapes, including {@link java.util.function.UnaryOperator}
85 * (extends {@code Function}) and {@link java.util.function.BinaryOperator}
86 * (extends {@code BiFunction}).
87 * </li>
88 *
89 * <li>Type parameters of functional interfaces can be specialized to
90 * primitives with additional type prefixes. To specialize the return type
91 * for a type that has both generic return type and generic arguments, we
92 * prefix {@code ToXxx}, as in {@link java.util.function.ToIntFunction}.
93 * Otherwise, type arguments are specialized left-to-right, as in
94 * {@link java.util.function.DoubleConsumer}
95 * or {@link java.util.function.ObjIntConsumer}.
96 * (The type prefix {@code Obj} is used to indicate that we don't want to
97 * specialize this parameter, but want to move on to the next parameter,
98 * as in {@link java.util.function.ObjIntConsumer}.)
99 * These schemes can be combined, as in {@code IntToDoubleFunction}.
100 * </li>
101 *
102 * <li>If there are specialization prefixes for all arguments, the arity
103 * prefix may be left out (as in {@link java.util.function.ObjIntConsumer}).
104 * </li>
105 * </ul>
106 *
107 * @see java.lang.FunctionalInterface
108 */
109 package java.util.function;