Module java.base
Package java.util

Class Optional<T>

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

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

这是一个基于值的类；程序员应该将相等的实例视为可互换，并且不应将实例用于同步，否则可能会导致不可预测的行为。例如，在将来的版本中，同步可能会失败。

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

  • Method Summary

    Modifier and Type
    Method
    Description
    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)
    返回描述给定非null值的Optional。
    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的非空字符串表示形式，适用于调试。

    Methods declared in class java.lang.Object

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

  • Method Details

    • 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)
      返回描述给定非null值的Optional。
      类型参数:
      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 注释:
      此方法的首选替代方法是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。

      如果映射函数返回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的Optional<Path>（如果存在）。
      类型参数:
      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
      抛出:
      NullPointerException - 如果映射函数为null或返回null结果

    • or

      public Optional<T> or(Supplier<? extends Optional<? extends T>> supplier)
      如果存在值，则返回描述该值的Optional，否则返回由提供函数生成的Optional。
      参数:
      supplier - 生成要返回的Optional的提供函数
      返回:
      返回描述此Optional的值的Optional（如果存在值），否则返回由提供函数生成的Optional
      抛出:
      NullPointerException - 如果提供函数为null或产生null结果
      自 JDK 版本:
      9

    • stream

      public Stream<T> stream()
      如果存在值，则返回包含该值的顺序Stream，否则返回一个空的Stream。
      API 注释:
      此方法可用于将可选元素的Stream转换为具有现有值元素的Stream： 
      
     Stream<Optional<T>> os = ..
     Stream<T> s = os.flatMap(Optional::stream)
      返回:
      作为Stream的可选值
      自 JDK 版本:
      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 - 如果不存在值
      自 JDK 版本:
      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必须能够明确区分。
      返回:
      此实例的字符串表示形式