Package org.aoju.bus.core.lang

Class Optional<T>

java.lang.Object
org.aoju.bus.core.lang.Optional<T>
Type Parameters:
T - 包裹里元素的类型
public class Optional<T> extends Object
复制jdk16中的Optional，进行了一些调整，比jdk8中的Optional多了几个实用的函数
Since:
Java 17+
Author:
Kimi Liu
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    Optional(T value)
    Optional的构造函数

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T> Optional<T>
    empty()
    返回一个空的Optional
    boolean
    equals(Object object)
    判断传入参数是否与 Optional相等 在以下情况下返回true 它也是一个 Optional 并且 它们包裹住的元素都为空 或者 它们包裹住的元素之间相互 equals()
    T
    exceptionOrElse(T other)
    异常则返回另一个可选值
    Optional<T>
    filter(Predicate<? super T> predicate)
    判断包裹里的值存在并且与给定的条件是否满足 (Predicate.test(T)执行结果是否为true) 如果满足条件则返回本身 不满足条件或者元素本身为空时返回一个返回一个空的Optional
    <U> Optional<U>
    flatMap(Function<? super T,? extends Optional<? extends U>> mapper)
    如果包裹里的值存在，就执行传入的操作(Function.apply(T))并返回该操作返回值 如果不存在，返回一个空的Optional 和 map(java.util.function.Function<? super T, ? extends U>)的区别为 传入的操作返回值必须为 Optional
    <U> Optional<U>
    flattedMap(Function<? super T,? extends Optional<? extends U>> mapper)
    如果包裹里的值存在，就执行传入的操作(Function.apply(T))并返回该操作返回值 如果不存在，返回一个空的Optional 和 map(java.util.function.Function<? super T, ? extends U>)的区别为 传入的操作返回值必须为 Optional
    T
    get()
    返回包裹里的元素，取不到则为null，注意！！！此处和Optional.get()不同的一点是本方法并不会抛出NoSuchElementException 如果元素为空，则返回null，如果需要一个绝对不能为null的值，则使用orElseThrow()
    Throwable
    getException()
    获取异常 当调用 ofTry(XSupplier)时，异常信息不会抛出，而是保存，调用此方法获取抛出的异常
    int
    hashCode()
    如果包裹内元素为空，则返回0，否则返回元素的 hashcode
    Optional<T>
    ifPresent(Consumer<? super T> action)
    如果包裹里的值存在，就执行传入的操作(Consumer.accept(T))
    boolean
    isEmpty()
    判断包裹里元素的值是否不存在，不存在为 true，否则为false
    boolean
    isFail()
    是否失败 当调用 ofTry(XSupplier)时，抛出异常则表示失败
    boolean
    isPresent()
    判断包裹里元素的值是否存在，存在为 true，否则为false
    <U> Optional<U>
    map(Function<? super T,? extends U> mapper)
    如果包裹里的值存在，就执行传入的操作(Function.apply(T))并返回一个包裹了该操作返回值的Optional 如果不存在，返回一个空的Optional
    static <T> Optional<T>
    of(Optional<T> optional)
    根据 Optional 构造 Optional
    static <T> Optional<T>
    of(T value)
    返回一个包裹里元素不可能为空的Optional
    static <T extends CharSequence>
    Optional<T>
    ofBlankAble(T value)
    返回一个包裹里元素可能为空的Optional，额外判断了空字符串的情况
    static <T, R extends Collection<T>>
    Optional<R>
    ofEmptyAble(R value)
    返回一个包裹里List集合可能为空的Opt，额外判断了集合内元素为空的情况
    static <T> Optional<T>
    ofNullable(T value)
    返回一个包裹里元素可能为空的Optional
    static <T> Optional<T>
    ofTry(XSupplier<T> supplier)
     
    Optional<T>
    or(Supplier<? extends Optional<? extends T>> supplier)
    如果包裹里元素的值存在，就返回本身，如果不存在，则使用传入的操作执行后获得的 Optional
    T
    orElse(T other)
    如果包裹里元素的值存在，则返回该值，否则返回传入的other
    T
    orElseGet(Supplier<? extends T> supplier)
    如果包裹里元素的值存在，则返回该值，否则返回传入的操作执行后的返回值
    T
    orElseRun(Runnable action)
    如果包裹里元素的值存在，则返回该值，否则执行传入的操作
    T
    orElseThrow()
    如果包裹里的值存在，则返回该值，否则抛出 NoSuchElementException
    <X extends Throwable>
    T
    orElseThrow(Supplier<? extends X> exceptionSupplier)
    如果包裹里的值存在，则返回该值，否则执行传入的操作，获取异常类型的返回值并抛出
    Optional<T>
    peek(Consumer<T> action)
    如果包裹里元素的值存在，就执行对应的操作，并返回本身 如果不存在，返回一个空的Optional 属于 ifPresent(java.util.function.Consumer<? super T>)的链式拓展
    final Optional<T>
    peeks(Consumer<T>... actions)
    如果包裹里元素的值存在，就执行对应的操作集，并返回本身 如果不存在，返回一个空的Optional
    Stream<T>
    stream()
    如果包裹里元素的值存在，就返回一个包含该元素的 Stream, 否则返回一个空元素的 Stream
    Optional<T>
    toOptional()
    转换为 Optional对象
    String
    toString()
    返回包裹内元素调用toString()的结果，不存在则返回null

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Optional

      public Optional(T value)
      Optional的构造函数
      Parameters:
      value - 包裹里的元素

  • Method Details

    • empty

      public static <T> Optional<T> empty()
      返回一个空的Optional
      Type Parameters:
      T - 包裹里元素的类型
      Returns:
      this

    • of

      public static <T> Optional<T> of(Optional<T> optional)
      根据 Optional 构造 Optional
      Type Parameters:
      T - 包裹的元素类型
      Parameters:
      optional - optional
      Returns:
      一个包裹里元素可能为空的 Optional

    • of

      public static <T> Optional<T> of(T value)
      返回一个包裹里元素不可能为空的Optional
      Type Parameters:
      T - 包裹里元素的类型
      Parameters:
      value - 包裹里的元素
      Returns:
      一个包裹里元素不可能为空的 Optional
      Throws:
      NullPointerException - 如果传入的元素为空，抛出 NPE

    • ofNullable

      public static <T> Optional<T> ofNullable(T value)
      返回一个包裹里元素可能为空的Optional
      Type Parameters:
      T - 包裹里元素的类型
      Parameters:
      value - 传入需要包裹的元素
      Returns:
      一个包裹里元素可能为空的 Optional

    • ofBlankAble

      public static <T extends CharSequence> Optional<T> ofBlankAble(T value)
      返回一个包裹里元素可能为空的Optional，额外判断了空字符串的情况
      Type Parameters:
      T - 字符串类型
      Parameters:
      value - 传入需要包裹的元素
      Returns:
      一个包裹里元素可能为空，或者为空字符串的 Optional

    • ofEmptyAble

      public static <T, R extends Collection<T>> Optional<R> ofEmptyAble(R value)
      返回一个包裹里List集合可能为空的Opt，额外判断了集合内元素为空的情况
      Type Parameters:
      T - 包裹里元素的类型
      R - 集合值类型
      Parameters:
      value - 传入需要包裹的元素
      Returns:
      一个包裹里元素可能为空的 Opt

    • ofTry

      public static <T> Optional<T> ofTry(XSupplier<T> supplier)
      Type Parameters:
      T - 类型
      Parameters:
      supplier - 操作
      Returns:
      操作执行后的值

    • get

      public T get()
      返回包裹里的元素，取不到则为null，注意！！！此处和Optional.get()不同的一点是本方法并不会抛出NoSuchElementException 如果元素为空，则返回null，如果需要一个绝对不能为null的值，则使用orElseThrow()

      如果需要一个绝对不能为 null的值，则使用orElseThrow() 做此处修改的原因是，有时候我们确实需要返回一个null给前端，并且这样的时候并不少见 而使用 .orElse(null)需要写整整12个字符，用.get()就只需要6个啦

      Returns:
      包裹里的元素，有可能为null

    • isEmpty

      public boolean isEmpty()
      判断包裹里元素的值是否不存在，不存在为 true，否则为false
      Returns:
      包裹里元素的值不存在 则为 true，否则为false

    • getException

      public Throwable getException()
      获取异常 当调用 ofTry(XSupplier)时，异常信息不会抛出，而是保存，调用此方法获取抛出的异常
      Returns:
      异常

    • isFail

      public boolean isFail()
      是否失败 当调用 ofTry(XSupplier)时，抛出异常则表示失败
      Returns:
      是否失败

    • isPresent

      public boolean isPresent()
      判断包裹里元素的值是否存在，存在为 true，否则为false
      Returns:
      包裹里元素的值存在为 true，否则为false

    • ifPresent

      public Optional<T> ifPresent(Consumer<? super T> action)
      如果包裹里的值存在，就执行传入的操作(Consumer.accept(T))

      例如如果值存在就打印结果 

      
 Optional.ofNullable("Hello!").ifPresent(Console::log);
      Parameters:
      action - 你想要执行的操作
      Returns:
      this
      Throws:
      NullPointerException - 如果包裹里的值存在，但你传入的操作为null时抛出

    • filter

      public Optional<T> filter(Predicate<? super T> predicate)
      判断包裹里的值存在并且与给定的条件是否满足 (Predicate.test(T)执行结果是否为true) 如果满足条件则返回本身 不满足条件或者元素本身为空时返回一个返回一个空的Optional
      Parameters:
      predicate - 给定的条件
      Returns:
      如果满足条件则返回本身, 不满足条件或者元素本身为空时返回一个返回一个空的Optional
      Throws:
      NullPointerException - 如果给定的条件为 null，抛出NPE

    • map

      public <U> Optional<U> map(Function<? super T,? extends U> mapper)
      如果包裹里的值存在，就执行传入的操作(Function.apply(T))并返回一个包裹了该操作返回值的Optional 如果不存在，返回一个空的Optional
      Type Parameters:
      U - 操作返回值的类型
      Parameters:
      mapper - 值存在时执行的操作
      Returns:
      如果包裹里的值存在，就执行传入的操作(Function.apply(T))并返回一个包裹了该操作返回值的Optional， 如果不存在，返回一个空的Optional
      Throws:
      NullPointerException - 如果给定的操作为 null，抛出 NPE

    • flatMap

      public <U> Optional<U> flatMap(Function<? super T,? extends Optional<? extends U>> mapper)
      如果包裹里的值存在，就执行传入的操作(Function.apply(T))并返回该操作返回值 如果不存在，返回一个空的Optional 和 map(java.util.function.Function<? super T, ? extends U>)的区别为 传入的操作返回值必须为 Optional
      Type Parameters:
      U - 操作返回值的类型
      Parameters:
      mapper - 值存在时执行的操作
      Returns:
      如果包裹里的值存在，就执行传入的操作(Function.apply(T))并返回该操作返回值 如果不存在，返回一个空的Optional
      Throws:
      NullPointerException - 如果给定的操作为 null或者给定的操作执行结果为 null，抛出 NPE

    • flattedMap

      public <U> Optional<U> flattedMap(Function<? super T,? extends Optional<? extends U>> mapper)
      如果包裹里的值存在，就执行传入的操作(Function.apply(T))并返回该操作返回值 如果不存在，返回一个空的Optional 和 map(java.util.function.Function<? super T, ? extends U>)的区别为 传入的操作返回值必须为 Optional
      Type Parameters:
      U - 操作返回值的类型
      Parameters:
      mapper - 值存在时执行的操作
      Returns:
      如果包裹里的值存在，就执行传入的操作(Function.apply(T))并返回该操作返回值 如果不存在，返回一个空的Optional
      Throws:
      NullPointerException - 如果给定的操作为 null或者给定的操作执行结果为 null，抛出 NPE
      See Also:

    • peek

      public Optional<T> peek(Consumer<T> action) throws NullPointerException
      如果包裹里元素的值存在，就执行对应的操作，并返回本身 如果不存在，返回一个空的Optional 属于 ifPresent(java.util.function.Consumer<? super T>)的链式拓展
      Parameters:
      action - 值存在时执行的操作
      Returns:
      this
      Throws:
      NullPointerException - 如果值存在，并且传入的操作为 null

    • peeks

      @SafeVarargs public final Optional<T> peeks(Consumer<T>... actions) throws NullPointerException
      如果包裹里元素的值存在，就执行对应的操作集，并返回本身 如果不存在，返回一个空的Optional

      属于 ifPresent(java.util.function.Consumer<? super T>)的链式拓展

      属于 peek(Consumer)的动态拓展

      Parameters:
      actions - 值存在时执行的操作，动态参数，可传入数组，当数组为一个空数组时并不会抛出 NPE
      Returns:
      this
      Throws:
      NullPointerException - 如果值存在，并且传入的操作集中的元素为 null

    • or

      public Optional<T> or(Supplier<? extends Optional<? extends T>> supplier)
      如果包裹里元素的值存在，就返回本身，如果不存在，则使用传入的操作执行后获得的 Optional
      Parameters:
      supplier - 不存在时的操作
      Returns:
      如果包裹里元素的值存在，就返回本身，如果不存在，则使用传入的函数执行后获得的 Optional
      Throws:
      NullPointerException - 如果传入的操作为空，或者传入的操作执行后返回值为空，则抛出 NPE

    • stream

      public Stream<T> stream()
      如果包裹里元素的值存在，就返回一个包含该元素的 Stream, 否则返回一个空元素的 Stream

      该方法能将 Optional 中的元素传递给 Stream 

      
     Stream<Optional<T>> os = ..
     Stream<T> s = os.flatMap(Optional::stream)
      Returns:
      返回一个包含该元素的 Stream或空的 Stream

    • orElse

      public T orElse(T other)
      如果包裹里元素的值存在，则返回该值，否则返回传入的other
      Parameters:
      other - 元素为空时返回的值，有可能为 null.
      Returns:
      如果包裹里元素的值存在，则返回该值，否则返回传入的other

    • exceptionOrElse

      public T exceptionOrElse(T other)
      异常则返回另一个可选值
      Parameters:
      other - 可选值
      Returns:
      如果未发生异常，则返回该值，否则返回传入的other

    • orElseGet

      public T orElseGet(Supplier<? extends T> supplier)
      如果包裹里元素的值存在，则返回该值，否则返回传入的操作执行后的返回值
      Parameters:
      supplier - 值不存在时需要执行的操作，返回一个类型与 包裹里元素类型 相同的元素
      Returns:
      如果包裹里元素的值存在，则返回该值，否则返回传入的操作执行后的返回值
      Throws:
      NullPointerException - 如果之不存在，并且传入的操作为空，则抛出 NPE

    • orElseRun

      public T orElseRun(Runnable action)
      如果包裹里元素的值存在，则返回该值，否则执行传入的操作
      Parameters:
      action - 值不存在时执行的操作
      Returns:
      如果包裹里元素的值存在，则返回该值，否则执行传入的操作
      Throws:
      NullPointerException - 如果值不存在，并且传入的操作为 null

    • orElseThrow

      public T orElseThrow()
      如果包裹里的值存在，则返回该值，否则抛出 NoSuchElementException
      Returns:
      返回一个不为 null 的包裹里的值
      Throws:
      NoSuchElementException - 如果包裹里的值不存在则抛出该异常

    • orElseThrow

      public <X extends Throwable> T orElseThrow(Supplier<? extends X> exceptionSupplier) throws X
      如果包裹里的值存在，则返回该值，否则执行传入的操作，获取异常类型的返回值并抛出

      往往是一个包含无参构造器的异常 例如传入IllegalStateException::new

      Type Parameters:
      X - 异常类型
      Parameters:
      exceptionSupplier - 值不存在时执行的操作，返回值继承 Throwable
      Returns:
      包裹里不能为空的值
      Throws:
      X - 如果值不存在
      NullPointerException - 如果值不存在并且 传入的操作为 null或者操作执行后的返回值为null

    • toOptional

      public Optional<T> toOptional()
      转换为 Optional对象
      Returns:
      Optional对象

    • equals

      public boolean equals(Object object)
      判断传入参数是否与 Optional相等 在以下情况下返回true
      • 它也是一个 Optional 并且
      • 它们包裹住的元素都为空 或者
      • 它们包裹住的元素之间相互 equals()
      Overrides:
      equals in class Object
      Parameters:
      object - 一个要用来判断是否相等的参数
      Returns:
      如果传入的参数也是一个 Optional并且它们包裹住的元素都为空 或者它们包裹住的元素之间相互 equals() 就返回true 否则返回 false

    • hashCode

      public int hashCode()
      如果包裹内元素为空，则返回0，否则返回元素的 hashcode
      Overrides:
      hashCode in class Object
      Returns:
      如果包裹内元素为空，则返回0，否则返回元素的 hashcode

    • toString

      public String toString()
      返回包裹内元素调用toString()的结果，不存在则返回null
      Overrides:
      toString in class Object
      Returns:
      包裹内元素调用toString()的结果，不存在则返回null