OpenJDK 24 · java.util.Optional · APIdia, the JavaDoc alternative

Modifier and Type	Field and Description
private static final Optional<?>	EMPTY Common instance for `empty()`.
private final T	value If non-null, the value; if null, indicates no value is present

Access	Constructor and Description
private	Optional(T the value to describe; it's the caller's responsibility to ensure the value is non-`null` unless creating the singleton instance returned by `empty()`. value) Constructs an instance with the described value.

Method Summary

Modifier and Type	Method and Description
public static < The type of the non-existent value T> Optional<T>	Returns: an empty `Optional` empty() Returns an empty `Optional` instance.
public boolean	Returns: `true` if the other object is "equal to" this object otherwise `false` equals(Object an object to be tested for equality obj) Overrides java.lang.Object.equals. Indicates whether some other object is "equal to" this `Optional`.
public Optional<T>	Returns: an `Optional` describing the value of this `Optional`, if a value is present and the value matches the given predicate, otherwise an empty `Optional` filter(Predicate<? super T> the predicate to apply to a value, if present predicate) If a value is present, and the value matches the given predicate, returns an `Optional` describing the value, otherwise returns an empty `Optional`.
public < The type of value of the `Optional` returned by the mapping function U> Optional<U>	Returns: the result of applying an `Optional`-bearing mapping function to the value of this `Optional`, if a value is present, otherwise an empty `Optional` flatMap(Function<? super T, ? extends Optional<? extends U>> the mapping function to apply to a value, if present mapper) If a value is present, returns the result of applying the given `Optional`-bearing mapping function to the value, otherwise returns an empty `Optional`.
public T	Returns: the non-`null` value described by this `Optional` get() If a value is present, returns the value, otherwise throws `NoSuchElementException`.
public int	Returns: hash code value of the present value or `0` if no value is present hashCode() Overrides java.lang.Object.hashCode. Returns the hash code of the value, if present, otherwise `0` (zero) if no value is present.
public void	ifPresent(Consumer<? super T> the action to be performed, if a value is present action) If a value is present, performs the given action with the value, otherwise does nothing.
public void	ifPresentOrElse(Consumer<? super T> the action to be performed, if a value is present action, Runnable the empty-based action to be performed, if no value is present emptyAction) If a value is present, performs the given action with the value, otherwise performs the given empty-based action.
public boolean	Returns: `true` if a value is not present, otherwise `false` isEmpty() If a value is not present, returns `true`, otherwise `false`.
public boolean	Returns: `true` if a value is present, otherwise `false` isPresent() If a value is present, returns `true`, otherwise `false`.
public < The type of the value returned from the mapping function U> Optional<U>	Returns: an `Optional` describing the result of applying a mapping function to the value of this `Optional`, if a value is present, otherwise an empty `Optional` map(Function<? super T, ? extends U> the mapping function to apply to a value, if present mapper) If a value is present, returns an `Optional` describing (as if by `ofNullable`) the result of applying the given mapping function to the value, otherwise returns an empty `Optional`.
public static < the type of the value T> Optional<T>	Returns: an `Optional` with the value present of(T the value to describe, which must be non-`null` value) Returns an `Optional` describing the given non-`null` value.
public static < the type of the value T> Optional<T>	Returns: an `Optional` with a present value if the specified value is non-`null`, otherwise an empty `Optional` ofNullable(T the possibly-`null` value to describe value) Returns an `Optional` describing the given value, if non-`null`, otherwise returns an empty `Optional`.
public Optional<T>	Returns: returns an `Optional` describing the value of this `Optional`, if a value is present, otherwise an `Optional` produced by the supplying function. or(Supplier<? extends Optional<? extends T>> the supplying function that produces an `Optional` to be returned supplier) If a value is present, returns an `Optional` describing the value, otherwise returns an `Optional` produced by the supplying function.
public T	Returns: the value, if present, otherwise `other` orElse(T the value to be returned, if no value is present. May be `null`. other) If a value is present, returns the value, otherwise returns `other`.
public T	Returns: the value, if present, otherwise the result produced by the supplying function orElseGet(Supplier<? extends T> the supplying function that produces a value to be returned supplier) If a value is present, returns the value, otherwise returns the result produced by the supplying function.
public T	Returns: the non-`null` value described by this `Optional` orElseThrow() If a value is present, returns the value, otherwise throws `NoSuchElementException`.
public < Type of the exception to be thrown X extends Throwable> T	Returns: the value, if present orElseThrow(Supplier<? extends X> the supplying function that produces an exception to be thrown exceptionSupplier) If a value is present, returns the value, otherwise throws an exception produced by the exception supplying function.
public Stream<T>	Returns: the optional value as a `Stream` stream() If a value is present, returns a sequential `Stream` containing only that value, otherwise returns an empty `Stream`.
public String	Returns: the string representation of this instance toString() Overrides java.lang.Object.toString. Returns a non-empty string representation of this `Optional` suitable for debugging.

