模块 java.base
包 java.util

类 Optional<T>

java.lang.Object
java.util.Optional<T>
类型参数：
T - 值的类型
public final class Optional<T> extends Object
可能包含也可能不包含非null值的容器对象。如果存在值，则 isPresent() 返回 true 。如果没有值，则认为该对象emptyisPresent() 返回 false 。

提供了依赖于包含值是否存在的其他方法，例如 orElse() （如果不存在值则返回默认值）和 ifPresent() （如果存在值则执行操作）。

这是一个value-based类；程序员应该将 equal 的实例视为可互换的，并且不应使用实例进行同步，否则可能会发生不可预测的行为。例如，在未来的版本中，同步可能会失败。

API 注意：
Optional 主要用作方法返回类型，其中明确需要表示“无结果”，并且使用 null 可能会导致错误。类型为 Optional 的变量本身永远不应该是 null ；它应该始终指向一个 Optional 实例。
自从：
1.8

  • 方法总结

    修饰符和类型
    方法
    描述
    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
    isEmpty()
    如果值不存在，则返回 true ，否则返回 false 。
    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)
    如果存在值，则返回该值，否则返回由提供函数生成的结果。
    T
    orElseThrow()
    如果存在值，则返回该值，否则抛出 NoSuchElementException 。
    <X extends Throwable>
    T
    orElseThrow(Supplier<? extends X> exceptionSupplier)
    如果存在值，则返回该值，否则抛出由异常提供函数产生的异常。
    Stream<T>
    stream()
    如果存在值，则返回仅包含该值的顺序 Stream ，否则返回空的 Stream。
    String
    toString()
    返回适合调试的此 Optional 的非空字符串表示形式。

    在类 java.lang.Object 中声明的方法

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

  • 方法详情

    • empty

      public static <T> Optional <T> empty()
      返回一个空的 Optional 实例。此 Optional 没有值。
      API 注意：
      尽管这样做可能很诱人，但请避免通过将 == 或 != 与 Optional.empty() 返回的实例进行比较来测试对象是否为空。不能保证它是单例。相反，使用 isEmpty() 或 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值
      返回：
      如果指定值是非 null ，则为具有现值的 Optional ，否则为空 Optional

    • get

      public T  get()
      如果存在值，则返回该值，否则抛出 NoSuchElementException 。
      API 注意：
      此方法的首选替代方法是 orElseThrow() 。
      返回：
      这个Optional描述的非null值
      抛出：
      NoSuchElementException - 如果没有值

    • isPresent

      public boolean isPresent()
      如果存在值，则返回 true ，否则返回 false 。
      返回：
      true 如果存在值，否则 false

    • isEmpty

      public boolean isEmpty()
      如果值不存在，则返回 true ，否则返回 false 。
      返回：
      true 如果值不存在，否则 false
      自从：
      11

    • 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 。

      如果map函数返回 null 结果，则此方法返回空 Optional 。

      API 注意：
      此方法支持对 Optional 值进行后处理，无需显式检查返回状态。例如，以下代码遍历 URI 流，选择一个尚未处理的 URI，并从该 URI 创建路径，返回一个 Optional<Path>： 
      
   Optional<Path> p =
     uris.stream().filter(uri -> !isProcessedYet(uri))
            .findFirst()
            .map(Paths::get);
      这里，findFirst 返回一个 Optional<URI>，然后 map 返回一个URI（如果存在）。
      类型参数：
      U - 映射函数返回值的类型
      参数：
      mapper - 应用于值的映射函数（如果存在）
      返回：
      Optional 描述将映射函数应用于此 Optional 的值的结果，如果存在值，否则为空 Optional
      抛出：
      NullPointerException - 如果map函数是 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
      抛出：
      NullPointerException - 如果map函数是 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 注意：
      此方法可用于将可选元素的 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 T  orElseThrow()
      如果存在值，则返回该值，否则抛出 NoSuchElementException 。
      返回：
      这个Optional描述的非null值
      抛出：
      NoSuchElementException - 如果没有值
      自从：
      10

    • orElseThrow

      public <X extends Throwable > T  orElseThrow(Supplier <? extends X> exceptionSupplier) throws X
      如果存在值，则返回该值，否则抛出由异常提供函数产生的异常。
      API 注意：
      对具有空参数列表的异常构造函数的方法引用可以用作提供者。例如，IllegalStateException::new
      类型参数：
      X - 要抛出的异常类型
      参数：
      exceptionSupplier - 产生要抛出的异常的提供函数
      返回：
      值，如果存在
      抛出：
      X - 如果没有值
      NullPointerException - 如果没有值存在并且异常提供函数是 null

    • equals

      public boolean equals(Object  obj)
      指示某个其他对象是否“等于”此 Optional 。另一个对象被认为是相等的，如果：
      • 它也是一个 Optional 和；
      • 两个实例都没有值，或者；
      • 当前值通过 equals() 彼此“相等”。
      重写：
      equals 在类 Object 中
      参数：
      obj - 要进行相等性测试的对象
      返回：
      true 如果另一个对象“等于”这个对象，否则 false
      参见：

    • hashCode

      public int hashCode()
      返回值的哈希码（如果存在），否则如果不存在值则返回 0（零）。
      重写：
      hashCode 在类 Object 中
      返回：
      当前值的哈希码值或 0（如果不存在值）
      参见：

    • toString

      public String  toString()
      返回适合调试的此 Optional 的非空字符串表示形式。确切的表示格式未指定，并且可能因实现和版本而异。
      重写：
      toString 在类 Object 中
      实现要求：
      如果存在值，则结果中必须包含其字符串表示形式。空的和现在的 Optional 必须是明确可区分的。
      返回：
      此实例的字符串表示形式