Класс 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)

Параметры:

supplier — предоставляющая функция, создающая возвращаемое значение

Возвращает:

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

Выбрасывает:

NullPointerException — если значение отсутствует, а предоставляющая функция равна null

public T orElseThrow()

Возвращает:

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

Выбрасывает:

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

С момента версии:

10

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

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

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

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

X — тип выбрасываемого исключения

Параметры:

exceptionSupplier — предоставляющая функция, создающая выбрасываемое исключение

Возвращает:

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

Выбрасывает:

X — если значение отсутствует

NullPointerException — если значение отсутствует, а функция предоставления исключения равна null или создает результат null

public boolean equals(Object obj)

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

equals в классе Object

Параметры:

obj — объект, равенство которого проверяется

Возвращает:

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

См. также:

• Object.hashCode()
• HashMap

public int hashCode()

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

hashCode в классе Object

Возвращает:

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

См. также:

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

public String toString()

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

toString в классе Object

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

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

Возвращает:

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