Inherited from java.lang.Object:: clone finalize getClass notify notifyAll wait wait wait

EMPTY	back to summary
private static final Optional<?> EMPTY Common instance for `empty()`.

value	back to summary
private final T value If non-null, the value; if null, indicates no value is present

Optional	back to summary
private Optional(T value) Constructs an instance with the described value. Parameters value:T the value to describe; it's the caller's responsibility to ensure the value is non-`null` unless creating the singleton instance returned by `empty()`.

Method Detail

empty back to summary

empty	back to summary
public static <T> Optional<T> empty() Returns an empty `Optional` instance. No value is present for this `Optional`. API Note Though it may be tempting to do so, avoid testing if an object is empty by comparing with `==` or `!=` against instances returned by `Optional.empty()`. There is no guarantee that it is a singleton. Instead, use `isEmpty()` or `isPresent()`. Parameters <T> The type of the non-existent value Returns:Optional<T> an empty `Optional`

public static <T> Optional<T> empty()

Returns an empty Optional instance. No value is present for this Optional.

API Note

Though it may be tempting to do so, avoid testing if an object is empty by comparing with == or != against instances returned by Optional.empty(). There is no guarantee that it is a singleton. Instead, use isEmpty() or isPresent().

Parameters

<T>: The type of the non-existent value

Returns:Optional<T>

an empty Optional

equals back to summary

