Java 9のorTimeout()とcompleteOnTimeout()メソッドの違いを徹底解説

orTimeout()メソッドとcompleteOnTimeout()メソッドは、どちらもCompletableFutureクラスに定義されたメソッドで、Java 9で新たに導入されました。

orTimeout()は、非同期タスクが一定時間内に完了しなかった場合にTimeoutExceptionをスローし、CompletableFutureを例外的に完了させます。一方、completeOnTimeout()は、タイムアウトが発生した際に、あらかじめ指定しておいたデフォルト値でCompletableFutureを正常に完了させます。どちらの場合も、タイムアウト時間より前にタスクが完了していれば、その実際の計算結果がそのまま返されます。

違いのポイント

orTimeout()メソッドの構文

public CompletableFuture<T> orTimeout(long timeout, TimeUnit unit)

• timeout: 最大待機時間
• unit: 待機時間の単位（TimeUnit.SECONDS など）

orTimeout()の使用例

以下の例では、5秒かかる非同期タスクに対して4秒のタイムアウトを設定しています。タスクがタイムアウト时间内に完了しないため、TimeoutExceptionが発生します。

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.TimeUnit;

public class OrTimeoutMethodTest {
    public static void main(String args[]) throws InterruptedException {
        int a = 10;
        int b = 15;
        CompletableFuture.supplyAsync(() -> {
            try {
                TimeUnit.SECONDS.sleep(5); // 処理に5秒かかる
            } catch (InterruptedException e) {
                e.printStackTrace();
            }
            return a + b;
        })
        .orTimeout(4, TimeUnit.SECONDS) // 4秒でタイムアウト
        .whenComplete((result, exception) -> {
            System.out.println("結果: " + result);
            if (exception != null) {
                System.out.println("例外: " + exception);
            }
        });
        TimeUnit.SECONDS.sleep(10); // メインスレッドを維持
    }
}

実行結果

結果: null
例外: java.util.concurrent.TimeoutException

このように、タイムアウト時間内にタスクが完了しなかった場合、結果はnullとなり、TimeoutExceptionがスローされます。

completeOnTimeout()メソッドの構文

public CompletableFuture<T> completeOnTimeout(T value, long timeout, TimeUnit unit)

• value: タイムアウト時に使用されるデフォルト値
• timeout: 最大待機時間
• unit: 待機時間の単位

completeOnTimeout()の使用例

以下の例では、同じ5秒かかるタスクに対して4秒のタイムアウトとデフォルト値「0」を設定しています。タスクが間に合わない場合、代わりに0が出力されます。

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.TimeUnit;

public class CompleteOnTimeOutMethodTest {
    public static void main(String args[]) throws InterruptedException {
        int a = 10;
        int b = 15;
        CompletableFuture.supplyAsync(() -> {
            try {
                TimeUnit.SECONDS.sleep(5); // 処理に5秒かかる
            } catch (InterruptedException e) {
                e.printStackTrace();
            }
            return a + b;
        })
        .completeOnTimeout(0, 4, TimeUnit.SECONDS) // タイムアウト時は0で完了
        .thenAccept(result -> System.out.println("結果: " + result));
        TimeUnit.SECONDS.sleep(10); // メインスレッドを維持
    }
}

実行結果

結果: 0

タイムアウトが発生しても例外にはならず、指定したデフォルト値（この場合は0）でCompletableFutureが完了する点が、orTimeout()との大きな違いです。

使い分けの指針

• orTimeout(): タイムアウトを許容できない処理や、遅延を明示的な失敗としてハンドリングしたい場合に適しています。
• completeOnTimeout(): タイムアウト時にもフォールバック値（キャッシュ値や初期値など）を返してアプリケーションの動作を継続させたい場合に便利です。