Класс 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, возвращая 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)

Parameters:

supplier - функция-поставщик, которая производит значение, которое должно быть возвращено

Returns:

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

Throws:

NullPointerException - если значение отсутствует и функция-поставщик является null

public T orElseThrow()

Returns:

значение, не являющееся null, описываемое этим Optional

Throws:

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

Since:

10

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

public boolean equals(Object obj)

Overrides:

equals в классе Object

Parameters:

obj - объект, который должен быть проверен на равенство

Returns:

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

See Also:

• Object.hashCode()
• HashMap

public int hashCode()

Overrides:

hashCode в классе Object

Returns:

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

See Also:

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

public String toString()

Overrides:

toString в классе Object

Implementation Requirements:

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

Returns:

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