Класс Optional

java.lang.Object

java.util.Optional

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

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 элементов optional в поток Stream элементов present value:


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

Возвращает:

значение optional в виде 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. Другой объект считается равным, если:

он также является 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()

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

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

© 1993, 2023, 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/21/docs/api/java.base/java/util/Optional.html