Класс Optional<T>

java.lang.Object

java.util.Optional<T>

Параметры типа:: T - тип значения

public final class Optional<T> extends Object

Объект-контейнер, который может или не может содержать значение, отличное от null. Если значение присутствует, isPresent() возвращает true. Если значение отсутствует, объект считается пустым и isPresent() возвращает false.

Предоставляются дополнительные методы, зависящие от наличия или отсутствия содержащегося значения, такие как orElse() (возвращает значение по умолчанию, если значение отсутствует) и ifPresent() (выполняет действие, если значение присутствует).

Это класс базирующийся на значении; программисты должны рассматривать экземпляры, которые равны, как взаимозаменяемые и не должны использовать экземпляры для синхронизации, в противном случае могут возникнуть непредсказуемые поведения. Например, в будущей версии синхронизация может завершиться сбоем.

Примечание API:: Optional предназначен в первую очередь для использования в качестве типа возвращаемого значения метода, где явно требуется представить «отсутствие результата», и где использование null может привести к ошибкам. Переменная, тип которой Optional, никогда не должна быть null; она всегда должна указывать на экземпляр Optional.
С:: 1.8

Краткое описание методов

Модификатор и тип	Метод	Описание
`static <T> Optional<T>`	`empty()`	Возвращает пустой экземпляр `Optional`.
`boolean`	`equals(Object obj)`	Указывает, является ли другой объект «равным» этому `Optional`.
`Optional<T>`	`filter(Predicate<? super T> predicate)`	Если значение присутствует и совпадает с заданным предикатом, возвращает `Optional`, описывающее значение, в противном случае возвращает пустой `Optional`.
`<U> Optional<U>`	`flatMap(Function<? super T,? extends Optional<? extends U>> mapper)`	Если значение присутствует, возвращает результат применения заданной функции отображения, несущей `Optional`, к значению, в противном случае возвращает пустой `Optional`.
`T`	`get()`	Если значение присутствует, возвращает значение, в противном случае выбрасывает `NoSuchElementException`.
`int`	`hashCode()`	Возвращает код хэширования значения, если оно присутствует, в противном случае `0` (ноль), если значение отсутствует.
`void`	`ifPresent(Consumer<? super T> action)`	Если значение присутствует, выполняет заданное действие со значением, в противном случае ничего не делает.
`void`	`ifPresentOrElse(Consumer<? super T> action, Runnable emptyAction)`	Если значение присутствует, выполняет заданное действие со значением, в противном случае выполняет заданное действие, связанное с отсутствием значения.
`boolean`	`isEmpty()`	Если значение отсутствует, возвращает `true`, в противном случае `false`.
`boolean`	`isPresent()`	Если значение присутствует, возвращает `true`, в противном случае `false`.
`<U> Optional<U>`	`map(Function<? super T,? extends U> mapper)`	Если значение присутствует, возвращает `Optional`, описывающее (как если бы с помощью `ofNullable(T)`) результат применения заданной функции отображения к значению, в противном случае возвращает пустой `Optional`.
`static <T> Optional<T>`	`of(T value)`	Возвращает `Optional`, описывающий заданное значение, отличное от `null`.
`static <T> Optional<T>`	`ofNullable(T value)`	Возвращает `Optional`, описывающее заданное значение, если оно не `null`, в противном случае возвращает пустой `Optional`.
`Optional<T>`	`or(Supplier<? extends Optional<? extends T>> supplier)`	Если значение присутствует, возвращает `Optional`, описывающее значение, в противном случае возвращает `Optional`, сгенерированное предоставленной функцией.
`T`	`orElse(T other)`	Если значение присутствует, возвращает значение, в противном случае возвращает `other`.
`T`	`orElseGet(Supplier<? extends T> supplier)`	Если значение присутствует, возвращает значение, в противном случае возвращает результат, произведённый предоставленной функцией.
`T`	`orElseThrow()`	Если значение присутствует, возвращает значение, в противном случае выбрасывает `NoSuchElementException`.
`<X extends Throwable> T`	`orElseThrow(Supplier<? extends X> exceptionSupplier)`	Если значение присутствует, возвращает значение, в противном случае выбрасывает исключение, сгенерированное функцией предоставления исключения.
`Stream<T>`	`stream()`	Если значение присутствует, возвращает последовательную `Stream`, содержащую только это значение, в противном случае возвращает пустой `Stream`.
`String`	`toString()`	Возвращает строковое представление этого `Optional`, подходящее для отладки.

Методы, объявленные в классе java.lang.Object

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

Подробное описание методов

empty

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

Возвращает пустой Optional экземпляр. Значение для этого Optional отсутствует.

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

of

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

Возвращает Optional, описывающий заданное значение, отличное от null.

Параметры типа:: T - тип значения
Параметры:: value - описываемое значение, которое должно быть отличным от null
Возвращает:: Optional со значением, присутствующим в нём
Исключение:: NullPointerException - если значение равно null

ofNullable

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

Возвращает Optional , описывающий заданное значение, если оно не null, иначе возвращает пустой Optional.

Параметры типа:: T - тип значения
Параметры:: value - возможно null значение для описания
Возвращает:: Optional со значением, присутствующим, если заданное значение не null, в противном случае пустой Optional

get

public T get()

Если значение присутствует, возвращает значение, в противном случае выбрасывает NoSuchElementException.

Примечание API:: Предпочтительная альтернатива этому методу - orElseThrow().
Возвращает:: значение, отличное от null, описываемое этим Optional
Исключение:: NoSuchElementException - если значение отсутствует

isPresent

public boolean isPresent()

Если значение присутствует, возвращает true, в противном случае false.

Возвращает:: true если значение присутствует, в противном случае false

isEmpty

public boolean isEmpty()

Если значение отсутствует, возвращает true, в противном случае false.

Возвращает:: true если значение отсутствует, в противном случае false
С:: 11

ifPresent

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

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

Параметры:: action - действие, которое должно быть выполнено, если значение присутствует
Исключение:: NullPointerException - если значение присутствует и заданное действие null

ifPresentOrElse

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

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

Параметры:: action - действие, которое должно быть выполнено, если значение присутствует; emptyAction - действие, основанное на отсутствии значения, которое должно быть выполнено, если значение отсутствует
Исключение:: NullPointerException - если значение присутствует и заданное действие null, или значение отсутствует и заданное действие, основанное на отсутствии значения, null.
С:: 9

filter

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

Если значение присутствует и значение соответствует заданному предикату, возвращает Optional, описывающее значение, в противном случае возвращает пустой Optional.

Параметры:: predicate - предикат, применяемый к значению, если оно присутствует
Возвращает:: Optional , описывающее значение этого Optional, если значение присутствует и значение соответствует заданному предикату, в противном случае пустой Optional
Исключение:: NullPointerException - если предикат null

map

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

Если значение присутствует, возвращает Optional , описывающее (как если бы с помощью ofNullable(T)) результат применения заданной функции отображения к значению, в противном случае возвращает пустой Optional.

Если функция отображения возвращает null результат, то этот метод возвращает пустой Optional.

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

Этот метод поддерживает пост-обработку значений Optional без необходимости явного проверки состояния возврата. Например, следующий код проходит по потоку URIs, выбирает один, который еще не обработан, и создает путь из этого 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

flatMap

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

Если значение присутствует, возвращает результат применения заданной функции отображения, содержащей Optional, в противном случае возвращает пустой Optional.

Этот метод аналогичен map(Function), но функция отображения — это функция, результат которой уже является Optional, и если она вызывается, flatMap не оборачивает её в дополнительный Optional.

Параметры типа:: U - тип значения Optional , возвращаемого функцией отображения
Параметры:: mapper - функция отображения, применяемая к значению, если оно присутствует
Возвращает:: результат применения функции отображения, содержащей Optional, к значению этого Optional, если значение присутствует, в противном случае пустой Optional
Исключение:: NullPointerException - если функция отображения null или возвращает null результат

or

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

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

Параметры:: supplier - функция поставки, которая создаёт Optional для возврата
Возвращает:: Возвращает Optional , описывающее значение этого Optional, в противном случае Optional , созданный функцией поставки.
Исключение:: NullPointerException - если функция поставки null или создаёт null результат
С:: 9

stream

public Stream<T> stream()

Если значение присутствует, возвращает последовательный поток Stream, содержащий только это значение, в противном случае возвращает пустой Stream.

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

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


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

Возвращает:

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

С:

orElse

public T orElse(T other)

Если значение присутствует, возвращает значение, в противном случае возвращает other.

Параметры:: other - значение, которое должно быть возвращено, если значение отсутствует. Может быть null.
Возвращает:: значение, если оно присутствует, в противном случае other

orElseGet

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

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

Параметры:: supplier - функция поставки, которая создаёт возвращаемое значение
Возвращает:: значение, если оно присутствует, в противном случае результат, созданный функцией поставки
Исключение:: NullPointerException - если значение отсутствует и функция поставки null

orElseThrow

public T orElseThrow()

Если значение присутствует, возвращает значение, в противном случае выбрасывает NoSuchElementException.

Возвращает:: значение, отличное от null, описываемое этим Optional
Исключение:: NoSuchElementException - если значение отсутствует
С:: 10

orElseThrow

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

Если значение присутствует, возвращает значение, иначе выбрасывает исключение, сгенерированное функцией, предоставляющей исключение.

API Note:: В качестве поставщика можно использовать ссылку на метод конструктора исключения с пустым списком аргументов. Например, IllegalStateException::new
Type Parameters:: X - Тип исключения, которое будет выброшено
Parameters:: exceptionSupplier - функция, которая предоставляет исключение, которое будет выброшено
Returns:: значение, если оно присутствует
Throws:: X - если значение не присутствует; NullPointerException - если значение не присутствует и функция, предоставляющая исключение, null

equals

public boolean equals(Object obj)

Указывает, является ли некоторый другой объект "равным" этому объекту. Другой объект считается равным, если:

он также является Optional;
оба экземпляра не содержат значения или;
присутствующие значения "равны" друг другу по equals().

Overrides:

equals в классе Object

Parameters:

obj - объект, который необходимо проверить на равенство

Returns:

true если другой объект "равен" этому объекту, иначе false

See Also:

hashCode

public int hashCode()

Возвращает хэш-код значения, если оно присутствует, иначе 0 (ноль), если значение не присутствует.

Overrides:

hashCode в классе Object

Returns:

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

See Also:

toString

public String toString()

Возвращает непустую строку, представляющую этот объект, подходящую для отладки. Точный формат представления не определен и может различаться между реализациями и версиями.

Overrides:: toString в классе Object
Implementation Requirements:: Если значение присутствует, результат должен включать его строковое представление в результате. Пустые и присутствующие Optional должны быть однозначно различимы.
Returns:: строковое представление этого экземпляра

© 1993, 2021, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Optional.html