java.lang.Object
java.util.Optional<T>
- Type Parameters:
T
- the type of value
A container object which may or may not contain a non-
null
value.
If a value is present, isPresent()
returns true
. If no
value is present, the object is considered empty and
isPresent()
returns false
.
Additional methods that depend on the presence or absence of a contained
value are provided, such as orElse()
(returns a default value if no value is present) and
ifPresent()
(performs an
action if a value is present).
This is a value-based class; programmers should treat instances that are equal as interchangeable and should not use instances for synchronization, or unpredictable behavior may occur. For example, in a future release, synchronization may fail.
- API Note:
Optional
is primarily intended for use as a method return type where there is a clear need to represent "no result," and where usingnull
is likely to cause errors. A variable whose type isOptional
should never itself benull
; it should always point to anOptional
instance.- Since:
- 1.8
-
Method Summary
Modifier and TypeMethodDescriptionstatic <T> Optional<T>
empty()
Returns an emptyOptional
instance.boolean
Indicates whether some other object is "equal to" thisOptional
.If a value is present, and the value matches the given predicate, returns anOptional
describing the value, otherwise returns an emptyOptional
.<U> Optional<U>
If a value is present, returns the result of applying the givenOptional
-bearing mapping function to the value, otherwise returns an emptyOptional
.get()
If a value is present, returns the value, otherwise throwsNoSuchElementException
.int
hashCode()
Returns the hash code of the value, if present, otherwise0
(zero) if no value is present.void
If a value is present, performs the given action with the value, otherwise does nothing.void
ifPresentOrElse
(Consumer<? super T> action, Runnable emptyAction) If a value is present, performs the given action with the value, otherwise performs the given empty-based action.boolean
isEmpty()
If a value is not present, returnstrue
, otherwisefalse
.boolean
If a value is present, returnstrue
, otherwisefalse
.<U> Optional<U>
If a value is present, returns anOptional
describing (as if byofNullable(T)
) the result of applying the given mapping function to the value, otherwise returns an emptyOptional
.static <T> Optional<T>
of
(T value) Returns anOptional
describing the given non-null
value.static <T> Optional<T>
ofNullable
(T value) Returns anOptional
describing the given value, if non-null
, otherwise returns an emptyOptional
.If a value is present, returns anOptional
describing the value, otherwise returns anOptional
produced by the supplying function.If a value is present, returns the value, otherwise returnsother
.If a value is present, returns the value, otherwise returns the result produced by the supplying function.If a value is present, returns the value, otherwise throwsNoSuchElementException
.orElseThrow
(Supplier<? extends X> exceptionSupplier) If a value is present, returns the value, otherwise throws an exception produced by the exception supplying function.stream()
If a value is present, returns a sequentialStream
containing only that value, otherwise returns an emptyStream
.toString()
Returns a non-empty string representation of thisOptional
suitable for debugging.
-
Method Details
-
empty
Returns an emptyOptional
instance. No value is present for thisOptional
.- API Note:
- Though it may be tempting to do so, avoid testing if an object is empty
by comparing with
==
or!=
against instances returned byOptional.empty()
. There is no guarantee that it is a singleton. Instead, useisEmpty()
orisPresent()
. - Type Parameters:
T
- The type of the non-existent value- Returns:
- an empty
Optional
-
of
Returns anOptional
describing the given non-null
value.- Type Parameters:
T
- the type of the value- Parameters:
value
- the value to describe, which must be non-null
- Returns:
- an
Optional
with the value present - Throws:
NullPointerException
- if value isnull
-
ofNullable
Returns anOptional
describing the given value, if non-null
, otherwise returns an emptyOptional
.- Type Parameters:
T
- the type of the value- Parameters:
value
- the possibly-null
value to describe- Returns:
- an
Optional
with a present value if the specified value is non-null
, otherwise an emptyOptional
-
get
If a value is present, returns the value, otherwise throwsNoSuchElementException
.- API Note:
- The preferred alternative to this method is
orElseThrow()
. - Returns:
- the non-
null
value described by thisOptional
- Throws:
NoSuchElementException
- if no value is present
-
isPresent
public boolean isPresent()If a value is present, returnstrue
, otherwisefalse
.- Returns:
true
if a value is present, otherwisefalse
-
isEmpty
public boolean isEmpty()If a value is not present, returnstrue
, otherwisefalse
.- Returns:
true
if a value is not present, otherwisefalse
- Since:
- 11
-
ifPresent
If a value is present, performs the given action with the value, otherwise does nothing.- Parameters:
action
- the action to be performed, if a value is present- Throws:
NullPointerException
- if value is present and the given action isnull
-
ifPresentOrElse
If a value is present, performs the given action with the value, otherwise performs the given empty-based action.- Parameters:
action
- the action to be performed, if a value is presentemptyAction
- the empty-based action to be performed, if no value is present- Throws:
NullPointerException
- if a value is present and the given action isnull
, or no value is present and the given empty-based action isnull
.- Since:
- 9
-
filter
If a value is present, and the value matches the given predicate, returns anOptional
describing the value, otherwise returns an emptyOptional
.- Parameters:
predicate
- the predicate to apply to a value, if present- Returns:
- an
Optional
describing the value of thisOptional
, if a value is present and the value matches the given predicate, otherwise an emptyOptional
- Throws:
NullPointerException
- if the predicate isnull
-
map
If a value is present, returns anOptional
describing (as if byofNullable(T)
) the result of applying the given mapping function to the value, otherwise returns an emptyOptional
.If the mapping function returns a
null
result then this method returns an emptyOptional
.- API Note:
- This method supports post-processing on
Optional
values, without the need to explicitly check for a return status. For example, the following code traverses a stream of URIs, selects one that has not yet been processed, and creates a path from that URI, returning anOptional<Path>
:
Here,Optional<Path> p = uris.stream().filter(uri -> !isProcessedYet(uri)) .findFirst() .map(Paths::get);
findFirst
returns anOptional<URI>
, and thenmap
returns anOptional<Path>
for the desired URI if one exists. - Type Parameters:
U
- The type of the value returned from the mapping function- Parameters:
mapper
- the mapping function to apply to a value, if present- Returns:
- an
Optional
describing the result of applying a mapping function to the value of thisOptional
, if a value is present, otherwise an emptyOptional
- Throws:
NullPointerException
- if the mapping function isnull
-
flatMap
If a value is present, returns the result of applying the givenOptional
-bearing mapping function to the value, otherwise returns an emptyOptional
.This method is similar to
map(Function)
, but the mapping function is one whose result is already anOptional
, and if invoked,flatMap
does not wrap it within an additionalOptional
.- Type Parameters:
U
- The type of value of theOptional
returned by the mapping function- Parameters:
mapper
- the mapping function to apply to a value, if present- Returns:
- the result of applying an
Optional
-bearing mapping function to the value of thisOptional
, if a value is present, otherwise an emptyOptional
- Throws:
NullPointerException
- if the mapping function isnull
or returns anull
result
-
or
If a value is present, returns anOptional
describing the value, otherwise returns anOptional
produced by the supplying function.- Parameters:
supplier
- the supplying function that produces anOptional
to be returned- Returns:
- returns an
Optional
describing the value of thisOptional
, if a value is present, otherwise anOptional
produced by the supplying function. - Throws:
NullPointerException
- if the supplying function isnull
or produces anull
result- Since:
- 9
-
stream
If a value is present, returns a sequentialStream
containing only that value, otherwise returns an emptyStream
.- API Note:
- This method can be used to transform a
Stream
of optional elements to aStream
of present value elements:Stream<Optional<T>> os = .. Stream<T> s = os.flatMap(Optional::stream)
- Returns:
- the optional value as a
Stream
- Since:
- 9
-
orElse
If a value is present, returns the value, otherwise returnsother
.- Parameters:
other
- the value to be returned, if no value is present. May benull
.- Returns:
- the value, if present, otherwise
other
-
orElseGet
If a value is present, returns the value, otherwise returns the result produced by the supplying function.- Parameters:
supplier
- the supplying function that produces a value to be returned- Returns:
- the value, if present, otherwise the result produced by the supplying function
- Throws:
NullPointerException
- if no value is present and the supplying function isnull
-
orElseThrow
If a value is present, returns the value, otherwise throwsNoSuchElementException
.- Returns:
- the non-
null
value described by thisOptional
- Throws:
NoSuchElementException
- if no value is present- Since:
- 10
-
orElseThrow
If a value is present, returns the value, otherwise throws an exception produced by the exception supplying function.- API Note:
- A method reference to the exception constructor with an empty argument
list can be used as the supplier. For example,
IllegalStateException::new
- Type Parameters:
X
- Type of the exception to be thrown- Parameters:
exceptionSupplier
- the supplying function that produces an exception to be thrown- Returns:
- the value, if present
- Throws:
X
- if no value is presentNullPointerException
- if no value is present and the exception supplying function isnull
-
equals
Indicates whether some other object is "equal to" thisOptional
. The other object is considered equal if:- it is also an
Optional
and; - both instances have no value present or;
- the present values are "equal to" each other via
equals()
.
- it is also an
-
hashCode
public int hashCode()Returns the hash code of the value, if present, otherwise0
(zero) if no value is present. -
toString
Returns a non-empty string representation of thisOptional
suitable for debugging. The exact presentation format is unspecified and may vary between implementations and versions.
-