Module java.base
Package java.util

Class 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; use of identity-sensitive operations (including reference equality (==), identity hash code, or synchronization) on instances ofOptional may have unpredictable results and should be avoided.

    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

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and TypeMethodDescription
      static <T> Optional<T>empty()
      Returns an emptyOptional instance.
      booleanequals​(Object obj)
      Indicates whether some other object is "equal to" thisOptional.
      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.
      <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.
      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<? superT> action)
      If a value is present, performs the given action with the value, otherwise does nothing.
      voidifPresentOrElse​(Consumer<? superT> 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<? 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.
      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.
      TorElse​(T other)
      If a value is present, returns the value, otherwise returnsother.
      TorElseGet​(Supplier<? extendsT> 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 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.
      Stream<T>stream()
      If a value is present, returns a sequentialStream containing only that value, otherwise returns an emptyStream.
      StringtoString()
      Returns a non-empty string representation of thisOptional suitable for debugging.

    • Method Detail

      • 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== 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 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)                                    throws 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
        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
        X extendsThrowable

      • 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:
        Object.hashCode(),HashMap

      • 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