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,7 +1,7 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2012, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this

@@ -23,60 +23,86 @@
  * questions.
  */
 
 /**
  * <em>Functional interfaces</em> provide target types for lambda expressions
- * and method references.  Each functional interface has a single abstract method
+ * and method references.  Each functional interface has a single abstract
+ * method, called the <em>functional method</em> for that functional interface,
  * to which the lambda expression's parameter and return types are matched or
- * adapted.  Functional interfaces can provide a target type in multiple contexts,
- * such as assignment context, method invocation, or cast context:
+ * adapted.  Functional interfaces can provide a target type in multiple
+ * contexts, such as assignment context, method invocation, or cast context:
  *
  * <pre>{@code
+ *     // Assignment context
  *     Predicate<String> p = String::isEmpty;
  *
+ *     // Method invocation context
  *     stream.filter(e -> e.getSize() > 10)...
  *
+ *     // Cast context
  *     stream.map((ToIntFunction) e -> e.getSize())...
  * }</pre>
  *
- * <p>The interfaces in this package are functional interfaces used by the JDK,
- * and are available to be used by user code as well.  While they do not identify
- * a complete set of function shapes to which lambda expressions might be adapted,
- * they provide enough to cover common requirements.
- *
- * <p>The interfaces in this package are annotated with @{link FunctionalInterface}.
- * This annotation is not a requirement for the compiler to recognize an interface
- * as a functional interface, but merely an aid to capture design intent and enlist the
- * help of the compiler in identifying accidental violations of design intent.
+ * <p>The interfaces in this package are general purpose functional interfaces
+ * used by the JDK, and are available to be used by user code as well.  While
+ * they do not identify a complete set of function shapes to which lambda
+ * expressions might be adapted, they provide enough to cover common
+ * requirements. Other functional interfaces provided for specific purposes,
+ * such as {@link java.io.FileFilter}, are defined in the packages where they
+ * are used.
+ *
+ * <p>The interfaces in this package are annotated with
+ * {@link java.lang.FunctionalInterface}. This annotation is not a requirement
+ * for the compiler to recognize an interface as a functional interface, but
+ * merely an aid to capture design intent and enlist the help of the compiler in
+ * identifying accidental violations of design intent.
+ *
+ * <p>Functional interfaces often represent abstract concepts like functions,
+ * actions, or predicates.  In documenting functional interfaces, or referring
+ * to variables typed as functional interfaces, it is common to refer directly
+ * to those abstract concepts, for example using "this function" instead of
+ * "the function represented by this object".
  *
- * <p>The functional interfaces in this package follow an extensible naming convention,
- * as follows:
+ * <p>The functional interfaces in this package follow an extensible naming
+ * convention, as follows:
  *
  * <ul>
- *     <li>There are several basic function shapes, including {@link java.util.function.Function} ({@code T -> R}),
- *     {@link java.util.function.Consumer} ({@code T -> void}),
- *     {@link java.util.function.Predicate} ({@code T -> boolean}),
- *     and {@link java.util.function.Supplier} ({@code () -> T}).
+ *     <li>There are several basic function shapes, including
+ *     {@link java.util.function.Function} (unary function from {@code T} to {@code R}),
+ *     {@link java.util.function.Consumer} (unary function from {@code T} to {@code void}),
+ *     {@link java.util.function.Predicate} (unary function from {@code T} to {@code boolean}),
+ *     and {@link java.util.function.Supplier} (nilary function to {@code R}).
  *     </li>
- *     <li>Function shapes have a natural arity based on how they are most commonly used.
- *     The basic shapes can be modified by an arity prefix to indicate a different arity,
- *     such as {@link java.util.function.BiFunction} ({@code (T, U) -> R}).
+ *
+ *     <li>Function shapes have a natural arity based on how they are most
+ *     commonly used.  The basic shapes can be modified by an arity prefix to
+ *     indicate a different arity, such as
+ *     {@link java.util.function.BiFunction} (binary function from {@code T} and
+ *     {@code U} to {@code R}).
  *     </li>
- *     <li>There are additional derived function shapes which extend the basic function
- *     shapes, including {@link java.util.function.UnaryOperator} (extends {@code Function}) and
- *     {@link java.util.function.BinaryOperator} (extends {@code BiFunction}).
+ *
+ *     <li>There are additional derived function shapes which extend the basic
+ *     function shapes, including {@link java.util.function.UnaryOperator}
+ *     (extends {@code Function}) and {@link java.util.function.BinaryOperator}
+ *     (extends {@code BiFunction}).
  *     </li>
- *     <li>Type parameters of functional interfaces can be specialized to primitives with
- *     additional type prefixes.  To specialize the return type for a type that has both
- *     generic return type and generic arguments, we prefix {@code ToXxx}, as in
- *     {@link java.util.function.ToIntFunction}.  Otherwise, type arguments are specialized left-to-right,
- *     as in {@link java.util.function.DoubleConsumer} or {@link java.util.function.ObjIntConsumer}.
- *     (The type prefix {@code Obj} is used to indicate that we don't want to specialize this parameter,
- *     but want to move on to the next parameter.)  These schemes can be combined as in {@code IntToDoubleFunction}.
+ *
+ *     <li>Type parameters of functional interfaces can be specialized to
+ *     primitives with additional type prefixes.  To specialize the return type
+ *     for a type that has both generic return type and generic arguments, we
+ *     prefix {@code ToXxx}, as in {@link java.util.function.ToIntFunction}.
+ *     Otherwise, type arguments are specialized left-to-right, as in
+ *     {@link java.util.function.DoubleConsumer}
+ *     or {@link java.util.function.ObjIntConsumer}.
+ *     (The type prefix {@code Obj} is used to indicate that we don't want to
+ *     specialize this parameter, but want to move on to the next parameter,
+ *     as in {@link java.util.function.ObjIntConsumer}.)
+ *     These schemes can be combined, as in {@code IntToDoubleFunction}.
  *     </li>
- *     <li>If there are specialization prefixes for all arguments, the arity prefix may be left
- *     out (as in {@link java.util.function.ObjIntConsumer}).
+ *
+ *     <li>If there are specialization prefixes for all arguments, the arity
+ *     prefix may be left out (as in {@link java.util.function.ObjIntConsumer}).
  *     </li>
  * </ul>
  *
  * @see java.lang.FunctionalInterface
  */