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