Класс Optional<T>

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

Примечание к API:

Хотя это может показаться заманчивым, не следует проверять, является ли объект пустым, сравнивая его с == или != с экземплярами, возвращёнными методом Optional.empty(). Нет гарантии, что это синглтон. Вместо этого используйте isEmpty() или isPresent().

Параметры типа:

T — тип несуществующего значения

Возвращает:

пустой Optional

public static <T> Optional<T> of(T value)

Параметры типа:

T — тип значения

Параметры:

value — описываемое значение, которое не должно быть null

Возвращает:

Optional с присутствующим значением

Выбрасывает:

NullPointerException — если значение равно null

public static <T> Optional<T> ofNullable(T value)

Параметры типа:

T — тип значения

Параметры:

value — возможно, равное null значение для описания

Возвращает:

Optional с присутствующим значением, если указанное значение отлично от null; в противном случае — пустой Optional

public T get()

Примечание к API:

Предпочтительная альтернатива этому методу — orElseThrow().

Возвращает:

значение, отличное от null, описанное этим Optional

Выбрасывает:

NoSuchElementException — если значение отсутствует

public boolean isPresent()

Возвращает:

true, если значение присутствует; в противном случае — false

public boolean isEmpty()

Возвращает:

true, если значение отсутствует; в противном случае — false

Начиная с версии:

11

public void ifPresent(Consumer<? super T> action)

Параметры:

action — действие, выполняемое, если значение присутствует

Выбрасывает:

NullPointerException — если значение присутствует, а заданное действие равно null

public void ifPresentOrElse(Consumer<? super T> action, Runnable emptyAction)

Параметры:

action — действие, выполняемое, если значение присутствует

emptyAction — действие для пустого значения, выполняемое, если значение отсутствует

Выбрасывает:

NullPointerException — если значение присутствует, а заданное действие равно null, либо если значение отсутствует, а заданное действие для пустого значения равно null.

Начиная с версии:

9

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

Параметры:

predicate — предикат, применяемый к значению, если оно присутствует

Возвращает:

Optional, описывающий значение этого Optional, если значение присутствует и соответствует заданному предикату; в противном случае — пустой Optional

Выбрасывает:

NullPointerException — если предикат равен null

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

Примечание к API:

Этот метод позволяет выполнять постобработку значений 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

Выбрасывает:

NullPointerException — если функция отображения равна null

public <U> Optional<U> flatMap(Function<? super T, ? extends Optional<? extends U>> mapper)

Параметры типа:

U — тип значения Optional, возвращаемого функцией отображения

Параметры:

mapper — функция отображения, применяемая к значению, если оно присутствует

Возвращает:

результат применения функции отображения, возвращающей Optional, к значению этого Optional, если значение присутствует; в противном случае — пустой Optional

Выбрасывает:

NullPointerException — если функция отображения равна null или возвращает результат null

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

Параметры:

supplier — предоставляющая функция, создающая возвращаемый Optional

Возвращает:

возвращает Optional, описывающий значение этого Optional, если значение присутствует; в противном случае — Optional, созданный предоставляющей функцией.

Выбрасывает:

NullPointerException — если предоставляющая функция равна null или создаёт результат null

Начиная с версии:

9

public Stream<T> stream()

Примечание к API:

Этот метод можно использовать для преобразования Stream необязательных элементов в Stream элементов с присутствующими значениями:

    Stream<Optional<T>> os = ..
    Stream<T> s = os.flatMap(Optional::stream)

Возвращает:

необязательное значение в виде Stream

Начиная с версии:

9

public T orElse(T other)

Параметры:

other — значение, возвращаемое при отсутствии значения. Может быть null.

Возвращает:

значение, если оно присутствует; в противном случае — other

public T orElseGet(Supplier<? extends T> supplier)

Параметры:

supplier — предоставляющая функция, создающая возвращаемое значение

Возвращает:

значение, если оно присутствует; в противном случае — результат, созданный предоставляющей функцией

Выбрасывает:

NullPointerException — если значение отсутствует, а предоставляющая функция равна null

public T orElseThrow()

Возвращает:

значение, отличное от null, описанное этим Optional

Выбрасывает:

NoSuchElementException — если значение отсутствует

Начиная с версии:

10

public <X extends Throwable> T orElseThrow(Supplier<? extends X> exceptionSupplier) throws X

Примечание к API:

В качестве предоставляющей функции можно использовать ссылку на метод-конструктор исключения без аргументов. Например: IllegalStateException::new

Параметры типа:

X — тип выбрасываемого исключения

Параметры:

exceptionSupplier — предоставляющая функция, создающая выбрасываемое исключение

Возвращает:

значение, если оно присутствует

Выбрасывает:

X — если значение отсутствует

NullPointerException — если значение отсутствует, а функция, предоставляющая исключение, равна null или создаёт результат null

public boolean equals(Object obj)

Переопределяет:

equals в классе Object

Параметры:

obj — объект, равенство которого проверяется

Возвращает:

true, если другой объект «равен» этому объекту; в противном случае — false

См. также:

• Object.hashCode()
• HashMap

public int hashCode()

Переопределяет:

hashCode в классе Object

Возвращает:

хеш-код присутствующего значения или 0, если значение отсутствует

См. также:

• Object.equals(java.lang.Object)
• System.identityHashCode(Object)

public String toString()

Переопределяет:

toString в классе Object

Требования к реализации:

Если значение присутствует, результат должен включать его строковое представление. Пустые и непустые Optionals должны однозначно различаться.

Возвращает:

строковое представление этого экземпляра