1607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller/* 2607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved. 3607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 5607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * This code is free software; you can redistribute it and/or modify it 6607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * under the terms of the GNU General Public License version 2 only, as 7607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * published by the Free Software Foundation. Oracle designates this 8607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * particular file as subject to the "Classpath" exception as provided 9607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * by Oracle in the LICENSE file that accompanied this code. 10607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 11607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * This code is distributed in the hope that it will be useful, but WITHOUT 12607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * version 2 for more details (a copy is included in the LICENSE file that 15607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * accompanied this code). 16607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 17607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * You should have received a copy of the GNU General Public License version 18607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 2 along with this work; if not, write to the Free Software Foundation, 19607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 21607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * or visit www.oracle.com if you need additional information or have any 23607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * questions. 24607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller */ 25607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller 26607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller/** 27607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * <em>Functional interfaces</em> provide target types for lambda expressions 28607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * and method references. Each functional interface has a single abstract 29607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * method, called the <em>functional method</em> for that functional interface, 30607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * to which the lambda expression's parameter and return types are matched or 31607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * adapted. Functional interfaces can provide a target type in multiple 32607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * contexts, such as assignment context, method invocation, or cast context: 33607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 34607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * <pre>{@code 35607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * // Assignment context 36607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * Predicate<String> p = String::isEmpty; 37607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 38607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * // Method invocation context 39607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * stream.filter(e -> e.getSize() > 10)... 40607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 41607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * // Cast context 42607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * stream.map((ToIntFunction) e -> e.getSize())... 43607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * }</pre> 44607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 45607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * <p>The interfaces in this package are general purpose functional interfaces 46607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * used by the JDK, and are available to be used by user code as well. While 47607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * they do not identify a complete set of function shapes to which lambda 48607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * expressions might be adapted, they provide enough to cover common 49607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * requirements. Other functional interfaces provided for specific purposes, 50607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * such as {@link java.io.FileFilter}, are defined in the packages where they 51607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * are used. 52607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 53607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * <p>The interfaces in this package are annotated with 54607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * {@link java.lang.FunctionalInterface}. This annotation is not a requirement 55607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * for the compiler to recognize an interface as a functional interface, but 56607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * merely an aid to capture design intent and enlist the help of the compiler in 57607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * identifying accidental violations of design intent. 58607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 59607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * <p>Functional interfaces often represent abstract concepts like functions, 60607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * actions, or predicates. In documenting functional interfaces, or referring 61607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * to variables typed as functional interfaces, it is common to refer directly 62607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * to those abstract concepts, for example using "this function" instead of 63607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * "the function represented by this object". When an API method is said to 64607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * accept or return a functional interface in this manner, such as "applies the 65607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * provided function to...", this is understood to mean a <i>non-null</i> 66607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * reference to an object implementing the appropriate functional interface, 67607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * unless potential nullity is explicitly specified. 68607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 69607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * <p>The functional interfaces in this package follow an extensible naming 70607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * convention, as follows: 71607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 72607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * <ul> 73607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * <li>There are several basic function shapes, including 74607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * {@link java.util.function.Function} (unary function from {@code T} to {@code R}), 75607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * {@link java.util.function.Consumer} (unary function from {@code T} to {@code void}), 76607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * {@link java.util.function.Predicate} (unary function from {@code T} to {@code boolean}), 77607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * and {@link java.util.function.Supplier} (nilary function to {@code R}). 78607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * </li> 79607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 80607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * <li>Function shapes have a natural arity based on how they are most 81607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * commonly used. The basic shapes can be modified by an arity prefix to 82607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * indicate a different arity, such as 83607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * {@link java.util.function.BiFunction} (binary function from {@code T} and 84607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * {@code U} to {@code R}). 85607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * </li> 86607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 87607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * <li>There are additional derived function shapes which extend the basic 88607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * function shapes, including {@link java.util.function.UnaryOperator} 89607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * (extends {@code Function}) and {@link java.util.function.BinaryOperator} 90607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * (extends {@code BiFunction}). 91607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * </li> 92607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 93607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * <li>Type parameters of functional interfaces can be specialized to 94607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * primitives with additional type prefixes. To specialize the return type 95607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * for a type that has both generic return type and generic arguments, we 96607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * prefix {@code ToXxx}, as in {@link java.util.function.ToIntFunction}. 97607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * Otherwise, type arguments are specialized left-to-right, as in 98607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * {@link java.util.function.DoubleConsumer} 99607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * or {@link java.util.function.ObjIntConsumer}. 100607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * (The type prefix {@code Obj} is used to indicate that we don't want to 101607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * specialize this parameter, but want to move on to the next parameter, 102607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * as in {@link java.util.function.ObjIntConsumer}.) 103607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * These schemes can be combined, as in {@code IntToDoubleFunction}. 104607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * </li> 105607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 106607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * <li>If there are specialization prefixes for all arguments, the arity 107607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * prefix may be left out (as in {@link java.util.function.ObjIntConsumer}). 108607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * </li> 109607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * </ul> 110607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * 111607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * @see java.lang.FunctionalInterface 112607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller * @since 1.8 113607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fuller */ 114607050af5a16c46ae53ff4d2c3f47b4ef694b559Neil Fullerpackage java.util.function; 115