Module  java.base
软件包  java.util

Class Optional<T>

  • 参数类型
    T - 值的类型 

    public final class Optional<T>
extends Object
    可能包含或不包含非null值的容器对象。 如果存在值，则isPresent()返回true ，返回值为get() 。

    提供依赖于存在或不存在包含值的附加方法，例如orElse() （如果没有值，则返回默认值）和ifPresent() （如果值存在则执行操作）。

    这是一个value-based课; 在Optional实例上使用身份敏感操作（包括引用等式（ == ），身份哈希码或同步）可能会产生不可预知的结果，应该避免。

    API Note:
    Optional主要用作方法返回类型，其中明确需要表示“否结果”，并且使用null可能会导致错误。 类型为Optional变量本身不应为null ; 它应该总是指向一个Optional实例。
    从以下版本开始：
    1.8

    • 方法摘要

      所有方法  静态方法  接口方法  具体的方法 
      Modifier and Type 方法 描述
      static <T> Optional<T> empty​()
      返回一个空的 Optional实例。
      boolean equals​(Object obj)
      指示某个其他对象是否等于此 Optional 。
      Optional<T> filter​(Predicate<? super T> predicate)
      如果存在值，并且该值与给定谓词匹配，则返回描述该值的 Optional ，否则返回一个空的 Optional 。
      <U> Optional<U> flatMap​(Function<? super T,? extends Optional<? extends U>> mapper)
      如果存在值，则返回将给定的 Optional映射函数应用于该值的结果，否则返回一个空的 Optional 。
      T get​()
      如果值存在，则返回值，否则抛出 NoSuchElementException 。
      int hashCode​()
      返回值的哈希码（如果存在），否则，如果没有值，则 0 （零）。
      void ifPresent​(Consumer<? super T> action)
      如果存在值，则使用该值执行给定的操作，否则不执行任何操作。
      void ifPresentOrElse​(Consumer<? super T> action, Runnable emptyAction)
      如果存在值，则使用该值执行给定的操作，否则执行给定的基于空的操作。
      boolean isPresent​()
      如果存在值，则返回 true ，否则为 false 。
      <U> Optional<U> map​(Function<? super T,? extends U> mapper)
      如果存在值，则返回一个 Optional描述（如果由 ofNullable(T) ）将给定的映射函数应用于该值的结果，否则返回一个空的 Optional 。
      static <T> Optional<T> of​(T value)
      返回一个 Optional描述给定的非 null值。
      static <T> Optional<T> ofNullable​(T value)
      返回描述给定值的 Optional ，如果 null ，否则返回一个空的 Optional 。
      Optional<T> or​(Supplier<? extends Optional<? extends T>> supplier)
      如果值存在时，返回一个 Optional描述的值，否则返回一个 Optional通过供给函数产生。
      T orElse​(T other)
      如果存在值，则返回值，否则返回 other 。
      T orElseGet​(Supplier<? extends T> supplier)
      如果存在值，则返回值，否则返回由供应函数产生的结果。
      <X extends Throwable>
      T      		 orElseThrow​(Supplier<? extends X> exceptionSupplier)
      如果存在值，则返回值，否则将抛出由异常提供函数产生的异常。
      Stream<T> stream​()
      如果存在值，则返回仅包含该值的序列Stream ，否则返回空Stream 。
      String toString​()
      返回适用于调试的 Optional的非空字符串表示形式。

    • 方法详细信息

      • empty

        public static <T> Optional<T> empty​()
        返回一个空的Optional实例。 这个Optional没有值。
        API Note:
        虽然可能很容易这样做，但如果对象是空的，则通过与==返回的实例进行比较，避免测试是否为Optional.empty() 。 不能保证是单身人士。 相反，请使用isPresent() 。
        参数类型
        T - 不存在的值的类型
        结果
        一个空的 Optional

      • of

        public static <T> Optional<T> of​(T value)
        返回一个 Optional描述给定的非 null值。
        参数类型
        T - 值的类型
        参数
        value - 要描述的值，它必须是非 null
        结果
        一个 Optional的值存在
        异常
        NullPointerException - 如果值为 null

      • ofNullable

        public static <T> Optional<T> ofNullable​(T value)
        返回描述给定值的 Optional ，如果非 null ，否则返回一个空的 Optional 。
        参数类型
        T - 值的类型
        参数
        value - 可能描述的 null值
        结果
        一个 Optional ，如果指定的值不是 null ，其值为现值，否则为空 Optional

      • get

        public T get​()
        如果存在值，返回值，否则抛出 NoSuchElementException 。
        API Note:
        方法 orElse和 orElseGet通常优于该方法，因为如果该值不存在则返回替代值，而不是抛出异常。
        结果
        该 null值描述为 Optional
        异常
        NoSuchElementException - 如果没有值
        另请参见：
        isPresent()

      • isPresent

        public boolean isPresent​()
        如果值存在，则返回 true ，否则为 false 。
        结果
        true如果一个值存在，否则 false

      • ifPresent

        public void ifPresent​(Consumer<? super T> action)
        如果存在值，则使用该值执行给定的操作，否则不执行任何操作。
        参数
        action - 要执行的操作，如果值存在
        异常
        NullPointerException - 如果值存在，给定的操作是 null

      • ifPresentOrElse

        public void ifPresentOrElse​(Consumer<? super T> action,
                            Runnable emptyAction)
        如果存在值，则使用该值执行给定的操作，否则执行给定的基于空的操作。
        参数
        action - 要执行的操作，如果值存在
        emptyAction - 要执行的基于空的操作，如果没有值
        异常
        NullPointerException - 如果存在值且给定的操作是 null ，或者不存在任何值，并且给定的基于空的操作是 null 。
        从以下版本开始：
        9

      • filter

        public Optional<T> filter​(Predicate<? super T> predicate)
        如果存在值，并且该值与给定谓词匹配，则返回描述该值的 Optional ，否则返回一个空的 Optional 。
        参数
        predicate - 应用于值的谓词（如果存在）
        结果
        一个 Optional描述了这个 Optional的值，如果一个值存在，该值与给定的谓词匹配，否则为空 Optional
        异常
        NullPointerException - 如果谓词是 null

      • map

        public <U> Optional<U> map​(Function<? super T,? extends U> mapper)
        如果存在一个值，则返回一个Optional描述（如果由ofNullable(T) ）将给定的映射函数应用于该值的结果，否则返回一个空的Optional 。

        如果映射函数返回一个null结果，那么这个方法返回一个空的Optional 。

        API Note:
        此方法支持对Optional值进行后处理，无需显式检查返回状态。 例如，以下代码遍历一个URI流，选择一个未处理的流，并从该URI创建路径，返回一个Optional<Path> ： 
           Optional<Path> p = uris.stream().filter(uri -> !isProcessedYet(uri)) .findFirst() .map(Paths::get);
        这里， findFirst返回一个Optional<URI> ，然后map返回一个Optional<Path>为所需的URI（如果存在）。
        参数类型
        U - 从映射函数返回的值的类型
        参数
        mapper - 应用于值的映射函数（如果存在）
        结果
        一个 Optional描述了将映射函数应用于该值的值的 Optional ，如果值存在，否则为空 Optional
        异常
        NullPointerException - 映射函数是否为 null

      • flatMap

        public <U> Optional<U> flatMap​(Function<? super T,? extends Optional<? extends U>> mapper)
        如果存在值，则返回将给定的Optional映射函数应用于该值的结果，否则返回一个空的Optional 。

        此方法类似于map(Function) ，但映射函数的结果已经是Optional ，如果被调用， flatMap不会在额外的Optional 。

        参数类型
        U - 映射函数返回的 Optional的值的类型
        参数
        mapper - 应用于值的映射函数（如果存在）
        结果
        将 Optional映射函数应用于此 Optional的值的 Optional ，如果存在值，否则为空 Optional
        异常
        NullPointerException - 如果映射函数是 null或返回一个 null结果

      • or

        public Optional<T> or​(Supplier<? extends Optional<? extends T>> supplier)
        如果值存在时，返回一个 Optional描述的值，否则返回一个 Optional通过供给函数产生。
        参数
        supplier - 产生要返回的 Optional的供应功能
        结果
        返回一个描述 Optional的值的 Optional ，如果存在一个值，否则由供应函数产生一个 Optional 。
        异常
        NullPointerException - 如果供应功能是 null或产生一个 null结果
        从以下版本开始：
        9

      • stream

        public Stream<T> stream​()
        如果存在值，则返回仅包含该值的序列Stream ，否则返回空Stream 。
        API Note:
        该方法可用于将Stream的可选元素转换为Stream的现值元素： 
           Stream<Optional<T>> os = .. Stream<T> s = os.flatMap(Optional::stream)
        结果
        可选值为 Stream
        从以下版本开始：
        9

      • orElse

        public T orElse​(T other)
        如果存在值，则返回值，否则返回 other 。
        参数
        other - 如果没有值，则返回的值。 可能是null 。
        结果
        该值，如果存在，否则为 other

      • orElseGet

        public T orElseGet​(Supplier<? extends T> supplier)
        如果存在值，则返回值，否则返回由供应函数产生的结果。
        参数
        supplier - 产生要返回的值的供应函数
        结果
        该值（如果存在），否则由供应功能产生的结果
        异常
        NullPointerException - 如果没有值，并且提供功能是 null

      • orElseThrow

        public <X extends Throwable> T orElseThrow​(Supplier<? extends X> exceptionSupplier)
                                    throws X extends Throwable
        如果存在值，则返回值，否则将抛出由异常提供函数产生的异常。
        API Note:
        可以使用具有空参数列表的异常构造函数的方法引用作为供应商。 例如， IllegalStateException::new
        参数类型
        X - 要抛出的异常的类型
        参数
        exceptionSupplier - 产生要抛出的异常的供应函数
        结果
        价值，如果存在
        异常
        X - 如果没有值
        NullPointerException - 如果没有值，异常提供功能是 null
        X extends Throwable

      • equals

        public boolean equals​(Object obj)
        指示某个其他对象是否等于此Optional 。 另一个对象被认为是相等的：
        • 它也是一个Optional和;
        • 或者;
        • 当前值通过equals()彼此“相等”。
        重写：
        equals在 Object
        参数
        obj - 要进行相等测试的对象
        结果
        true如果另一个对象是“等于”这个对象否则 false
        另请参见：
        Object.hashCode() ， HashMap

      • toString

        public String toString​()
        返回适用于调试的Optional的非空字符串表示形式。 准确的表示格式是未指定的，可能会在实现和版本之间变化。
        重写：
        toString在 Object
        实现要求：
        如果存在值，则结果必须在其结果中包含其字符串表示形式。 空和现在Optional必须明确区分。
        结果
        该实例的字符串表示形式