equals	back to summary
public boolean equals(Object obj) Overrides java.lang.Object.equals. Indicates whether some other object is "equal to" this `Optional`. 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()`. Parameters obj:Object an object to be tested for equality Returns:boolean `true` if the other object is "equal to" this object otherwise `false` Annotations @Override

public boolean equals(Object obj)

Overrides java.lang.Object.equals.

Indicates whether some other object is "equal to" this Optional. 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().

Parameters

obj:Object: an object to be tested for equality

Returns:boolean

true if the other object is "equal to" this object otherwise false

Annotations

@Override

filter back to summary

filter	back to summary
public Optional<T> filter(Predicate<? super T> predicate) If a value is present, and the value matches the given predicate, returns an `Optional` describing the value, otherwise returns an empty `Optional`. Parameters predicate:Predicate<? super T> the predicate to apply to a value, if present Returns:Optional<T> an `Optional` describing the value of this `Optional`, if a value is present and the value matches the given predicate, otherwise an empty `Optional` Exceptions NullPointerException: if the predicate is `null`

public Optional<T> filter(Predicate<? super T> predicate)

If a value is present, and the value matches the given predicate, returns an Optional describing the value, otherwise returns an empty Optional.

Parameters

predicate:Predicate<? super T>: the predicate to apply to a value, if present

Returns:Optional<T>

an Optional describing the value of this Optional, if a value is present and the value matches the given predicate, otherwise an empty Optional

Exceptions

NullPointerException:: if the predicate is null

flatMap back to summary

flatMap	back to summary
public <U> Optional<U> flatMap(Function<? super T, ? extends Optional<? extends U>> mapper) If a value is present, returns the result of applying the given `Optional`-bearing mapping function to the value, otherwise returns an empty `Optional`. This method is similar to `map(Function)`, but the mapping function is one whose result is already an `Optional`, and if invoked, `flatMap` does not wrap it within an additional `Optional`. Parameters <U> The type of value of the `Optional` returned by the mapping function mapper:Function<? super T, ? extends Optional<? extends U>> the mapping function to apply to a value, if present Returns:Optional<U> the result of applying an `Optional`-bearing mapping function to the value of this `Optional`, if a value is present, otherwise an empty `Optional` Exceptions NullPointerException: if the mapping function is `null` or returns a `null` result

public Optional flatMap(Function<? super T, ? extends Optional<? extends U>> mapper)

If a value is present, returns the result of applying the given Optional-bearing mapping function to the value, otherwise returns an empty Optional.

This method is similar to map(Function), but the mapping function is one whose result is already an Optional, and if invoked, flatMap does not wrap it within an additional Optional.

Parameters

: The type of value of the Optional returned by the mapping function
mapper:Function<? super T, ? extends Optional<? extends U>>: the mapping function to apply to a value, if present

Returns:Optional

the result of applying an Optional-bearing mapping function to the value of this Optional, if a value is present, otherwise an empty Optional

Exceptions

NullPointerException:: if the mapping function is null or returns a null result

get back to summary

get	back to summary
public T get() If a value is present, returns the value, otherwise throws `NoSuchElementException`. API Note The preferred alternative to this method is `orElseThrow()`. Returns:T the non-`null` value described by this `Optional` Exceptions NoSuchElementException: if no value is present

public T get()

If a value is present, returns the value, otherwise throws NoSuchElementException.

API Note

The preferred alternative to this method is orElseThrow().

Returns:T

the non-null value described by this Optional

Exceptions

NoSuchElementException:: if no value is present

hashCode back to summary

hashCode	back to summary
public int hashCode() Overrides java.lang.Object.hashCode. Returns the hash code of the value, if present, otherwise `0` (zero) if no value is present. Returns:int hash code value of the present value or `0` if no value is present Annotations @Override

public int hashCode()

Overrides java.lang.Object.hashCode.

Returns the hash code of the value, if present, otherwise 0 (zero) if no value is present.

Returns:int

hash code value of the present value or 0 if no value is present

Annotations

@Override

ifPresent back to summary

ifPresent	back to summary
public void ifPresent(Consumer<? super T> action) If a value is present, performs the given action with the value, otherwise does nothing. Parameters action:Consumer<? super T> the action to be performed, if a value is present Exceptions NullPointerException: if value is present and the given action is `null`

public void ifPresent(Consumer<? super T> action)

If a value is present, performs the given action with the value, otherwise does nothing.

Parameters

action:Consumer<? super T>: the action to be performed, if a value is present

Exceptions

NullPointerException:: if value is present and the given action is null

ifPresentOrElse back to summary

ifPresentOrElse	back to summary
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:Consumer<? super T> the action to be performed, if a value is present emptyAction:Runnable the empty-based action to be performed, if no value is present Exceptions 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

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:Consumer<? super T>: the action to be performed, if a value is present
emptyAction:Runnable: the empty-based action to be performed, if no value is present

Exceptions

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

isEmpty back to summary

isEmpty	back to summary
public boolean isEmpty() If a value is not present, returns `true`, otherwise `false`. Returns:boolean `true` if a value is not present, otherwise `false` Since 11

public boolean isEmpty()

If a value is not present, returns true, otherwise false.

Returns:boolean: true if a value is not present, otherwise false
Since: 11

isPresent back to summary

isPresent	back to summary
public boolean isPresent() If a value is present, returns `true`, otherwise `false`. Returns:boolean `true` if a value is present, otherwise `false`

public boolean isPresent()

If a value is present, returns true, otherwise false.

Returns:boolean: true if a value is present, otherwise false

map back to summary

map	back to summary
public <U> Optional<U> map(Function<? super T, ? extends U> mapper) If a value is present, returns an `Optional` describing (as if by `ofNullable`) the result of applying the given mapping function to the value, otherwise returns an empty `Optional`. If the mapping function returns a `null` result then this method returns an empty `Optional`. 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 an `Optional<Path>`: `Optional<Path> p = uris.stream().filter(uri -> !isProcessedYet(uri)) .findFirst() .map(Paths::get);` Here, `findFirst` returns an `Optional<URI>`, and then `map` returns an `Optional<Path>` for the desired URI if one exists. Parameters <U> The type of the value returned from the mapping function mapper:Function<? super T, ? extends U> the mapping function to apply to a value, if present Returns:Optional<U> an `Optional` describing the result of applying a mapping function to the value of this `Optional`, if a value is present, otherwise an empty `Optional` Exceptions NullPointerException: if the mapping function is `null`

public Optional map(Function<? super T, ? extends U> mapper)

If a value is present, returns an Optional describing (as if by ofNullable) the result of applying the given mapping function to the value, otherwise returns an empty Optional.

If the mapping function returns a null result then this method returns an empty Optional.

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 an Optional<Path>:

Optional<Path> p =
        uris.stream().filter(uri -> !isProcessedYet(uri))
                      .findFirst()
                      .map(Paths::get);

Here, findFirst returns an Optional<URI>, and then map returns an Optional<Path> for the desired URI if one exists.

Parameters

: The type of the value returned from the mapping function
mapper:Function<? super T, ? extends U>: the mapping function to apply to a value, if present

Returns:Optional

an Optional describing the result of applying a mapping function to the value of this Optional, if a value is present, otherwise an empty Optional

Exceptions

NullPointerException:: if the mapping function is null

of back to summary

of	back to summary
public static <T> Optional<T> of(T value) Returns an `Optional` describing the given non-`null` value. Parameters <T> the type of the value value:T the value to describe, which must be non-`null` Returns:Optional<T> an `Optional` with the value present Exceptions NullPointerException: if value is `null`

public static <T> Optional<T> of(T value)

Returns an Optional describing the given non-null value.

Parameters

<T>: the type of the value
value:T: the value to describe, which must be non-null

Returns:Optional<T>

an Optional with the value present

Exceptions

NullPointerException:: if value is null

ofNullable back to summary

ofNullable	back to summary
public static <T> Optional<T> ofNullable(T value) Returns an `Optional` describing the given value, if non-`null`, otherwise returns an empty `Optional`. Parameters <T> the type of the value value:T the possibly-`null` value to describe Returns:Optional<T> an `Optional` with a present value if the specified value is non-`null`, otherwise an empty `Optional` Annotations @SuppressWarnings:unchecked

public static <T> Optional<T> ofNullable(T value)

Returns an Optional describing the given value, if non-null, otherwise returns an empty Optional.

Parameters

<T>: the type of the value
value:T: the possibly-null value to describe

Returns:Optional<T>

an Optional with a present value if the specified value is non-null, otherwise an empty Optional

Annotations

@SuppressWarnings:unchecked

or back to summary

or	back to summary
public Optional<T> or(Supplier<? extends Optional<? extends T>> supplier) If a value is present, returns an `Optional` describing the value, otherwise returns an `Optional` produced by the supplying function. Parameters supplier:Supplier<? extends Optional<? extends T>> the supplying function that produces an `Optional` to be returned Returns:Optional<T> returns an `Optional` describing the value of this `Optional`, if a value is present, otherwise an `Optional` produced by the supplying function. Exceptions NullPointerException: if the supplying function is `null` or produces a `null` result Since 9

public Optional<T> or(Supplier<? extends Optional<? extends T>> supplier)

If a value is present, returns an Optional describing the value, otherwise returns an Optional produced by the supplying function.

Parameters

supplier:Supplier<? extends Optional<? extends T>>: the supplying function that produces an Optional to be returned

Returns:Optional<T>

returns an Optional describing the value of this Optional, if a value is present, otherwise an Optional produced by the supplying function.

Exceptions

NullPointerException:: if the supplying function is null or produces a null result

Since

orElse back to summary

orElse	back to summary
public T orElse(T other) If a value is present, returns the value, otherwise returns `other`. Parameters other:T the value to be returned, if no value is present. May be `null`. Returns:T the value, if present, otherwise `other`

public T orElse(T other)

If a value is present, returns the value, otherwise returns other.

Parameters

other:T: the value to be returned, if no value is present. May be null.

Returns:T

the value, if present, otherwise other

orElseGet back to summary

orElseGet	back to summary
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:Supplier<? extends T> the supplying function that produces a value to be returned Returns:T the value, if present, otherwise the result produced by the supplying function Exceptions NullPointerException: if no value is present and the supplying function is `null`

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:Supplier<? extends T>: the supplying function that produces a value to be returned

Returns:T

the value, if present, otherwise the result produced by the supplying function

Exceptions

NullPointerException:: if no value is present and the supplying function is null

orElseThrow back to summary

orElseThrow	back to summary
public T orElseThrow() If a value is present, returns the value, otherwise throws `NoSuchElementException`. Returns:T the non-`null` value described by this `Optional` Exceptions NoSuchElementException: if no value is present Since 10

public T orElseThrow()

If a value is present, returns the value, otherwise throws NoSuchElementException.

Returns:T

the non-null value described by this Optional

Exceptions

NoSuchElementException:: if no value is present

Since

orElseThrow back to summary

orElseThrow	back to summary
public <X extends Throwable> T orElseThrow(Supplier<? extends X> exceptionSupplier) throws Supplier-:X 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` Parameters <X> Type of the exception to be thrown exceptionSupplier:Supplier<? extends X> the supplying function that produces an exception to be thrown Returns:T the value, if present Exceptions Supplier-:X: if no value is present NullPointerException: if no value is present and the exception supplying function is `null`

