Class Optional<T>

java.lang.Object
java.util.Optional<T>
Type Parameters:
T - the type of value
public final classOptional<T>extendsObject
A container object which may or may not contain a non-null value. If a value is present,isPresent() returnstrue. If no value is present, the object is consideredempty andisPresent() returnsfalse.

Additional methods that depend on the presence or absence of a contained value are provided, such asorElse() (returns a default value if no value is present) andifPresent() (performs an action if a value is present).

This is avalue-based class; programmers should treat instances that areequal 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:
Optional is primarily intended for use as a method return type where there is a clear need to represent "no result," and where usingnull is likely to cause errors. A variable whose type isOptional should never itself benull; it should always point to anOptional instance.
Since:
1.8

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T> Optional<T>
    Returns an emptyOptional instance.
    boolean
    Indicates whether some other object is "equal to" thisOptional.
    filter(Predicate<? superT> predicate)
    If a value is present, and the value matches the given predicate, returns anOptional describing the value, otherwise returns an emptyOptional.
    <U> Optional<U>
    flatMap(Function<? superT, ? extendsOptional<? 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.
    get()
    If a value is present, returns the value, otherwise throwsNoSuchElementException.
    int
    Returns the hash code of the value, if present, otherwise0 (zero) if no value is present.
    void
    ifPresent(Consumer<? superT> action)
    If a value is present, performs the given action with the value, otherwise does nothing.
    void
    ifPresentOrElse(Consumer<? superT> action,Runnable emptyAction)
    If a value is present, performs the given action with the value, otherwise performs the given empty-based action.
    boolean
    If a value is not present, returnstrue, otherwisefalse.
    boolean
    If a value is present, returnstrue, otherwisefalse.
    <U> Optional<U>
    map(Function<? superT, ? extends U> mapper)
    If a value is present, returns anOptional describing (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 anOptional describing the given non-null value.
    static <T> Optional<T>
    ofNullable(T value)
    Returns anOptional describing the given value, if non-null, otherwise returns an emptyOptional.
    or(Supplier<? extendsOptional<? extendsT>> supplier)
    If a value is present, returns anOptional describing the value, otherwise returns anOptional produced by the supplying function.
    orElse(T other)
    If a value is present, returns the value, otherwise returnsother.
    orElseGet(Supplier<? extendsT> supplier)
    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.
    <X extendsThrowable>
    T
    orElseThrow(Supplier<? extends X> exceptionSupplier)
    If a value is present, returns the value, otherwise throws an exception produced by the exception supplying function.
    If a value is present, returns a sequentialStream containing only that value, otherwise returns an emptyStream.
    Returns a non-empty string representation of thisOptional suitable for debugging.

    Methods declared in class java.lang.Object

    clone,finalize,getClass,notify,notifyAll,wait,wait,wait

  • Method Details

    • empty

      public static <T> Optional<T> empty()
      Returns an emptyOptional instance. 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 emptyOptional

    • of

      public static <T> Optional<T> of(T value)
      Returns anOptional describing the given non-null value.
      Type Parameters:
      T - the type of the value
      Parameters:
      value - the value to describe, which must be non-null
      Returns:
      anOptional with the value present
      Throws:
      NullPointerException - if value isnull

    • ofNullable

      public static <T> Optional<T> ofNullable(T value)
      Returns anOptional describing the given value, if non-null, otherwise returns an emptyOptional.
      Type Parameters:
      T - the type of the value
      Parameters:
      value - the possibly-null value to describe
      Returns:
      anOptional with 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 isorElseThrow().
      Returns:
      the non-null value described by thisOptional
      Throws:
      NoSuchElementException - if no value is present

    • isPresent

      public boolean isPresent()
      If a value is present, returnstrue, otherwisefalse.
      Returns:
      true if a value is present, otherwisefalse

    • isEmpty

      public boolean isEmpty()
      If a value is not present, returnstrue, otherwisefalse.
      Returns:
      true if a value is not present, otherwisefalse
      Since:
      11

    • ifPresent

      public void ifPresent(Consumer<? superT> 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<? superT> 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 isnull, or no value is present and the given empty-based action isnull.
      Since:
      9

    • filter

      public Optional<T> filter(Predicate<? superT> predicate)
      If a value is present, and the value matches the given predicate, returns anOptional describing the value, otherwise returns an emptyOptional.
      Parameters:
      predicate - the predicate to apply to a value, if present
      Returns:
      anOptional describing 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<? superT, ? extends U> mapper)
      If a value is present, returns anOptional describing (as if byofNullable(T)) the result of applying the given mapping function to the value, otherwise returns an emptyOptional.

      If the mapping function returns anull result then this method returns an emptyOptional.

      API Note:
      This method supports post-processing onOptional 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 anOptional<Path>:
           Optional<Path> p =         uris.stream().filter(uri -> !isProcessedYet(uri))                       .findFirst()                       .map(Paths::get);
      Here,findFirst returns anOptional<URI>, and thenmap returns 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:
      anOptional describing 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<? superT, ? extendsOptional<? 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 tomap(Function), but the mapping function is one whose result is already anOptional, and if invoked,flatMap does not wrap it within an additionalOptional.

      Type Parameters:
      U - The type of value of theOptional returned by the mapping function
      Parameters:
      mapper - the mapping function to apply to a value, if present
      Returns:
      the result of applying anOptional-bearing mapping function to the value of thisOptional, if a value is present, otherwise an emptyOptional
      Throws:
      NullPointerException - if the mapping function isnull or returns anull result

    • or

      public Optional<T> or(Supplier<? extendsOptional<? extendsT>> supplier)
      If a value is present, returns anOptional describing the value, otherwise returns anOptional produced by the supplying function.
      Parameters:
      supplier - the supplying function that produces anOptional to be returned
      Returns:
      returns anOptional describing the value of thisOptional, if a value is present, otherwise anOptional produced by the supplying function.
      Throws:
      NullPointerException - if the supplying function isnull or produces anull result
      Since:
      9

    • stream

      public Stream<T> stream()
      If a value is present, returns a sequentialStream containing only that value, otherwise returns an emptyStream.
      API Note:
      This method can be used to transform aStream of optional elements to aStream of present value elements:
           Stream<Optional<T>> os = ..     Stream<T> s = os.flatMap(Optional::stream)
      Returns:
      the optional value as aStream
      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, otherwiseother

    • orElseGet

      public T orElseGet(Supplier<? extendsT> 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-null value described by thisOptional
      Throws:
      NoSuchElementException - if no value is present
      Since:
      10

    • orElseThrow

      public <X extendsThrowable> T orElseThrow(Supplier<? extends X> exceptionSupplier) throwsX
      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 isnull

    • 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 anOptional and;
      • both instances have no value present or;
      • the present values are "equal to" each other viaequals().
      Overrides:
      equals in class Object
      Parameters:
      obj - an object to be tested for equality
      Returns:
      true if the other object is "equal to" this object otherwisefalse
      See Also:

    • hashCode

      public int hashCode()
      Returns the hash code of the value, if present, otherwise0 (zero) if no value is present.
      Overrides:
      hashCode in class Object
      Returns:
      hash code value of the present value or0 if no value is present
      See Also:

    • toString

      public String toString()
      Returns a non-empty string representation of thisOptional suitable for debugging. The exact presentation format is unspecified and may vary between implementations and versions.
      Overrides:
      toString in class Object
      Implementation Requirements:
      If a value is present the result must include its string representation in the result. Empty and presentOptionals must be unambiguously differentiable.
      Returns:
      the string representation of this instance