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; 115