public <X extends Throwable> T orElseThrow(Supplier<? extends X> exceptionSupplier) throws Supplier-:X

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

Parameters

<X>: Type of the exception to be thrown
exceptionSupplier:Supplier<? extends X>: the supplying function that produces an exception to be thrown

Returns:T

the value, if present

Exceptions

Supplier-:X:: if no value is present
NullPointerException:: if no value is present and the exception supplying function is null

stream back to summary

stream	back to summary
public Stream<T> stream() If a value is present, returns a sequential `Stream` containing only that value, otherwise returns an empty `Stream`. API Note This method can be used to transform a `Stream` of optional elements to a `Stream` of present value elements: `Stream<Optional<T>> os = .. Stream<T> s = os.flatMap(Optional::stream)` Returns:Stream<T> the optional value as a `Stream` Since 9

public Stream<T> stream()

If a value is present, returns a sequential Stream containing only that value, otherwise returns an empty Stream.

API Note

This method can be used to transform a Stream of optional elements to a Stream of present value elements:

Stream<Optional<T>> os = ..
    Stream<T> s = os.flatMap(Optional::stream)

Returns:Stream<T>: the optional value as a Stream
Since: 9

toString back to summary

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Returns a non-empty string representation of this `Optional` suitable for debugging. The exact presentation format is unspecified and may vary between implementations and versions. Implementation Specification If a value is present the result must include its string representation in the result. Empty and present `Optional`s must be unambiguously differentiable. Returns:String the string representation of this instance Annotations @Override

public String toString()

Overrides java.lang.Object.toString.

Returns a non-empty string representation of this Optional suitable for debugging. The exact presentation format is unspecified and may vary between implementations and versions.

Implementation Specification

If a value is present the result must include its string representation in the result. Empty and present Optionals must be unambiguously differentiable.

Returns:String

the string representation of this instance

Annotations

@Override

public final Class Optional<T>

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail