模块  java.base
软件包  java.util

Class Optional<T>

  • 参数类型
    T - 价值类型

    public final class Optional<T>extends Object
    容器对象,可能包含也可能不包含非null值。 如果存在值,则isPresent()返回true 如果没有值,则该对象被视为isPresent()返回false

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

    这是一个value-based类; Optional实例上使用身份敏感操作(包括引用相等( == ),标识哈希码或同步)可能会产生不可预测的结果,应该避免使用。

    API Note:
    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 mapping函数应用于该值的结果,否则返回空 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的非空字符串表示形式。
    • 方法详细信息

      • 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 - 可能 nullnull
        结果
        Optional如果指定值为非 null ,则为现值,否则为空 Optional
      • get

        public T get()
        如果存在值,则返回该值,否则抛出 NoSuchElementException
        API Note:
        该方法的优选替代方案是 orElseThrow()
        结果
        null通过该所述值 Optional
        异常
        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 Note:
        此方法支持对Optional值进行后处理,而无需显式检查返回状态。 例如,以下代码遍历URI流,选择尚未处理的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 (如果存在值),否则为空 Optional
        异常
        NullPointerException - 如果映射功能是 null
      • flatMap

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

        此方法类似于map(Function) ,但映射函数的结果已经是Optional ,如果调用,则flatMap不会将其包装在另外的Optional

        参数类型
        U - 映射函数返回的 Optional的值的类型
        参数
        mapper - 要应用于值的映射函数(如果存在)
        结果
        Optional mapping函数应用于此 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
           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
        结果
        null通过该所述值 Optional
        异常
        NoSuchElementException - 如果没有值
        从以下版本开始:
        10
      • orElseThrow

        public <X extends ThrowableT 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必须明确可区分。
        结果
        此实例的字符串表示形式