Класс Optional<T>

Type Parameters:
T - тип значения
public final class Optional<T>
extends Object

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

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

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

Примечание 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(). Нет гарантии, что это единственный экземпляр. Вместо этого используйте 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
C момента:
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.
C момента:
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 результат
C момента:
9

stream

public Stream<T> stream()

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

Примечание API:
Этот метод может быть использован для преобразования Stream опциональных элементов в Stream элементов присутствующих значений: 
Stream<Optional<T>> os = ..
     Stream<T> s = os.flatMap(Optional::stream)
Возвращает:
опциональное значение как Stream
C момента:
9

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 - если значение отсутствует
C момента:
10

orElseThrow

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

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

Примечание API:
В качестве функции поставок можно использовать ссылку на конструктор исключения с пустым списком аргументов. Например, IllegalStateException::new
Параметры типа:
X - Тип исключения, которое будет выброшено
Параметры:
exceptionSupplier - функция поставок, производящая исключение, которое будет выброшено
Возвращает:
значение, если присутствует
Исключения:
X - если значение отсутствует
NullPointerException - если значение отсутствует и функция поставок исключений null
X extends Throwable

equals

public boolean equals(Object obj)

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

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

Переопределяет:
equals в классе Object
Параметры:
obj - объект, подлежащий проверке на равенство
Возвращает:
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 должны быть однозначно различимы.
Возвращает:
строковое представление этого экземпляра

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

Spec-Zone .ru
спецификации, руководства, описания, API