Package org.miaixz.bus.core.lang

Class Optional<T>

java.lang.Object

org.miaixz.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:

• 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(PredicateX<? super T> predicate)	判断包裹里的值存在并且与给定的条件是否满足 (Predicate.test(T)执行结果是否为true) 如果满足条件则返回本身 不满足条件或者元素本身为空时返回一个返回一个空的Optional predicate测试报错，则返回一个空的Optional，并附带错误信息
<U> Optional<U>	flattedMap(FunctionX<? super T,? extends Optional<? extends U>> mapper)	如果包裹里的值存在，就执行传入的操作(Function.apply(T))并返回该操作返回值 如果不存在，返回一个空的Optional 和 map(org.miaixz.bus.core.center.function.FunctionX<? super T, ? extends U>)的区别为 传入的操作返回值必须为 Optional
T	getOrNull()	返回包裹里的元素，取不到则为null，注意！！！
T	getOrThrow()	返回包裹里的元素，取不到则抛出异常
Throwable	getThrowable()	获取异常 当调用 ofTry(SupplierX)时，异常信息不会抛出，而是保存，调用此方法获取抛出的异常
int	hashCode()	如果包裹内元素为空，则返回0，否则返回元素的 hashcode
Optional<T>	ifFail(Consumer<? super Throwable> action)	如果包裹内容失败了，则执行传入的操作(Consumer.accept(T)) 例如执行有异常就打印结果
final Optional<T>	ifFail(Consumer<? super Throwable> action, Class<? extends Throwable>... exs)	如果包裹内容失败了，同时是指定的异常执行传入的操作(Consumer.accept(T)) 例如如果值存在就打印结果
Optional<T>	ifPresent(ConsumerX<? super T> action)	如果包裹里的值存在，就执行传入的操作(Consumer.accept(T)) 例如如果值存在就打印结果
final Optional<T>	ifPresents(ConsumerX<T>... actions)	如果包裹里元素的值存在，就执行对应的操作集，并返回本身 如果不存在，返回一个空的Optional 属于 ifPresent(ConsumerX)的动态拓展
boolean	isEmpty()	判断包裹里元素的值是否不存在，不存在为 true，否则为false
boolean	isFail()	是否失败 当调用 ofTry(SupplierX)时，抛出异常则表示失败
boolean	isPresent()	判断包裹里元素的值是否存在，存在为 true，否则为false
<U> Optional<U>	map(FunctionX<? super T,? extends U> mapper)	如果包裹里的值存在，就执行传入的操作(FunctionX.applying(Object))并返回一个包裹了该操作返回值的Opt 如果不存在，返回一个空的Optional
static <T> Optional<T>	of(Optional<? extends 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集合可能为空的Optional，额外判断了集合内元素为空的情况
static <T> Optional<T>	ofNullable(T value)	返回一个包裹里元素可能为空的Optional
static <T> Optional<T>	ofTry(SupplierX<T> supplier)
Optional<T>	or(SupplierX<? extends Optional<? extends T>> supplier)	如果包裹里元素的值存在，就返回本身，如果不存在，则使用传入的操作执行后获得的 Optional
T	orElse(T other)	如果包裹里元素的值存在，则返回该值，否则返回传入的other
T	orElseGet(SupplierX<? extends T> supplier)	如果包裹里元素的值存在，则返回该值，否则返回传入的操作执行后的返回值
Optional<T>	orElseOpt(SupplierX<? extends T> supplier)	如果包裹里元素的值存在，则返回该值，否则返回传入的操作执行后的返回值
T	orElseRun(Runnable action)	如果包裹里元素的值存在，则返回该值，否则执行传入的操作
T	orElseThrow()	如果包裹里的值存在，则返回该值，否则抛出 NoSuchElementException
<X extends Throwable> T	orElseThrow(SupplierX<? extends X> exceptionSupplier)	如果包裹里的值存在，则返回该值，否则执行传入的操作，获取异常类型的返回值并抛出 往往是一个包含无参构造器的异常 例如传入IllegalStateException::new
Stream<T>	stream()	如果包裹里元素的值存在，就返回一个包含该元素的 Stream, 否则返回一个空元素的 Stream 该方法能将 Optional 中的元素传递给 Stream
EasyStream<T>	toEasyStream()	转换为 EasyStream对象
Optional<T>	toOptional()	转换为 Optional对象
String	toString()	返回包裹内元素调用toString()的结果，不存在则返回null

Methods inherited from class java.lang.Object

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

Method Details

empty

public static <T> Optional<T> empty()

返回一个空的Optional

Type Parameters:

T - 包裹里元素的类型

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集合可能为空的Optional，额外判断了集合内元素为空的情况

Type Parameters:

T - 包裹里元素的类型

R - 集合值类型

Parameters:

value - 传入需要包裹的元素，支持CharSequence、Map、Iterable、Iterator、Array类型

Returns:

一个包裹里元素可能为空的 Optional

ofTry

public static <T> Optional<T> ofTry(SupplierX<T> supplier)

Type Parameters:

T - 类型

Parameters:

supplier - 操作

Returns:

操作执行后的值

of

public static <T> Optional<T> of(Optional<? extends T> optional)

根据 Optional 构造 Optional

Type Parameters:

T - 包裹的元素类型

Parameters:

optional - optional

Returns:

一个包裹里元素可能为空的 Optional

getOrNull

public T getOrNull()

返回包裹里的元素，取不到则为null，注意！！！此处和Optional.get()不同的一点是本方法并不会抛出NoSuchElementException 如果元素为空，则返回null，如果需要一个绝对不能为 null的值，则使用orElseThrow() 做此处修改的原因是，有时候我们确实需要返回一个null给前端，并且这样的时候并不少见 而使用 .orElse(null)需要写整整12个字符，用.get()就只需要6个啦

Returns:

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

getOrThrow

public T getOrThrow()
             throws NoSuchElementException

返回包裹里的元素，取不到则抛出异常

Returns:

包裹里的元素

Throws:

NoSuchElementException - 如果元素为空，则抛出此异常

isEmpty

public boolean isEmpty()

判断包裹里元素的值是否不存在，不存在为 true，否则为false

Returns:

包裹里元素的值不存在 则为 true，否则为false

getThrowable

public Throwable getThrowable()

获取异常 当调用 ofTry(SupplierX)时，异常信息不会抛出，而是保存，调用此方法获取抛出的异常

Returns:

异常

isFail

public boolean isFail()

是否失败 当调用 ofTry(SupplierX)时，抛出异常则表示失败

Returns:

是否失败

ifFail

public Optional<T> ifFail(Consumer<? super Throwable> action)
                   throws NullPointerException

如果包裹内容失败了，则执行传入的操作(Consumer.accept(T)) 例如执行有异常就打印结果

 Optional.ofTry(() -> 1 / 0).ifFail(Console::logger);
 

Parameters:

action - 你想要执行的操作

Returns:

this

Throws:

NullPointerException - 如果包裹里的值存在，但你传入的操作为null时抛出

ifFail

@SafeVarargs
public final Optional<T> ifFail(Consumer<? super Throwable> action,
 Class<? extends Throwable>... exs)
                         throws NullPointerException

如果包裹内容失败了，同时是指定的异常执行传入的操作(Consumer.accept(T)) 例如如果值存在就打印结果

 Optional.ofTry(() -> 1 / 0).ifFail(Console::logger, ArithmeticException.class);
 

Parameters:

action - 你想要执行的操作

exs - 限定的异常

Returns:

this

Throws:

NullPointerException - 如果包裹里的值存在，但你传入的操作为null时抛出

isPresent

public boolean isPresent()

判断包裹里元素的值是否存在，存在为 true，否则为false

Returns:

包裹里元素的值存在为 true，否则为false

ifPresent

public Optional<T> ifPresent(ConsumerX<? super T> action)

如果包裹里的值存在，就执行传入的操作(Consumer.accept(T)) 例如如果值存在就打印结果

 Optional.ofNullable("Hello!").ifPresent(Console::logger);
 

Parameters:

action - 你想要执行的操作

Returns:

this

Throws:

NullPointerException - 如果包裹里的值存在，但你传入的操作为null时抛出

filter

public Optional<T> filter(PredicateX<? super T> predicate)

判断包裹里的值存在并且与给定的条件是否满足 (Predicate.test(T)执行结果是否为true) 如果满足条件则返回本身 不满足条件或者元素本身为空时返回一个返回一个空的Optional predicate测试报错，则返回一个空的Optional，并附带错误信息

Parameters:

predicate - 给定的条件

Returns:

如果满足条件则返回本身, 不满足条件或者元素本身为空时返回一个空的Optional

Throws:

NullPointerException - 如果给定的条件为 null抛出NPE

map

public <U> Optional<U> map(FunctionX<? super T,? extends U> mapper)

如果包裹里的值存在，就执行传入的操作(FunctionX.applying(Object))并返回一个包裹了该操作返回值的Opt 如果不存在，返回一个空的Optional

Type Parameters:

U - 操作返回值的类型

Parameters:

mapper - 值存在时执行的操作

Returns:

如果包裹里的值存在，就执行传入的操作(FunctionX.applying(Object))并返回一个包裹了该操作返回值的Opt， 如果不存在，返回一个空的Optional

Throws:

NullPointerException - 如果给定的操作为 null，抛出 NPE

flattedMap

public <U> Optional<U> flattedMap(FunctionX<? super T,? extends Optional<? extends U>> mapper)

如果包裹里的值存在，就执行传入的操作(Function.apply(T))并返回该操作返回值 如果不存在，返回一个空的Optional 和 map(org.miaixz.bus.core.center.function.FunctionX<? super T, ? extends U>)的区别为 传入的操作返回值必须为 Optional

Type Parameters:

U - 操作返回值的类型

Parameters:

mapper - 值存在时执行的操作

Returns:

如果包裹里的值存在，就执行传入的操作(Function.apply(T))并返回该操作返回值 如果不存在，返回一个空的Optional

Throws:

NullPointerException - 如果给定的操作为 null或者给定的操作执行结果为 null，抛出 NPE

See Also:

• Optional.flatMap(Function)

ifPresents

@SafeVarargs
public final Optional<T> ifPresents(ConsumerX<T>... actions)
                             throws NullPointerException

如果包裹里元素的值存在，就执行对应的操作集，并返回本身 如果不存在，返回一个空的Optional 属于 ifPresent(ConsumerX)的动态拓展

Parameters:

actions - 值存在时执行的操作，动态参数，可传入数组，当数组为一个空数组时并不会抛出 NPE

Returns:

this

Throws:

NullPointerException - 如果值存在，并且传入的操作集中的元素为 null

or

public Optional<T> or(SupplierX<? extends Optional<? extends T>> supplier)

如果包裹里元素的值存在，就返回本身，如果不存在，则使用传入的操作执行后获得的 Optional

Parameters:

supplier - 不存在时的操作

Returns:

如果包裹里元素的值存在，就返回本身，如果不存在，则使用传入的函数执行后获得的 Optional

Throws:

NullPointerException - 如果传入的操作为空，或者传入的操作执行后返回值为空，则抛出

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(SupplierX<? extends T> supplier)

如果包裹里元素的值存在，则返回该值，否则返回传入的操作执行后的返回值

Parameters:

supplier - 值不存在时需要执行的操作，返回一个类型与 包裹里元素类型 相同的元素

Returns:

如果包裹里元素的值存在，则返回该值，否则返回传入的操作执行后的返回值

Throws:

NullPointerException - 如果之不存在，并且传入的操作为空，则抛出 NPE

orElseOpt

public Optional<T> orElseOpt(SupplierX<? 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(SupplierX<? 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对象

toEasyStream

public EasyStream<T> toEasyStream()

转换为 EasyStream对象

Returns:

EasyStream对象

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