src/share/classes/java/util/function/package-info.java

Print this page
rev 7675 : 8019840: Spec updates for java.util.function
Reviewed-by: mduigou
Contributed-by: brian.goetz@oracle.com
   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 method

  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:
  32  *
  33  * <pre>{@code

  34  *     Predicate<String> p = String::isEmpty;
  35  *

  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  *
  54  * <ul>
  55  *     <li>There are several basic function shapes, including {@link java.util.function.Function} ({@code T -> R}),
  56  *     {@link java.util.function.Consumer} ({@code T -> void}),
  57  *     {@link java.util.function.Predicate} ({@code T -> boolean}),
  58  *     and {@link java.util.function.Supplier} ({@code () -> T}).

  59  *     </li>
  60  *     <li>Function shapes have a natural arity based on how they are most commonly used.
  61  *     The basic shapes can be modified by an arity prefix to indicate a different arity,
  62  *     such as {@link java.util.function.BiFunction} ({@code (T, U) -> R}).



  63  *     </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>
  79  * </ul>
  80  *
  81  * @see java.lang.FunctionalInterface
  82  */
  83 package java.util.function;
   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;