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:

• Optional

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，注意！！！
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:

• Optional.flatMap(Function)

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