T
- the type of instance that can be contained. Optional
is naturally
covariant on this type, so it is safe to cast an Optional<T>
to Optional<S>
for any supertype S
of T
.@Beta @GwtCompatible public abstract class Optional<T> extends java.lang.Object implements java.io.Serializable
null
".
A non-null Optional<T>
reference can be used as a replacement for a nullable
T
reference. It allows you to represent "a T
that must be present" and
a "a T
that might be absent" as two distinct types in your program, which can
aid clarity.
Some uses of this class include
null
to indicate
that no value was available
Optional.absent()
)
null
(though there are
several other approaches to this that should be considered first)
A common alternative to using this class is to find or create a suitable null object for the type in question.
This class is not intended as a direct analogue of any existing "option" or "maybe" construct from other programming environments, though it may bear some similarities.
Modifier and Type | Method and Description |
---|---|
static <T> Optional<T> |
absent()
Returns an
Optional instance with no contained reference. |
abstract java.util.Set<T> |
asSet()
Returns an immutable singleton
Set whose only element is the
contained instance if it is present; an empty immutable Set
otherwise. |
abstract boolean |
equals(java.lang.Object object)
Returns
true if object is an Optional instance, and either
the contained references are equal to each other or both
are absent. |
static <T> Optional<T> |
fromNullable(T nullableReference)
If
nullableReference is non-null, returns an Optional instance containing that
reference; otherwise returns absent() . |
abstract T |
get()
Returns the contained instance, which must be present.
|
abstract int |
hashCode()
Returns a hash code for this instance.
|
abstract boolean |
isPresent()
Returns
true if this holder contains a (non-null) instance. |
static <T> Optional<T> |
of(T reference)
Returns an
Optional instance containing the given non-null reference. |
abstract Optional<T> |
or(Optional<? extends T> secondChoice)
Returns this
Optional if it has a value present; secondChoice
otherwise. |
abstract T |
or(Supplier<? extends T> supplier)
Returns the contained instance if it is present;
supplier.get() otherwise. |
abstract T |
or(T defaultValue)
Returns the contained instance if it is present;
defaultValue otherwise. |
abstract T |
orNull()
Returns the contained instance if it is present;
null otherwise. |
static <T> java.lang.Iterable<T> |
presentInstances(java.lang.Iterable<Optional<T>> optionals)
Returns the value of each present instance from the supplied
optionals , in order,
skipping over occurrences of absent() . |
abstract java.lang.String |
toString()
Returns a string representation for this instance.
|
public static <T> Optional<T> absent()
Optional
instance with no contained reference.public static <T> Optional<T> of(T reference)
Optional
instance containing the given non-null reference.public static <T> Optional<T> fromNullable(@Nullable T nullableReference)
nullableReference
is non-null, returns an Optional
instance containing that
reference; otherwise returns absent()
.public abstract boolean isPresent()
true
if this holder contains a (non-null) instance.public abstract T get()
or(Object)
or orNull()
instead.java.lang.IllegalStateException
- if the instance is absent (isPresent()
returns
false
)public abstract Optional<T> or(Optional<? extends T> secondChoice)
Optional
if it has a value present; secondChoice
otherwise.public abstract T or(Supplier<? extends T> supplier)
supplier.get()
otherwise. If the
supplier returns null
, a NullPointerException
will be thrown.java.lang.NullPointerException
- if the supplier returns null
@Nullable public abstract T orNull()
null
otherwise. If the
instance is known to be present, use get()
instead.public abstract java.util.Set<T> asSet()
Set
whose only element is the
contained instance if it is present; an empty immutable Set
otherwise.public abstract boolean equals(@Nullable java.lang.Object object)
true
if object
is an Optional
instance, and either
the contained references are equal to each other or both
are absent. Note that Optional
instances of differing parameterized types can
be equal.equals
in class java.lang.Object
public abstract int hashCode()
hashCode
in class java.lang.Object
public abstract java.lang.String toString()
toString
in class java.lang.Object
public static <T> java.lang.Iterable<T> presentInstances(java.lang.Iterable<Optional<T>> optionals)
optionals
, in order,
skipping over occurrences of absent()
. Iterators are unmodifiable and are
evaluated lazily.