29
30 import java.util.function.Consumer;
31 import java.util.function.Function;
32 import java.util.function.Predicate;
33 import java.util.function.Supplier;
34 import java.util.stream.Stream;
35
36 /**
37 * A container object which may or may not contain a non-{@code null} value.
38 * If a value is present, {@code isPresent()} returns {@code true}. If no
39 * value is present, the object is considered <i>empty</i> and
40 * {@code isPresent()} returns {@code false}.
41 *
42 * <p>Additional methods that depend on the presence or absence of a contained
43 * value are provided, such as {@link #orElse(Object) orElse()}
44 * (returns a default value if no value is present) and
45 * {@link #ifPresent(Consumer) ifPresent()} (performs an
46 * action if a value is present).
47 *
48 * <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
49 * class; programmers should treat instances that are
50 * {@linkplain #equals(Object) equal} as interchangeable and should not
51 * use instances for synchronization, or unpredictable behavior may
52 * occur. For example, in a future release, synchronization may fail.
53 *
54 * @apiNote
55 * {@code Optional} is primarily intended for use as a method return type where
56 * there is a clear need to represent "no result," and where using {@code null}
57 * is likely to cause errors. A variable whose type is {@code Optional} should
58 * never itself be {@code null}; it should always point to an {@code Optional}
59 * instance.
60 *
61 * @param <T> the type of value
62 * @since 1.8
63 */
64 @jdk.internal.ValueBased
65 public final class Optional<T> {
66 /**
67 * Common instance for {@code empty()}.
68 */
69 private static final Optional<?> EMPTY = new Optional<>(null);
70
71 /**
72 * If non-null, the value; if null, indicates no value is present
73 */
74 @Stable
75 private final T value;
76
77 /**
78 * Returns an empty {@code Optional} instance. No value is present for this
79 * {@code Optional}.
80 *
81 * @apiNote
82 * Though it may be tempting to do so, avoid testing if an object is empty
83 * by comparing with {@code ==} or {@code !=} against instances returned by
|
29
30 import java.util.function.Consumer;
31 import java.util.function.Function;
32 import java.util.function.Predicate;
33 import java.util.function.Supplier;
34 import java.util.stream.Stream;
35
36 /**
37 * A container object which may or may not contain a non-{@code null} value.
38 * If a value is present, {@code isPresent()} returns {@code true}. If no
39 * value is present, the object is considered <i>empty</i> and
40 * {@code isPresent()} returns {@code false}.
41 *
42 * <p>Additional methods that depend on the presence or absence of a contained
43 * value are provided, such as {@link #orElse(Object) orElse()}
44 * (returns a default value if no value is present) and
45 * {@link #ifPresent(Consumer) ifPresent()} (performs an
46 * action if a value is present).
47 *
48 * <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
49 * class; programmers should treat instances that are {@linkplain #equals(Object) equal}
50 * as interchangeable and should not use instances for synchronization, mutexes, or
51 * with {@linkplain java.lang.ref.Reference object references}.
52 *
53 * <div class="preview-block">
54 * <div class="preview-comment">
55 * When preview features are enabled, {@code Optional} is a {@linkplain Class#isValue value class}.
56 * Use of value class instances for synchronization, mutexes, or with
57 * {@linkplain java.lang.ref.Reference object references} result in
58 * {@link IdentityException}.
59 * </div>
60 * </div>
61 *
62 * @apiNote
63 * {@code Optional} is primarily intended for use as a method return type where
64 * there is a clear need to represent "no result," and where using {@code null}
65 * is likely to cause errors. A variable whose type is {@code Optional} should
66 * never itself be {@code null}; it should always point to an {@code Optional}
67 * instance.
68 *
69 * @param <T> the type of value
70 * @since 1.8
71 */
72 @jdk.internal.MigratedValueClass
73 @jdk.internal.ValueBased
74 public final class Optional<T> {
75 /**
76 * Common instance for {@code empty()}.
77 */
78 private static final Optional<?> EMPTY = new Optional<>(null);
79
80 /**
81 * If non-null, the value; if null, indicates no value is present
82 */
83 @Stable
84 private final T value;
85
86 /**
87 * Returns an empty {@code Optional} instance. No value is present for this
88 * {@code Optional}.
89 *
90 * @apiNote
91 * Though it may be tempting to do so, avoid testing if an object is empty
92 * by comparing with {@code ==} or {@code !=} against instances returned by
|