changeset 7354:493df51924c8

Spec fixes in Optional
author briangoetz
date Tue, 19 Feb 2013 15:30:02 -0500
parents 698e5c0c020a
children 36482d2671d6
files src/share/classes/java/util/Optional.java
diffstat 1 files changed, 27 insertions(+), 24 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/Optional.java	Tue Feb 19 12:02:54 2013 -0800
+++ b/src/share/classes/java/util/Optional.java	Tue Feb 19 15:30:02 2013 -0500
@@ -28,13 +28,13 @@
 import java.util.function.Supplier;
 
 /**
- * A return object which may or may not contain a non-null value. If a value is
- * present then {@code isPresent()} will return {@code true} and {@code get()}
- * will return the value.
+ * A container object which may or may not contain a non-null value.
+ * If a value is present, {@code isPresent()} will return {@code true}
+ * and {@code get()} will return the value.
  *
- * <p/>Additional methods that depend on presence or absence are provided, such
- * as {@link #orElse(java.lang.Object) orElse()} (return a default value if
- * value not present) and
+ * <p>Additional methods that depend on the presence or absence of a contained
+ * value are provided, such as {@link #orElse(java.lang.Object) orElse()} (return
+ * a default value if value not present) and
  * {@link #ifPresent(java.util.function.Consumer) ifPresent()} (execute a block
  * of code if the value is present.)
  *
@@ -67,12 +67,11 @@
      * should exist per VM.
      */
     private Optional() {
-        // assert this == Optional.EMPTY : "Superfluous empty Optional creation";
         this.value = null;
     }
 
     /**
-     * Return an empty object. No value is present for this Optional.
+     * Return an empty {@code Optional}.  No value is present for this Optional.
      *
      * @apiNote Though it may be tempting to do so, avoid testing if an object
      * is empty by comparing with {@code ==} against instances returned
@@ -80,7 +79,7 @@
      * Instead, use {@code isPresent()}.
      *
      * @param <T> Type of the non-existent value.
-     * @return an empty object.
+     * @return an empty {@code Optional}.
      */
     @SuppressWarnings("unchecked")
     public static<T> Optional<T> empty() {
@@ -88,19 +87,20 @@
     }
 
     /**
-     * Create a new Optional with a present value.
+     * Create a new {@code Optional} with a present value.
      *
      * @param value The value, must be non-null.
-     * @param a new Optional with a present value.
+     * @param value new {@code Optional} with a present value.
      */
     public static <T> Optional<T> of(T value) {
         return new Optional<>(value);
     }
 
     /**
-     * If a value is present in this Optional then returns the value.
+     * If a value is present in this {@code Optional}, returns the value, otherwise
+     * throws {@code NoSuchElementException}.
      *
-     * @return the value of this object.
+     * @return the value held by this {@code Optional}.
      * @throws NoSuchElementException if there is no value present.
      *
      * @see Optional#isPresent()
@@ -113,16 +113,17 @@
     }
 
     /**
-     * Return {@code true} if there is a value present otherwise {@code false}.
+     * Return {@code true} if there is a value present, otherwise {@code false}.
      *
-     * @return {@code true} if there is a value present otherwise {@code false}.
+     * @return {@code true} if there is a value present, otherwise {@code false}.
      */
     public boolean isPresent() {
         return value != null;
     }
 
     /**
-     * Execute the specified block with the value if a value is present.
+     * Execute the specified block with the value if a value is present, otherwise
+     * do nothing.
      */
     public void ifPresent(Consumer<? super T> consumer) {
         if (value != null)
@@ -130,7 +131,7 @@
     }
 
     /**
-     * Return the value if present otherwise return {@code other}.
+     * Return the value if present, otherwise return {@code other}.
      *
      * @param other value to be returned if there is no value present.
      * @return the value, if present, otherwise {@code other}.
@@ -140,19 +141,20 @@
     }
 
     /**
-     * Return the value if present otherwise return result of {@code other}.
+     * Return the value if present, otherwise invoke {@code other} and return
+     * the result of that invocation.
      *
-     * @param other Supplier who's result is returned if there is no value
+     * @param other {@code Supplier} who's result is returned if there is no value
      * present.
      * @return the value if present otherwise return result of {@code other}.
      */
-    public T orElse(Supplier<T> other) {
+    public T orElseGet(Supplier<T> other) {
         return value != null ? value : other.get();
     }
 
     /**
-     * Return the value otherwise throw an exception to be created by the
-     * provided factory.
+     * Return the contained value, if present, otherwise throw an exception
+     * to be created by the provided factory.
      *
      * @param <V> Type of the exception to be thrown.
      * @param exceptionFactory The factory which will return the exception to
@@ -169,8 +171,9 @@
     }
 
     /**
-     * Return the value otherwise throw an exception of the provided class.
-     * Exception will be thrown with the message "No value present".
+     * Return the contained value, if present, otherwise throw an exception
+     * of the provided class.  Exception will be thrown with the message
+     * "No value present".
      *
      * @param <V> Type of the exception to be thrown.
      * @param exceptionClass The class if exception to be thrown. Must support