changeset 7342:86f7db98577e

cleanups prior to review phase.
author mduigou
date Fri, 15 Feb 2013 17:17:09 -0800
parents 5e5e9f1bed16
children 07984401133f
files src/share/classes/java/util/Optional.java
diffstat 1 files changed, 44 insertions(+), 19 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/Optional.java	Thu Feb 14 17:15:01 2013 -0800
+++ b/src/share/classes/java/util/Optional.java	Fri Feb 15 17:17:09 2013 -0800
@@ -28,13 +28,17 @@
 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 successfully.
- * Additional methods that depend on presence or absence are provided, such as {@code orElse()}
- * (return a default value if not present) or {@code ifPresent()} (execute a block of code if
- * the value is present.)
+ * 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.
  *
- * @author Brian Goetz
+ * <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
+ * {@link #ifPresent(java.util.function.Consumer) ifPresent()} (execute a block
+ * of code if the value is present.)
+ *
+ * @since 1.8
  */
 public final class Optional<T> {
     /**
@@ -43,22 +47,34 @@
     private final static Optional<?> EMPTY = new Optional<>();
 
     /**
-     * If non-null, the value; if null, incdicates no value is present
+     * If non-null, the value; if null, indicates no value is present
      */
     private final T value;
 
+    /**
+     * Construct an instance with a non-null value.
+     *
+     * @param value a non-null value.
+     */
     private Optional(T value) {
         this.value = Objects.requireNonNull(value);
     }
 
+    /**
+     * Construct an empty instance.
+     *
+     * @implNote generally only one empty instance, {@link Optional#EMPTY},
+     * should exist per VM.
+     */
     private Optional() {
+        // assert this == Optional.EMPTY : "Superfluous empty Optional creation";
         this.value = null;
     }
 
     /**
-     * An empty object.
+     * Return an empty object. No value is present for this Optional.
      *
-     * Note: Though it may be tempting to do so, avoid testing if an object
+     * @apiNote Though it may be tempting to do so, avoid testing if an object
      * is empty by comparing with {@code ==} against instances returned
      * {@code Option.empty()}. There is no guarantee that it is a singleton.
      * Instead, use {@code isPresent()}.
@@ -72,18 +88,22 @@
     }
 
     /**
-     * Create a new Optional with a present value
-     * @param value The value, must be non-null
+     * Create a new Optional with a present value.
+     *
+     * @param value The value, must be non-null.
+     * @param a new Optional with a present value.
      */
     public static <T> Optional<T> of(T value) {
         return new Optional<>(value);
     }
 
     /**
-     * Returns the value held by this object.
+     * If a value is present in this Optional then returns the value.
      *
      * @return the value of this object.
      * @throws NoSuchElementException if there is no value present.
+     *
+     * @see Optional#isPresent()
      */
     public T get() {
         if (value == null) {
@@ -94,6 +114,7 @@
 
     /**
      * 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() {
@@ -101,7 +122,7 @@
     }
 
     /**
-     * Execute the specified block with the value if a value is present
+     * Execute the specified block with the value if a value is present.
      */
     public void ifPresent(Consumer<? super T> consumer) {
         if (value != null)
@@ -112,7 +133,7 @@
      * 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 return {@code other}.
+     * @return the value, if present, otherwise {@code other}.
      */
     public T orElse(T other) {
         return value != null ? value : other;
@@ -121,7 +142,8 @@
     /**
      * Return the value if present otherwise return result of {@code other}.
      *
-     * @param other Supplier who's result is returned if there is no value present.
+     * @param other 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) {
@@ -170,18 +192,21 @@
 
     @Override
     public boolean equals(Object o) {
-        if (this == o)
+        if (this == o) {
             return true;
-        else if (o == null || getClass() != o.getClass())
+        }
+
+        if (!(o instanceof Optional)) {
             return false;
+        }
 
         Optional other = (Optional) o;
-        return (value == null) ? (other.value == null) : value.equals(other.value);
+        return Objects.equals(value, other.value);
     }
 
     @Override
     public int hashCode() {
-        return value != null ? value.hashCode() : 0;
+        return Objects.hashCode(value);
     }
 
     @Override