Class Optional<T>
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 using- nullis likely to cause errors. A variable whose type is- Optionalshould never itself be- null; it should always point to an- Optionalinstance.
- Since:
- 1.8
- 
Method SummaryModifier 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- 
emptyReturns 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
 
- 
ofReturns 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 is- null
 
- 
ofNullableReturns 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
 
- 
getIf 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
 
- 
isPresentpublic boolean isPresent()If a value is present, returnstrue, otherwisefalse.- Returns:
- trueif a value is present, otherwise- false
 
- 
isEmptypublic boolean isEmpty()If a value is not present, returnstrue, otherwisefalse.- Returns:
- trueif a value is not present, otherwise- false
- Since:
- 11
 
- 
ifPresentIf 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 is- null
 
- 
ifPresentOrElseIf 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 present
- emptyAction- the empty-based action to be performed, if no value is present
- Throws:
- NullPointerException- if a value is present and the given action is- null, or no value is present and the given empty-based action is- null.
- Since:
- 9
 
- 
filterIf 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 is- null
 
- 
mapIf 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 is- null
 
- 
flatMapIf 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 the- Optionalreturned 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 is- nullor returns a- nullresult
 
- 
orIf a value is present, returns anOptionaldescribing the value, otherwise returns anOptionalproduced by the supplying function.- Parameters:
- supplier- the supplying function that produces an- Optionalto 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 is- nullor produces a- nullresult
- Since:
- 9
 
- 
streamIf 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
- 
orElseGetIf 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 is- null
 
- 
orElseThrowIf 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
 
- 
orElseThrowIf 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 present
- NullPointerException- if no value is present and the exception supplying function is- null
 
- 
equalsIndicates 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
- 
toStringReturns a non-empty string representation of thisOptionalsuitable for debugging. The exact presentation format is unspecified and may vary between implementations and versions.
 
-