Класс Optional<T>

public final class Optional<T>
extends Object

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

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

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

Методы

empty

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

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

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

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

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

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

Возвращает:

пустой Optional

of

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

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

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

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()

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

Возвращает:

ненулевое значение, хранящееся в этом Optional

Исключение:

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

См. также:

isPresent()

isPresent

public boolean isPresent()

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

Возвращает:

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

ifPresent

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

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

Параметры:

consumer - блок, который будет выполнен, если значение присутствует

Исключение:

NullPointerException - если значение присутствует и consumer равно null

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)

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

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

Этот метод поддерживает постобработку значений optional без явного проверки статуса возврата. Например, следующий код проходит по потоку имён файлов, выбирает тот, который ещё не обработан, а затем открывает этот файл, возвращая Optional<FileInputStream>:

Optional<FileInputStream> fis =
         names.stream().filter(name -> !isProcessedYet(name))
                       .findFirst()
                       .map(name -> new FileInputStream(name));

Здесь findFirst возвращает Optional<String>, а затем map возвращает Optional<FileInputStream> для нужного файла, если он существует.

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

U - тип результата функции отображения

Параметры:

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

Возвращает:

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

Исключение:

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

flatMap

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

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

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

U - параметр типа Optional возвращаемый

Параметры:

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

Возвращает:

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

Исключение:

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

orElse

public T orElse(T other)

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

Параметры:

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

Возвращает:

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

orElseGet

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

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

Параметры:

other - Supplier , результат которого возвращается, если значение не присутствует

Возвращает:

значение, если оно присутствует, в противном случае результат other.get()

Исключение:

NullPointerException - если значение не присутствует и other равно null

orElseThrow

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

Возвращает содержащееся значение, если оно присутствует, в противном случае выбрасывает исключение, которое создаётся предоставленным поставщиком.

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

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

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

X - Тип исключения, которое должно быть выброшено

Параметры:

exceptionSupplier - Поставщик, который вернёт исключение, которое нужно выбросить

Возвращает:

настоящее значение

Исключение:

X - если значение не присутствует

NullPointerException - если значение не присутствует и exceptionSupplier равно null

X extends Throwable

equals

public boolean equals(Object obj)

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

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

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

equals в классе Object

Параметры:

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

Возвращает:

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

См. также:

Object.hashCode(), HashMap

hashCode

public int hashCode()

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

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

hashCode в классе Object

Возвращает:

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

См. также:

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

toString

public String toString()

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

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

toString в классе Object

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

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

Возвращает:

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