- 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 usingnullis likely to cause errors. A variable whose type isOptionalshould never itself benull; it should always point to anOptionalinstance.- Since:
- 1.8
-
-
Method Summary
All 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
-
empty
public 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
-
of
public 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 isnull
-
ofNullable
public 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
-
get
public 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
-
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
public 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 isnull
-
ifPresentOrElse
public 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 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
public 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 isnull
-
map
public <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 isnull
-
flatMap
public <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 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
public 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 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
public 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
-
orElse
public 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 benull.- Returns:
- the value, if present, otherwise
other
-
orElseGet
public 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 isnull
-
orElseThrow
public 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
-
orElseThrow
public <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 presentNullPointerException- if no value is present and the exception supplying function isnullX extends Throwable
-
equals
public 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 classObject- Parameters:
obj- an object to be tested for equality- Returns:
trueif the other object is "equal to" this object otherwisefalse- See Also:
Object.hashCode()
- it is also an
-
hashCode
public int hashCode()
Returns the hash code of the value, if present, otherwise0(zero) if no value is present.- Overrides:
hashCodein classObject- Returns:
- hash code value of the present value or
0if no value is present - See Also:
Object.equals(java.lang.Object)
-
toString
public 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.
-
-