Overview
Scalaドライバーを使用してサーバー操作を実行する場合、サーバーが操作を完了できる時間を制限することもできます。そのためには、クライアント側操作タイムアウト（CST） を指定します。タイムアウトは、サーバーの選択、接続のチェックアウト、サーバー側の実行など、操作を完了するために必要なすべてのステップに適用されます。タイムアウトが経過すると、 Scalaドライバーはタイムアウトの例外を発生させます。
注意
試験用機能
COT 機能は実験的なものであり、今後のドライバー リリースで変更される可能性があります。
timeoutMS オプション
MongoDBデプロイに接続するときにタイムアウトを指定するには、timeoutMS 接続オプションをミリ秒単位でタイムアウトの長さに設定します。timeoutMS オプションは、次の方法で設定できます。
MongoClientSettings.Builderクラスからtimeout()メソッドを呼び出す接続stringでの
timeoutMSパラメータの設定
次のコード例では、クライアントレベルのタイムアウトを 200 ミリ秒に設定します。対応するコードを表示するには、MongoClientSettings タブまたは Connection
Stringタブを選択します。
val settings = MongoClientSettings.builder .applyConnectionString(ConnectionString("<connection string>")) .timeout(200L, MILLISECONDS) .build val mongoClient = MongoClient(settings)
val uri = "<connection string>/?timeoutMS=200" val mongoClient = MongoClient(uri)
許容タイムアウト値
次の表では、timeoutMS に許容される値に対応するタイムアウト動作を説明しています。
値 | 動作 |
|---|---|
正の整数 | 操作完了に使用するタイムアウトを設定します。 |
| 操作がタイムアウトしないことを指定します。 |
| Defers the timeout behavior to the following settings: These settings are deprecated and are ignored if you set timeoutMS. |
timeoutMS オプションを指定すると、ドライバーは指定されたタイムアウトを各サーバー操作に自動的に適用します。次のコード例では、クライアントレベルで 200 ミリ秒のタイムアウトを指定し、MongoCollection.insertOne() メソッドを呼び出します。
val settings = MongoClientSettings.builder .applyConnectionString(ConnectionString("<connection string>")) .timeout(200L, MILLISECONDS) .build val mongoClient = MongoClient(settings) val database = mongoClient.getDatabase("db") val collection = database.getCollection("people") collection.insertOne(Document("name" -> "Francine Loews"))
タイムアウト継承
timeoutMS オプションを指定すると、ドライバーは他のScalaドライバー オプションと同じ継承動作に従ってタイムアウトを適用します。以下の表は、各レベルでタイムアウト値がどのように継承されるかを示しています。
レベル | 継承の説明 |
|---|---|
操作 | が最も優先され、他のレベルで設定したタイムアウト オプションを上書きします。 |
トランザクション | セッション、コレクション、データベース、またはクライアントレベルで設定したタイムアウト値よりも優先されます。 |
セッション | レベルで別のタイムアウト値を設定しない限り、そのセッション内のすべてのトランザクションと操作に適用されます。 |
Database | レベルで別のタイムアウト値を設定しない限り、そのデータベース内のすべてのセッションと操作に適用されます。 |
コレクション | レベルで別のタイムアウト値を設定しない限り、そのコレクションに対するすべてのセッションと操作に適用されます。 |
クライアント |
|
オーバーライドと特定のオプションの詳細については、次のオーバーライドセクションを参照してください。
の上書き
Scalaドライバーは、データベース操作の動作とパフォーマンスを制御するためのさまざまなレベルの構成をサポートしています。
より具体的なレベルで timeoutMS オプションを指定すると、クライアントレベルの構成を上書きできます。前のセクションの表では、タイムアウト設定を指定できるレベルについて説明しています。これにより、個々の操作のニーズに基づいてタイムアウトをカスタマイズできます。
次の例では、コレクション レベルのタイムアウト構成がクライアント レベルのタイムアウト構成を上書きする方法を示しています。
val settings = MongoClientSettings.builder .applyConnectionString(ConnectionString("<connection string>")) .timeout(200L, MILLISECONDS) .build val mongoClient = MongoClient(settings) val database = mongoClient.getDatabase("db") val collection = database .getCollection("people") .withTimeout(300L, MILLISECONDS) // ... perform operations on MongoCollection
トランザクション
新しい ScalaClientSession インスタンスを作成してトランザクションを実装する場合は、 ClientSessionOptionsインスタンスを構築するときに defaultTimeout() メソッドを使用します。このオプションを使用して、次のメソッドのタイムアウトを指定できます。
次のコードは、ClientSession をインスタンス化するときに defaultTimeout を設定する方法を示しています。
val opts = ClientSessionOptions.builder .defaultTimeout(200L, MILLISECONDS) .build val session = mongoClient.startSession(opts) // ... perform operations on ClientSession
defaultTimeout を指定しない場合、ドライバーは親の MongoClient に設定されたタイムアウト値を使用します。
また、 TransactionOptionsインスタンスを構築するときに timeout() メソッドを呼び出して、トランザクションレベルのタイムアウトを設定することもできます。このオプションを設定すると、トランザクションの範囲内で実行されるすべての操作にタイムアウトが適用されます。
val transactionOptions = TransactionOptions.builder .timeout(200L, MILLISECONDS) .build
トランザクションの詳細については、トランザクションの実行ガイドをご覧ください。
クライアントの暗号化
クライアント側フィールドレベル暗号化（CSFLE）を使用する場合、ドライバーは timeoutMS オプションを使用して暗号化と復号化操作に許可される時間を制限します。ClientEncryptionSettingsインスタンスを構築するときに timeout() メソッドを呼び出すことで、ClientEncryptionインスタンスのタイムアウト オプションを設定できます。
ClientEncryptionインスタンスを構築するときにタイムアウトを指定すると、タイムアウトはそのインスタンスで実行されるすべての操作の有効期間を制御します。ClientEncryption をインスタンス化するときにタイムアウトを指定しない場合、インスタンスはClientEncryption コンストラクターで使用される MongoClient からタイムアウト設定を継承します。
クライアントと ClientEncryption で直接 timeoutMS を設定すると、ClientEncryption に提供された値が優先されます。
Observables
Observable インスタンスでは、COT 機能を使用する場合に構成可能なタイムアウト設定が提供されます。Observable の有効期間を構成することで、Observable の処理を調整できます。タイムアウトモードを設定するには、Observable を継承する結果を返す操作を実行するときに timeoutMode() メソッドを使用します。
注意
継承されたタイムアウト
カーソル タイムアウトモードを設定するには、MongoClientSettings、MongoDatabase、または MongoCollection のいずれかでタイムアウトを設定する必要があります。
Observable の詳細については、「Observable からのデータへのアクセス」ガイドを参照してください。
ライフタイムモード
ライフタイムモードでは、 タイムアウト設定を使用して Observable の有効期間全体を制限します。このモードでは 、アプリケーションはObservable を初期化し、Observable メソッドへのすべての呼び出しを完了し、指定された時間制限内にすべてのドキュメントを返す必要があります。停止しない場合、Observable の有効期限が切れ、ドライバーはタイムアウトのエラーを発生させます。
次の例では、Observable タイムアウトを設定して、カーソルが初期化され、継承されたタイムアウト内にすべてのドキュメントが検索されるようにする方法を示しています。
val observableWithLifetimeTimeout = collection .find(gte("age", 40)) .timeoutMode(TimeoutMode.CURSOR_LIFETIME)
GridFS
withTimeout() メソッドを使用して GridFSBucket をインスタンス化するときにGridFS操作のタイムアウト オプションを設定できます。このタイムアウトは、データのアップロードやダウンロードなど、バケットで実行されるすべての操作に適用されます。タイムアウトを設定しない場合、GridFSBucketインスタンスは、作成された MongoDatabase からタイムアウト設定を継承します。
次のコードは、GridFSBucket をインスタンス化するときにタイムアウトを設定する方法を示しています。
val gridFSBucket = GridFSBucket(database).withTimeout(200L, MILLISECONDS)
重要
観察可能なタイムアウトのサポート
操作タイムアウトを持つ GridFSBucket で uploadFromObservable() メソッドを呼び出すと、Observableクラスには固有の読み取りタイムアウト サポートがないため、タイムアウトが発生する可能性があります。これにより、指定されたタイムアウト制限を超えて操作が延長され、タイムアウトの例外が発生する可能性があります。
API ドキュメント
Scalaドライバーでタイムアウトを使用する方法の詳細については、次のAPIドキュメントを参照してください。