- java.lang.Object
- 
- java.util.Optional<T>
 
- 
- Type Parameters:
- T- the type of value
 
 public final class Optional<T> extends Object A container object which may or may not contain a non-nullvalue. If a value is present,isPresent()returnstrue. If no value is present, the object is considered empty andisPresent()returnsfalse.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) andifPresent()(performs an action if a value is present).This is a value-based class; use of identity-sensitive operations (including reference equality ( ==), identity hash code, or synchronization) on instances ofOptionalmay have unpredictable results and should be avoided.- 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 SummaryAll Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static <T> Optional<T>empty()Returns an emptyOptionalinstance.booleanequals(Object obj)Indicates whether some other object is "equal to" thisOptional.Optional<T>filter(Predicate<? super T> predicate)If a value is present, and the value matches the given predicate, returns anOptionaldescribing the value, otherwise returns an emptyOptional.<U> Optional<U>flatMap(Function<? super T,? extends Optional<? extends U>> mapper)If a value is present, returns the result of applying the givenOptional-bearing mapping function to the value, otherwise returns an emptyOptional.Tget()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.voidifPresent(Consumer<? super T> action)If 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.booleanisPresent()If a value is present, returnstrue, otherwisefalse.<U> Optional<U>map(Function<? super T,? extends U> mapper)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.Optional<T>or(Supplier<? extends Optional<? extends T>> supplier)If a value is present, returns anOptionaldescribing the value, otherwise returns anOptionalproduced by the supplying function.TorElse(T other)If a value is present, returns the value, otherwise returnsother.TorElseGet(Supplier<? extends T> supplier)If a value is present, returns the value, otherwise returns the result produced by the supplying function.TorElseThrow()If a value is present, returns the value, otherwise throwsNoSuchElementException.<X extends Throwable>
 TorElseThrow(Supplier<? extends X> exceptionSupplier)If a value is present, returns the value, otherwise throws an exception produced by the exception supplying function.Stream<T>stream()If a value is present, returns a sequentialStreamcontaining only that value, otherwise returns an emptyStream.StringtoString()Returns a non-empty string representation of thisOptionalsuitable for debugging.
 
- 
- 
- 
Method Detail- 
emptypublic static <T> Optional<T> 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 ==against instances returned byOptional.empty(). There is no guarantee that it is a singleton. Instead, useisPresent().
- Type Parameters:
- T- The type of the non-existent value
- Returns:
- an empty Optional
 
 - 
ofpublic static <T> Optional<T> of(T value) 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 is- null
 
 - 
ofNullablepublic static <T> Optional<T> ofNullable(T value) 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
 
 - 
getpublic T 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
 
 - 
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
 
 - 
ifPresentpublic void ifPresent(Consumer<? super T> action) 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 is- null
 
 - 
ifPresentOrElsepublic 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.- 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
 
 - 
filterpublic Optional<T> filter(Predicate<? super T> predicate) 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 is- null
 
 - 
mappublic <U> Optional<U> map(Function<? super T,? extends U> mapper) 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 is- null
 
 - 
flatMappublic <U> Optional<U> flatMap(Function<? super T,? extends Optional<? extends U>> mapper) 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 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
 
 - 
orpublic Optional<T> or(Supplier<? extends Optional<? extends T>> supplier) If 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
 
 - 
streampublic Stream<T> 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
 
 - 
orElsepublic T orElse(T other) If a value is present, returns the value, otherwise returnsother.- Parameters:
- other- the value to be returned, if no value is present. May be- null.
- Returns:
- the value, if present, otherwise other
 
 - 
orElseGetpublic T orElseGet(Supplier<? extends T> supplier) 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 is- null
 
 - 
orElseThrowpublic T 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
 
 - 
orElseThrowpublic <X extends Throwable> T orElseThrow(Supplier<? extends X> exceptionSupplier) throws X extends Throwable 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 present
- NullPointerException- if no value is present and the exception supplying function is- null
- X extends Throwable
 
 - 
equalspublic boolean equals(Object obj) 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().
 - Overrides:
- equalsin class- Object
- Parameters:
- obj- an object to be tested for equality
- Returns:
- trueif the other object is "equal to" this object otherwise- false
- See Also:
- Object.hashCode(),- HashMap
 
- it is also an 
 - 
hashCodepublic int hashCode() Returns the hash code of the value, if present, otherwise0(zero) if no value is present.- Overrides:
- hashCodein class- Object
- Returns:
- hash code value of the present value or 0if no value is present
- See Also:
- Object.equals(java.lang.Object),- System.identityHashCode(java.lang.Object)
 
 - 
toStringpublic String toString() Returns a non-empty string representation of thisOptionalsuitable for debugging. The exact presentation format is unspecified and may vary between implementations and versions.
 
- 
 
-