モジュール java.base
パッケージ java.util

クラスOptional<T>

  • 型パラメータ:
    T - 値の型
    public final class Optional<T>
extends Object
    null以外の値が含まれる場合と含まれない場合があるコンテナ・オブジェクト。 値が存在する場合、isPresent()はtrueを返します。 値が存在しない場合、オブジェクトは空とみなされ、isPresent()はfalseを返します。

    orElse() (値が存在しない場合はデフォルト値を返す)やifPresent() (値が存在する場合はアクションを実行する)など、含まれる値の有無に依存するその他のメソッドが提供されます。

    これは値ベースのクラスで、Optionalのインスタンスに対して、ID依存操作(参照等価性(==)、IDハッシュ・コード、同期など)を使用すると、予期できない結果になる可能性があり、避けてください。

    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)
      指定された非null値を記述するOptionalを返します。
      static <T> Optional<T> ofNullable​(T value)
      null以外の場合は、指定された値を記述するOptionalを戻し、それ以外の場合は空の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の空でない文字列表現を返します。

    • メソッドの詳細

      • empty

        public static <T> Optional<T> empty()
        空のOptionalインスタンスを返します。 このOptionalには値がありません。
        APIのノート:
        オブジェクトが空であるかどうかのテストは、Optional.empty()によって返されるインスタンスに対して==と比較することで避けてください。 シングルトンである保証はありません。 かわりにisPresent()を使用してください。
        型パラメータ:
        T - 存在しない値の型
        戻り値:
        空のOptional。

      • of

        public static <T> Optional<T> of​(T value)
        指定された非null値を記述するOptionalを返します。
        型パラメータ:
        T - 値の型
        パラメータ:
        value - 記述する値。null以外である必要があります。
        戻り値:
        存在する値でのOptional
        例外:
        NullPointerException - valueがnullの場合

      • ofNullable

        public static <T> Optional<T> ofNullable​(T value)
        null以外の場合は、指定された値を記述するOptionalを戻し、それ以外の場合は空のOptionalを戻します。
        型パラメータ:
        T - 値の型
        パラメータ:
        value - 記述可能なnull値
        戻り値:
        指定された値がnull以外の場合は、現在の値を持つOptional、それ以外の場合は空のOptional

      • get

        public T get()
        値が存在する場合は値を返し、それ以外の場合はNoSuchElementExceptionをスローします。
        APIのノート:
        この方法に代わる推奨方法は、orElseThrow()です。
        戻り値:
        このOptionalで説明されているnull以外の値
        例外:
        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を選択して、そのURIからパスを作成し、Optional<Path>を返します。 
        
     Optional<Path> p =
         uris.stream().filter(uri -> !isProcessedYet(uri))
                       .findFirst()
                       .map(Paths::get);
        ここで、findFirstはOptional<URI>を返し、mapは目的のURIのOptional<Path>を返します(存在する場合)。
        型パラメータ:
        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を現在値要素のStreamに変換するために使用できます。 
        
     Stream<Optional<T>> os = ..
     Stream<T> s = os.flatMap(Optional::stream)
        戻り値:
        オプション値(Stream)
        導入されたバージョン:
        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をスローします。
        戻り値:
        このOptionalで説明されているnull以外の値
        例外:
        NoSuchElementException - 値が存在しない場合
        導入されたバージョン:
        10

      • orElseThrow

        public <X extends Throwable> T orElseThrow​(Supplier<? extends X> exceptionSupplier)
                                    throws X
        値が存在する場合はその値を返し、それ以外の場合は例外指定関数によって生成された例外をスローします。
        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

      • toString

        public String toString()
        デバッグに適した、このOptionalの空でない文字列表現を返します。 正確な表示フォーマットは未指定であり、実装とバージョンの間で異なることがあります。
        オーバーライド:
        toString、クラスObject
        実装要件:
        値が存在する場合は、結果にその文字列表現が含まれる必要があります。 空のOptionalと現在のOptionalは、明確に区別できる必要があります。
        戻り値:
        このインスタンスの文字列表現