java.util.Optional源码解读

/*
 * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */
package java.util;

import java.util.function.Consumer;
import java.util.function.Function;
import java.util.function.Predicate;
import java.util.function.Supplier;

/**
 * A container object which may or may not contain a non-null value.
 * If a value is present, {@code isPresent()} will return {@code true} and
 * {@code get()} will return the value.
 *
 * 

Additional methods that depend on the presence or absence of a contained * value are provided, such as {@link #orElse(java.lang.Object) orElse()} * (return a default value if value not present) and * {@link #ifPresent(java.util.function.Consumer) ifPresent()} (execute a block * of code if the value is present). * *

This is a value-based * class; use of identity-sensitive operations (including reference equality * ({@code ==}), identity hash code, or synchronization) on instances of * {@code Optional} may have unpredictable results and should be avoided. * * 一个判断实体是否为空的容器,如果有值,返回true, 无值的话返回false * 并扩展了一些其他的获取当前值得方法 * * 容器的创建方式: * @method Optional() 创建一个空实例 * @method Optional(T) 创建一个实例 如果参数为null的话,会抛出空指针异常 * @methid empty() 创建一个空实例,等同于Optional() * @methid of() 创建带参实例,等同于Optional(T) * @method ofNullable(T) 如果参数不为空,返回带参实例,为空的话返回空实例 * * 判断当前容器的状态 * @method isPresent() 判断当前实例是否有值 * @method isPresent(Consumer) 判断当前实例是否有值,有值的话执行消费信息 * * 获取当前容器的值 * @method get() 获取当前实例的值,如果实例为空的话会抛出异常 * @method orElse(T) 获取当前实例的值,如果值不存在返回当前参数 * @method orElseGet(Supplier) 获取当前值,值不存在返回指定实现的返回值 * * 对当前容器的值进行数据处理 * @method filter(Predicate) 过滤实例,如果当前值符合规则,则返回, 否则返回空实例 * @method map(Function) * @method flatMap(Function>) * * @since 1.8 */ public final class Optional { /** * Common instance for {@code empty()}. * 通用的空实例 */ private static final Optional EMPTY = new Optional<>(); /** * If non-null, the value; if null, indicates no value is present * 保存当前容器的值 */ private final T value; /** * Constructs an empty instance. * 构造方法, 返回空的容器 * @implNote Generally only one empty instance, {@link Optional#EMPTY}, * should exist per VM. */ private Optional() { this.value = null; } /** * Returns an empty {@code Optional} instance. No value is present for this * Optional. * 返回一个空的实例, 该实例没有value * * @apiNote Though it may be tempting to do so, avoid testing if an object * is empty by comparing with {@code ==} against instances returned by * {@code Option.empty()}. There is no guarantee that it is a singleton. * Instead, use {@link #isPresent()}. * * @param Type of the non-existent value * @return an empty {@code Optional} */ public static Optional empty() { @SuppressWarnings("unchecked") Optional t = (Optional) EMPTY; return t; } /** * Constructs an instance with the value present. * 创建一个实例, 实例的值为传递参数 * 如果参数为null的话,会抛出空指针异常 * @param value the non-null value to be present * @throws NullPointerException if value is null */ private Optional(T value) { this.value = Objects.requireNonNull(value); } /** * Returns an {@code Optional} with the specified present non-null value. * 返回一个带参数的实例 * 如果参数为null的话,会抛出空指针异常 * @param the class of the value * @param value the value to be present, which must be non-null * @return an {@code Optional} with the value present * @throws NullPointerException if value is null */ public static Optional of(T value) { return new Optional<>(value); } /** * Returns an {@code Optional} describing the specified value, if non-null, * otherwise returns an empty {@code Optional}. * 如果参数不为空的话,返回一个带参的实例 * 否则的话,返回一个空的实例 * * @param the class of the value * @param value the possibly-null value to describe * @return an {@code Optional} with a present value if the specified value * is non-null, otherwise an empty {@code Optional} */ public static Optional ofNullable(T value) { return value == null ? empty() : of(value); } /** * If a value is present in this {@code Optional}, returns the value, * otherwise throws {@code NoSuchElementException}. * 获取当前实例的值 * 如果存在,返回当前值 * 如果不存在,抛出元素不存在异常NoSuchElementException * * @return the non-null value held by this {@code Optional} * @throws NoSuchElementException if there is no value present * * @see Optional#isPresent() */ public T get() { if (value == null) { throw new NoSuchElementException("No value present"); } return value; } /** * Return {@code true} if there is a value present, otherwise {@code false}. * 判断当前实例是否有值 * true 有值 * false 无值 * @return {@code true} if there is a value present, otherwise {@code false} */ public boolean isPresent() { return value != null; } /** * If a value is present, invoke the specified consumer with the value, * otherwise do nothing. * 如果当前实例有值, 执行实现了Consumer接口的回调函数实例 * * @param consumer block to be executed if a value is present * @throws NullPointerException if value is present and {@code consumer} is * null */ public void ifPresent(Consumer consumer) { if (value != null) consumer.accept(value); } /** * If a value is present, and the value matches the given predicate, * return an {@code Optional} describing the value, otherwise return an * empty {@code Optional}. * 判断当前实例是否符合匹配规则 * 如果符合匹配规则, 返回当前实例 * 如果不符合匹配规则,返回空实例 * @param predicate a predicate to apply to the value, if present * @return an {@code Optional} describing the value of this {@code Optional} * if a value is present and the value matches the given predicate, * otherwise an empty {@code Optional} * @throws NullPointerException if the predicate is null */ public Optional filter(Predicate predicate) { Objects.requireNonNull(predicate); if (!isPresent()) return this; else return predicate.test(value) ? this : empty(); } /** * If a value is present, apply the provided mapping function to it, * and if the result is non-null, return an {@code Optional} describing the * result. Otherwise return an empty {@code Optional}. * * @apiNote This method supports post-processing on optional values, without * the need to explicitly check for a return status. For example, the * following code traverses a stream of file names, selects one that has * not yet been processed, and then opens that file, returning an * {@code Optional}: * *

{@code
     *     Optional fis =
     *         names.stream().filter(name -> !isProcessedYet(name))
     *                       .findFirst()
     *                       .map(name -> new FileInputStream(name));
     * }
* * Here, {@code findFirst} returns an {@code Optional}, and then * {@code map} returns an {@code Optional} for the desired * file if one exists. * * @param The type of the result of the mapping function * @param mapper a mapping function to apply to the value, if present * @return an {@code Optional} describing the result of applying a mapping * function to the value of this {@code Optional}, if a value is present, * otherwise an empty {@code Optional} * @throws NullPointerException if the mapping function is null */ public Optional map(Function mapper) { Objects.requireNonNull(mapper); if (!isPresent()) return empty(); else { return Optional.ofNullable(mapper.apply(value)); } } /** * If a value is present, apply the provided {@code Optional}-bearing * mapping function to it, return that result, otherwise return an empty * {@code Optional}. This method is similar to {@link #map(Function)}, * but the provided mapper is one whose result is already an {@code Optional}, * and if invoked, {@code flatMap} does not wrap it with an additional * {@code Optional}. * * @param The type parameter to the {@code Optional} returned by * @param mapper a mapping function to apply to the value, if present * the mapping function * @return the result of applying an {@code Optional}-bearing mapping * function to the value of this {@code Optional}, if a value is present, * otherwise an empty {@code Optional} * @throws NullPointerException if the mapping function is null or returns * a null result */ public Optional flatMap(Function> mapper) { Objects.requireNonNull(mapper); if (!isPresent()) return empty(); else { return Objects.requireNonNull(mapper.apply(value)); } } /** * Return the value if present, otherwise return {@code other}. * 获取当前值 * 如果值存在的话, 返回当前值, * 如果值不存在的话,返回指定的参数值 * @param other the value to be returned if there is no value present, may * be null * @return the value, if present, otherwise {@code other} */ public T orElse(T other) { return value != null ? value : other; } /** * Return the value if present, otherwise invoke {@code other} and return * the result of that invocation. * 获取当前实例的值 * 如果值存在的话,返回当前值, 如果值不存在的话,返回回调函数里的返回值 * @param other a {@code Supplier} whose result is returned if no value * is present * @return the value if present otherwise the result of {@code other.get()} * @throws NullPointerException if value is not present and {@code other} is * null */ public T orElseGet(Supplier other) { return value != null ? value : other.get(); } /** * Return the contained value, if present, otherwise throw an exception * to be created by the provided supplier. * * 获取当前实例的值, * 如果当前实例无值的话,抛出回调异常 * * @apiNote A method reference to the exception constructor with an empty * argument list can be used as the supplier. For example, * {@code IllegalStateException::new} * * @param Type of the exception to be thrown * @param exceptionSupplier The supplier which will return the exception to * be thrown * @return the present value * @throws X if there is no value present * @throws NullPointerException if no value is present and * {@code exceptionSupplier} is null */ public T orElseThrow(Supplier exceptionSupplier) throws X { if (value != null) { return value; } else { throw exceptionSupplier.get(); } } /** * Indicates whether some other object is "equal to" this Optional. The * other object is considered equal if: *
    *
  • it is also an {@code Optional} and; *
  • both instances have no value present or; *
  • the present values are "equal to" each other via {@code equals()}. *
* 比较两个实例的地址 及两个实例的值 * * @param obj an object to be tested for equality * @return {code true} if the other object is "equal to" this object * otherwise {@code false} */ @Override public boolean equals(Object obj) { if (this == obj) { return true; } if (!(obj instanceof Optional)) { return false; } Optional other = (Optional) obj; return Objects.equals(value, other.value); } /** * Returns the hash code value of the present value, if any, or 0 (zero) if * no value is present. * * @return hash code value of the present value or 0 if no value is present */ @Override public int hashCode() { return Objects.hashCode(value); } /** * Returns a non-empty string representation of this Optional suitable for * debugging. The exact presentation format is unspecified and may vary * between implementations and versions. * * @implSpec If a value is present the result must include its string * representation in the result. Empty and present Optionals must be * unambiguously differentiable. * * @return the string representation of this instance */ @Override public String toString() { return value != null ? String.format("Optional[%s]", value) : "Optional.empty"; } }

 

你可能感兴趣的:(JDK源码解读)