< prev index next >

src/java.base/share/classes/java/util/Optional.java

Print this page




  44  *
  45  * <p>This is a <a href="../lang/doc-files/ValueBased.html">value-based</a>
  46  * class; use of identity-sensitive operations (including reference equality
  47  * ({@code ==}), identity hash code, or synchronization) on instances of
  48  * {@code Optional} may have unpredictable results and should be avoided.
  49  *
  50  * @apiNote
  51  * {@code Optional} is primarily intended for use as a method return type where
  52  * there is a clear need to represent "no result," and where using {@code null}
  53  * is likely to cause errors. A variable whose type is {@code Optional} should
  54  * never itself be {@code null}; it should always point to an {@code Optional}
  55  * instance.
  56  *
  57  * @param <T> the type of value
  58  * @since 1.8
  59  */
  60 public final class Optional<T> {
  61     /**
  62      * Common instance for {@code empty()}.
  63      */
  64     private static final Optional<?> EMPTY = new Optional<>(null);
  65 
  66     /**
  67      * If non-null, the value; if null, indicates no value is present
  68      */
  69     private final T value;
  70 
  71     /**










  72      * Returns an empty {@code Optional} instance.  No value is present for this
  73      * {@code Optional}.
  74      *
  75      * @apiNote
  76      * Though it may be tempting to do so, avoid testing if an object is empty
  77      * by comparing with {@code ==} against instances returned by
  78      * {@code Optional.empty()}.  There is no guarantee that it is a singleton.
  79      * Instead, use {@link #isPresent()}.
  80      *
  81      * @param <T> The type of the non-existent value
  82      * @return an empty {@code Optional}
  83      */
  84     public static<T> Optional<T> empty() {
  85         @SuppressWarnings("unchecked")
  86         Optional<T> t = (Optional<T>) EMPTY;
  87         return t;
  88     }
  89 
  90     /**
  91      * Constructs an instance with the described value.
  92      *
  93      * @param value the value to describe; it's the caller's responsibility to
  94      *        ensure the value is non-{@code null} unless creating the singleton
  95      *        instance returned by {@code empty()}.
  96      */
  97     private Optional(T value) {
  98         this.value = value;
  99     }
 100 
 101     /**
 102      * Returns an {@code Optional} describing the given non-{@code null}
 103      * value.
 104      *
 105      * @param value the value to describe, which must be non-{@code null}
 106      * @param <T> the type of the value
 107      * @return an {@code Optional} with the value present
 108      * @throws NullPointerException if value is {@code null}
 109      */
 110     public static <T> Optional<T> of(T value) {
 111         return new Optional<>(Objects.requireNonNull(value));
 112     }
 113 
 114     /**
 115      * Returns an {@code Optional} describing the given value, if
 116      * non-{@code null}, otherwise returns an empty {@code Optional}.
 117      *
 118      * @param value the possibly-{@code null} value to describe
 119      * @param <T> the type of the value
 120      * @return an {@code Optional} with a present value if the specified value
 121      *         is non-{@code null}, otherwise an empty {@code Optional}
 122      */
 123     @SuppressWarnings("unchecked")
 124     public static <T> Optional<T> ofNullable(T value) {
 125         return value == null ? (Optional<T>) EMPTY
 126                              : new Optional<>(value);
 127     }
 128 
 129     /**
 130      * If a value is present, returns the value, otherwise throws
 131      * {@code NoSuchElementException}.
 132      *
 133      * @apiNote
 134      * The preferred alternative to this method is {@link #orElseThrow()}.
 135      *
 136      * @return the non-{@code null} value described by this {@code Optional}
 137      * @throws NoSuchElementException if no value is present
 138      */
 139     public T get() {
 140         if (value == null) {
 141             throw new NoSuchElementException("No value present");
 142         }
 143         return value;
 144     }
 145 
 146     /**




  44  *
  45  * <p>This is a <a href="../lang/doc-files/ValueBased.html">value-based</a>
  46  * class; use of identity-sensitive operations (including reference equality
  47  * ({@code ==}), identity hash code, or synchronization) on instances of
  48  * {@code Optional} may have unpredictable results and should be avoided.
  49  *
  50  * @apiNote
  51  * {@code Optional} is primarily intended for use as a method return type where
  52  * there is a clear need to represent "no result," and where using {@code null}
  53  * is likely to cause errors. A variable whose type is {@code Optional} should
  54  * never itself be {@code null}; it should always point to an {@code Optional}
  55  * instance.
  56  *
  57  * @param <T> the type of value
  58  * @since 1.8
  59  */
  60 public final class Optional<T> {
  61     /**
  62      * Common instance for {@code empty()}.
  63      */
  64     private static final Optional<?> EMPTY = new Optional<>();
  65 
  66     /**
  67      * If non-null, the value; if null, indicates no value is present
  68      */
  69     private final T value;
  70 
  71     /**
  72      * Constructs an empty instance.
  73      *
  74      * @implNote Generally only one empty instance, {@link Optional#EMPTY},
  75      * should exist per VM.
  76      */
  77     private Optional() {
  78         this.value = null;
  79     }
  80 
  81     /**
  82      * Returns an empty {@code Optional} instance.  No value is present for this
  83      * {@code Optional}.
  84      *
  85      * @apiNote
  86      * Though it may be tempting to do so, avoid testing if an object is empty
  87      * by comparing with {@code ==} against instances returned by
  88      * {@code Optional.empty()}.  There is no guarantee that it is a singleton.
  89      * Instead, use {@link #isPresent()}.
  90      *
  91      * @param <T> The type of the non-existent value
  92      * @return an empty {@code Optional}
  93      */
  94     public static<T> Optional<T> empty() {
  95         @SuppressWarnings("unchecked")
  96         Optional<T> t = (Optional<T>) EMPTY;
  97         return t;
  98     }
  99 
 100     /**
 101      * Constructs an instance with the described value.
 102      *
 103      * @param value the non-{@code null} value to describe
 104      * @throws NullPointerException if value is {@code null}

 105      */
 106     private Optional(T value) {
 107         this.value = Objects.requireNonNull(value);
 108     }
 109 
 110     /**
 111      * Returns an {@code Optional} describing the given non-{@code null}
 112      * value.
 113      *
 114      * @param value the value to describe, which must be non-{@code null}
 115      * @param <T> the type of the value
 116      * @return an {@code Optional} with the value present
 117      * @throws NullPointerException if value is {@code null}
 118      */
 119     public static <T> Optional<T> of(T value) {
 120         return new Optional<>(value);
 121     }
 122 
 123     /**
 124      * Returns an {@code Optional} describing the given value, if
 125      * non-{@code null}, otherwise returns an empty {@code Optional}.
 126      *
 127      * @param value the possibly-{@code null} value to describe
 128      * @param <T> the type of the value
 129      * @return an {@code Optional} with a present value if the specified value
 130      *         is non-{@code null}, otherwise an empty {@code Optional}
 131      */

 132     public static <T> Optional<T> ofNullable(T value) {
 133         return value == null ? empty() : of(value);

 134     }
 135 
 136     /**
 137      * If a value is present, returns the value, otherwise throws
 138      * {@code NoSuchElementException}.
 139      *
 140      * @apiNote
 141      * The preferred alternative to this method is {@link #orElseThrow()}.
 142      *
 143      * @return the non-{@code null} value described by this {@code Optional}
 144      * @throws NoSuchElementException if no value is present
 145      */
 146     public T get() {
 147         if (value == null) {
 148             throw new NoSuchElementException("No value present");
 149         }
 150         return value;
 151     }
 152 
 153     /**


< prev index next >