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:
Optionalis primarily intended for use as a method return type where there is a clear need to represent "no result," and where usingnullis likely to cause errors. A variable whose type isOptionalshould never itself benull; it should always point to anOptionalinstance.- Since:
- 1.8
-
Method Summary
Modifier and TypeMethodDescriptionstatic <T> Optional<T>empty()Returns an emptyOptionalinstance.booleanIndicates whether some other object is "equal to" thisOptional.If a value is present, and the value matches the given predicate, returns anOptionaldescribing 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.inthashCode()Returns the hash code of the value, if present, otherwise0(zero) if no value is present.voidIf a value is present, performs the given action with the value, otherwise does nothing.voidifPresentOrElse(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.booleanisEmpty()If a value is not present, returnstrue, otherwisefalse.booleanIf a value is present, returnstrue, otherwisefalse.<U> Optional<U>If a value is present, returns anOptionaldescribing (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 anOptionaldescribing the given non-nullvalue.static <T> Optional<T>ofNullable(T value) Returns anOptionaldescribing the given value, if non-null, otherwise returns an emptyOptional.If a value is present, returns anOptionaldescribing the value, otherwise returns anOptionalproduced 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 sequentialStreamcontaining only that value, otherwise returns an emptyStream.toString()Returns a non-empty string representation of thisOptionalsuitable for debugging.
-
Method Details
-
empty
Returns an emptyOptionalinstance. 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 anOptionaldescribing the given non-nullvalue.- Type Parameters:
T- the type of the value- Parameters:
value- the value to describe, which must be non-null- Returns:
- an
Optionalwith the value present - Throws:
NullPointerException- if value isnull
-
ofNullable
Returns anOptionaldescribing the given value, if non-null, otherwise returns an emptyOptional.- Type Parameters:
T- the type of the value- Parameters:
value- the possibly-nullvalue to describe- Returns:
- an
Optionalwith 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-
nullvalue described by thisOptional - Throws:
NoSuchElementException- if no value is present
-
isPresent
public boolean isPresent()If a value is present, returnstrue, otherwisefalse.- Returns:
trueif a value is present, otherwisefalse
-
isEmpty
public boolean isEmpty()If a value is not present, returnstrue, otherwisefalse.- Returns:
trueif 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 anOptionaldescribing the value, otherwise returns an emptyOptional.- Parameters:
predicate- the predicate to apply to a value, if present- Returns:
- an
Optionaldescribing 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 anOptionaldescribing (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
nullresult then this method returns an emptyOptional.- API Note:
- This method supports post-processing on
Optionalvalues, 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);findFirstreturns anOptional<URI>, and thenmapreturns 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
Optionaldescribing 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,flatMapdoes not wrap it within an additionalOptional.- Type Parameters:
U- The type of value of theOptionalreturned 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 isnullor returns anullresult
-
or
If a value is present, returns anOptionaldescribing the value, otherwise returns anOptionalproduced by the supplying function.- Parameters:
supplier- the supplying function that produces anOptionalto be returned- Returns:
- returns an
Optionaldescribing the value of thisOptional, if a value is present, otherwise anOptionalproduced by the supplying function. - Throws:
NullPointerException- if the supplying function isnullor produces anullresult- Since:
- 9
-
stream
If a value is present, returns a sequentialStreamcontaining only that value, otherwise returns an emptyStream.- API Note:
- This method can be used to transform a
Streamof optional elements to aStreamof 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-
nullvalue 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
Optionaland; - 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 thisOptionalsuitable for debugging. The exact presentation format is unspecified and may vary between implementations and versions.
-