概念

このトピックでは、Oracle Cloud Infrastructure SDK for Javaを使用するための主要な概念の一部を説明します。

このトピックでは、Oracle Cloud Infrastructure SDK for Javaを使用するための主要な概念の一部を説明します。

同期コール

同期コールを行うには、同期クライアントのインスタンスを作成します。同期クライアントの一般的なパターンでは、Exampleという名前のサービスに対して、ExampleServiceという名前のインタフェースが存在し、同期クライアント実装はExampleServiceClientと呼ばれます。次に、オブジェクト・ストレージ・クライアントを作成する例を示します:

AuthenticationDetailsProvider provider = ...;
ObjectStorage clientWithDefaultClientConfig = new ObjectStorageClient(provider);
clientWithDefaultClientConfig.setRegion(Region.US_ASHBURN_1);

ClientConfiguration clientConfig = ...;
ObjectStorage clientWithExplicitClientConfig = new ObjectStorageClient(provider, clientConfig);
clientWithExplicitClientConfig.setRegion(Region.US_ASHBURN_1);

同期コールは、レスポンスが可能になるまでブロックされます。すべてのSDK APIでは、そのAPIからコンテンツが返されるかかどうかには関係なく、レスポンス・オブジェクトが返されます。通常、レスポンス・オブジェクトには少なくともリクエストIDが含まれます。これは、特定のリクエストについてOracleサポートに連絡する際に使用できます。

ObjectStorage client = ...;
GetBucketResponse response = client.getBucket(
    GetBucketRequest.builder().namespaceName("myNamespace").bucketName("myBucket").build());
String requestId = response.getOpcRequestId();
Bucket bucket = response.getBucket();
System.out.println(requestId);
System.out.println(bucket.getName());

非同期コール

非同期コールを行うには、非同期クライアントのインスタンスを作成します。非同期クライアントの一般的なパターンでは、Exampleという名前のサービスに対して、ExampleServiceAsyncという名前のインタフェースが存在し、非同期クライアント実装はExampleServiceAsyncClientと呼ばれます。次に、オブジェクト・ストレージ・クライアントを作成する例を示します:

AuthenticationDetailsProvider provider = ...;
ObjectStorageAsync clientWithDefaultClientConfig = new ObjectStorageAsyncClient(provider);
clientWithDefaultClientConfig.setRegion(Region.US_ASHBURN_1);
 
ClientConfiguration clientConfig = ...;
ObjectStorageAsync clientWithExplicitClientConfig = new ObjectStorageAsyncClient(provider, clientConfig);
clientWithExplicitClientConfig.setRegion(Region.US_ASHBURN_1);

非同期コールはすぐに返されます。成功か失敗にかかわらずコールが完了したときに起動するAsyncHandlerを指定する必要があります。

ObjectStorageAsync client = ...;
 
AsyncHandler<GetBucketRequest, GetBucketResponse> handler = new AsyncHandler<GetBucketRequest, GetBucketResponse>() {
        @Override
        public void onSuccess(GetBucketRequest request, GetBucketResponse response) {
            String requestId = response.getOpcRequestId();
            Bucket bucket = response.getBucket();
            System.out.println(requestId);
            System.out.println(bucket.getName());
        }

        @Override
        public void onError(GetBucketRequest request, Throwable error) {
            error.printStackTrace();
        }
};
 
Future<GetBucketResponse> future = client.getBucket(
        GetBucketRequest.builder().namespaceName("myNamespace").bucketName("myBucket").build(),
        handler);

ウェイタによるポーリング

SDKで提供されるウェイタを使用すると、特定のリソースが目的の状態に到達するまでコードが待機するようにできます。ウェイタは、ブロッキング方式または非ブロッキング方式(非同期コールバックを使用)で呼び出すことができ、目的の状態に到達するかタイムアウトが超過するまで待機します。ウェイタによってポーリング・ロジックが抽象化されます。これがなければ、ユーザーが、使いやすい1つのメソッド・コールとしてロジックを記述する必要があります。

ウェイタはサービス・クライアント(client.getWaiters())を介して取得されます。Get<Resource>Requestと目的のライフサイクル状態の両方がwaiters.for<Resource>メソッドに渡されます。例:

public static Instance waitForInstanceProvisioningToComplete(  ComputeClient computeClient, String instanceId) throws Exception {
        
    ComputeWaiters waiters = computeClient.getWaiters();
    GetInstanceResponse response = waiters.forInstance(
        GetInstanceRequest.builder().instanceId(instanceId).build(),
        Instance.LifecycleState.Running)
    .execute();
        
    return response.getInstance();
}

waiters.for<Resource>メソッドには2つのバージョンがあります:

  • 1つのバージョンではデフォルトのポーリング値が使用されます。例:

    waiters.forInstance(GetInstanceRequest, LifecycleState)
  • もう一方のバージョンでは、待機時間およびポーリング試行間隔をユーザーが完全に制御できます。例:

    waiters.forInstance(GetInstanceRequest, LifecycleState, TerminationStrategy, DelayStrategy)

スレッド・モデル

クライアントは、初期化されるときにスレッドセーフになります。エンドポイントを設定したら、複数のスレッドでクライアントを安全に使用し、そこでメソッドを同時にコールできます。

クライアントは、同時スレッド全体でも単一のスレッド内でも、複数のリクエストに対して再利用できます。環境のリソースが制約されないかぎり、クライアントをすぐにクローズする必要があるのは、スコープ外になる場合のみです。

ノート

この保証は、デフォルトのJAX-RS実装であるJerseyのみに適用されます。別の実装を使用している場合は、独自にスレッド・セーフティを管理する必要があります。詳細は、SDKの構成を参照してください

ラージ・オブジェクトのアップロード

オブジェクト・ストレージ・サービスではマルチパート・アップロードがサポートされています。ラージ・オブジェクトをパートに分割することでラージ・オブジェクトのアップロードが容易になります。SDK for Javaでは、高度なユースケース向けのRawマルチパート・アップロード操作と、マルチパート・アップロードAPIを使用する高レベル・アップロード・クラスがサポートされています。マルチパート・アップロードの使用では、マルチパート・アップロード操作で使用されるAPIへのリンクが示されています。高レベルのマルチパート・アップロードは、UploadManagerを使用して実装されます。これは、ラージ・オブジェクトをパートに分割し、パートを並列でアップロードした後で、パートを再結合してストレージでコミットします。

UploadObjectの例では、オブジェクト・ストレージ・サービスとの相互作用を簡略化するため、UploadManagerを使用して、アップロード用にオブジェクトを自動的にパート分割する方法を示します。

再試行

バージョン2.10.0以降、SDK for Javaはデフォルトで、失敗した特定のSDK操作を再試行するよう構成されています。SDKによって、再試行の回数、SDKが操作を再試行する条件、操作の再試行を停止するタイミングなど、再試行の処理方法に使用する戦略を指定できます。これらのパラメータは、クライアント・レベルおよび個々のリクエスト・レベルで設定できます。

デフォルトで再試行が有効になっているサービス操作を確認するには、SDKのサービス操作の説明を参照してください。

ノート

現在、非同期クライアントでは再試行はサポートされていません

SDKでデフォルトで再試行されるのは、HTTPレスポンス・ステータス・コードが409 (IncorrectStateエラー・コードあり)、429、500、502、503、504の操作、タイムアウト・エラー(HTTP接続および読取りタイムアウトなど)、リクエスト接続エラー、リクエスト例外およびサーキット・ブレーカ例外です。

最新のデフォルトの再試行構成と再試行可能なエラーのリストは、Githubで参照できます。

デフォルトの再試行の無効化

デフォルトの再試行機能をオプトアウトするには、次を実行します:

  1. 環境変数OCI_SDK_DEFAULT_RETRY_ENABLEDfalseに設定して、デフォルトの再試行をグローバルに無効化します
  2. 特定のクライアント・インスタンスのデフォルトの再試行をオーバーライドします。この例では、objectStorageClientのデフォルトの再試行をオーバーライドしています。

    ClientConfiguration clientConfiguration =
            ClientConfiguration.builder()
                    .retryConfiguration(RetryConfiguration.builder().terminationStrategy(new MaxAttemptsTerminationStrategy(1))
                            .build())
                    .build();
    ObjectStorage objectStorageClient = ObjectStorageClient.builder().configuration(clientConfiguration).build(provider);
    
  3. 特定のリクエスト・インスタンスのデフォルトの再試行をオーバーライドします。この例では、putObjectRequestの再試行をオーバーライドしています:

    PutObjectRequest putObjectRequest =
            PutObjectRequest.builder()
                    .putObjectBody(stream)
                    .bucketName(bucketName)
                    .objectName(objectName)
                    .namespaceName(namespace)
                    .retryConfiguration(RetryConfiguration.builder().terminationStrategy(new MaxAttemptsTerminationStrategy(1)).build())
                    .build();

再試行動作の優先順位

  • リクエスト・レベルで明示的に定義した再試行構成では、クライアント・レベルの再試行構成またはグローバル・レベルの再試行構成と、その特定のリクエスト・インスタンスの環境変数オーバーライドがオーバーライドされます。
  • クライアント・レベルで明示的に定義された再試行構成では、グローバルの再試行構成、およびその特定のクライアント・インスタンスの環境変数レベルのオーバーライドがオーバーライドされます。

再試行戦略

再試行の処理方法に使用する戦略の指定が可能で、これには再試行回数、SDKが操作を再試行する条件、操作の再試行を停止するタイミングなどが含まれます。これらのパラメータは、クライアント・レベルおよび個々のリクエスト・レベルで設定できます。
ノート

デフォルトの再試行構成の最新バージョンおよび再試行可能なエラーのリストは、Githubで参照できます。

遅延戦略

delayStrategyパラメータは、各再試行コール間の待機時間を決定します。このパラメータには、2つのオプションがあります:

  • FixedTimeDelayStrategy (milliseconds) - 再試行はそれぞれに指定されたミリ秒数だけ遅延します。
  • ExponentialBackoffDelayStrategy (milliseconds) - 後続の再試行コールの遅延時間は、定義された最大遅延(ミリ秒単位)に達するまで指数因子2で増加します(ベース値は1ミリ秒)。

デフォルトの遅延戦略はExponentialBackoffDelayStrategyに設定されており、ジッタ値は0から1000ミリ秒、コール間の最大待機時間は30秒です。

再試行条件

retryConditionは、再試行するかどうかを示すブールを返すエラー引数を使用してファンクションを定義します。このファンクションがtrueを返す場合、操作は再試行されます。

終了戦略

terminationStrategyパラメータは、再試行を終了するタイミングを定義します。このパラメータは、次のオプションをサポートしています:

  • MaxTimeTerminationStrategy (milliseconds) - 再試行の合計期間をミリ秒単位で定義します。
  • MaxAttemptsTerminationStrategy (attempts) - 再試行の合計回数を定義します。

OCI SDKのデフォルトの終了戦略は、MaxAttemptsTerminationStrategyで、8に設定されています。

再試行の例

Java

この例では、SDK for Javaで再試行を構成して使用する方法を示しています:

/**
 * Copyright (c) 2016, 2021, Oracle and/or its affiliates.  All rights reserved.
 * This software is dual-licensed to you under the Universal Permissive License (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl or Apache License 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose either license.
 */
import com.oracle.bmc.ClientConfiguration;
import com.oracle.bmc.ConfigFileReader;
import com.oracle.bmc.auth.AuthenticationDetailsProvider;
import com.oracle.bmc.auth.ConfigFileAuthenticationDetailsProvider;
import com.oracle.bmc.identity.Identity;
import com.oracle.bmc.identity.IdentityClient;
import com.oracle.bmc.identity.requests.ListRegionsRequest;
import com.oracle.bmc.identity.responses.ListRegionsResponse;
import com.oracle.bmc.retrier.Retriers;
import com.oracle.bmc.retrier.RetryConfiguration;
import com.oracle.bmc.waiter.FixedTimeDelayStrategy;
import com.oracle.bmc.waiter.MaxAttemptsTerminationStrategy;

/**
 * This example demonstrates how to use the SDK retries.
 *
 * Retry configuration may be set at
 * a) the SDK level (using {@link Retriers#setDefaultRetryConfiguration(RetryConfiguration)}
 * b) the client level (using {@link ClientConfiguration}
 * c) the request level (using {@link com.oracle.bmc.requests.BmcRequest#setRetryConfiguration(RetryConfiguration)}
 */
public class RetryExample {
    public static void main(String[] args) throws Exception {
        String configurationFilePath = "~/.oci/config";
        String profile = "DEFAULT";

        // Configuring the AuthenticationDetailsProvider. It's assuming there is a default OCI config file
        // "~/.oci/config", and a profile in that config with the name "DEFAULT". Make changes to the following
        // line if needed and use ConfigFileReader.parse(configurationFilePath, profile);

        final ConfigFileReader.ConfigFile configFile = ConfigFileReader.parseDefault();

        final AuthenticationDetailsProvider provider =
                new ConfigFileAuthenticationDetailsProvider(configFile);

        // Set the default retry strategy for all operations to set retry attempts to 3
        Retriers.setDefaultRetryConfiguration(
                RetryConfiguration.builder()
                        .terminationStrategy(new MaxAttemptsTerminationStrategy(3))
                        .build());

        // Override the default retry strategy for the identity client and update retry attempts to 4
        final Identity identityClient =
                new IdentityClient(
                        provider,
                        ClientConfiguration.builder()
                                .retryConfiguration(
                                        RetryConfiguration.builder()
                                                .terminationStrategy(
                                                        new MaxAttemptsTerminationStrategy(4))
                                                .build())
                                .build());

        // Override the client's retry strategy for the list regions request and wait for 5ms between retrying
        final ListRegionsRequest listRegionsRequest =
                ListRegionsRequest.builder()
                        .retryConfiguration(
                                RetryConfiguration.builder()
                                        .terminationStrategy(new MaxAttemptsTerminationStrategy(2))
                                        .delayStrategy(new FixedTimeDelayStrategy(5L))
                                        .build())
                        .build();
        final ListRegionsResponse listRegionsResponse =
                identityClient.listRegions(listRegionsRequest);

        System.out.println(listRegionsResponse.getItems());
    }
}

サーキット・ブレーカ

バージョン2.10.0以降、SDK for Javaでは、デフォルトのSDKサーキット・ブレーカが有効になっているサービス・クライアント向けに、サーキット・ブレーカがデフォルトでサポートされています。サーキット・ブレーカを使用すると、特定の失敗のしきい値に達した後、サービスにリクエストが送信されないようにすることで、クライアントがサービスに負荷をかけるのを防ぐことができます。

ノート

現在、非同期クライアントではサーキット・ブレーカはサポートされていません。

デフォルトのサーキット・ブレーカでは、再試行可能なすべてのエラーは、そのサーキット・ブレーカの失敗として処理されます。どのサービス・クライアントでサーキット・ブレーカが有効になっているかを確認するには、SDKでサービス・クライアントの説明を参照してください。

ノート

デフォルトのサーキット・ブレーカ構成は、Githubで確認できます。

回路遮断器の構成

次のパラメータで、サーキット・ブレーカを定義します:

  • 失敗率のしきい値 - 失敗率がこのしきい値以上になると、サーキット・ブレーカの状態がクローズからオープンに変わります。たとえば、記録されたコールの失敗が50%を超えると、サーキット・ブレーカがオープンになります。
  • タイムアウトのリセット - リクエストが行われた場合、このタイムアウトが経過してから、オープン状態のサーキット・ブレーカでリクエストが試行されます
  • 失敗の例外 - そのサーキットの失敗とみなされる例外のリスト
  • 最小コール数/ボリュームのしきい値 - サーキット・ブレーカがエラー率を計算するために必要な最小コール数(スライディング・ウィンドウ期間ごと)

デフォルトのサーキット・ブレーカ構成

デフォルトのサーキット・ブレーカ構成は次のとおりです:

  • 失敗率のしきい値: 80%。120秒の時間ウィンドウで計算されたリクエストの80%が失敗すると、サーキットはクローズからオープンに変わります。
  • コール/ボリュームの最小しきい値: 上で定義された120秒の時間ウィンドウの場合は10。
  • タイムアウトのリセット: サーキット・ブレーカは、ブレーカをhalfOpen状態に設定し、アクションを再試行する前に30秒待機します。
  • 失敗の例外: サーキットの失敗が記録されるのは、再試行可能な例外または一時的な例外のみです。HTTPレスポンス・コード409 (IncorrectState)、429、500、502、503、504、HTTPリクエストとその他のタイムアウト、リクエスト接続エラーおよび例外はすべて、サーキット・ブレーカをトリガーする失敗として処理されます。

デフォルトのサーキット・ブレーカの無効化

デフォルトのサーキット・ブレーカ機能をオプトアウトするには、次のいずれかを実行します:

  1. 環境変数OCI_SDK_DEFAULT_CIRCUITBREAKER_ENABLEDfalseに設定します。
  2. クライアント・インスタンスのデフォルトのサーキット・ブレーカ構成を変更します。次の例では、IdentityClientインスタンスでこれを実行する方法を示しています:
    ClientConfiguration clientConfiguration =
            ClientConfiguration.builder().circuitBreakerConfiguration(CircuitBreakerUtils.getNoCircuitBreakerConfiguration()).build();
     
            // Create Clients using above ClientConfiguration
            IdentityClient identityClient = new IdentityClient(provider, clientConfiguration);

サーキット・ブレーカの動作の優先順位

クライアント・レベルで明示的に定義したサーキット・ブレーカ構成は、グローバルのデフォルトのサーキット・ブレーカ構成、およびそのクライアントの環境レベルのオーバーライドをオーバーライドします。

サーキット・ブレーカおよびデフォルトのサーキット・ブレーカ構成の詳細は、Githubのこの例を参照してください。

Rawリクエスト

Rawリクエストは役に立ちます。場合によっては必要です。一般的なユースケースは、独自のHTTPクライアントを使用して、代替エンドポイントへのOCI認証リクエストを作成する場合、およびSDKで現在サポートされていないOCI APIに対してリクエストを作成する場合です。SDK for Javaで公開されるDefaultRequestSignerクラスを使用して、標準以外のリクエストのRequestSignerインスタンスを作成できます。

GitHubのRawリクエストの例では、次の方法が示されています:

  • 認証プロバイダとリクエスト署名者を作成します
  • HTTPクライアント(この例ではJersey)と統合してリクエストを認証します

エンドポイントの設定

サービス・エンドポイントは3つの方法で設定できます。

  • サービス・インスタンスに対してsetEndpoint()をコールします。こうすると、完全なホスト名(たとえばhttps://www.example.com)を指定できます。
  • サービス・インスタンスに対してsetRegion()をコールします。こうすると、指定したリージョンのサービスに適切なホスト名が選択されます。ただし、設定したリージョンでサービスがサポートされていない場合は、SDK for Javaからエラーが返されます。
  • 構成ファイルでリージョンを渡します。詳細は、SDKおよびCLIの構成ファイルを参照してください。

サービス・インスタンスは、様々なリージョンとの通信には使用できないことに注意してください。様々なリージョンへのリクエストを行う必要がある場合は、複数のサービス・インスタンスを作成します。

専用エンドポイント

専用エンドポイントは、クライアント・レベルの特定のレルムに対してサービスによって定義されたエンドポイント・テンプレートです。OCI Java SDKでは、アプリケーション・レベルとクライアント・レベルの両方でレルム固有のエンドポイント・テンプレート機能の使用を有効にできます。この機能はデフォルトでは無効です。
ノート

クライアント・レベルで設定された値は、アプリケーション・レベルで設定された値より優先されます。

アプリケーション・レベルでのレルム固有のエンドポイント・テンプレートの有効化:

アプリケーション・レベルでレルム固有のエンドポイント・テンプレート機能を有効にするには、環境変数OCI_REALM_SPECIFIC_SERVICE_ENDPOINT_TEMPLATE_ENABLEDtrueに設定します。
ノート

ブール値では大/小文字が区別されません。

アプリケーション・レベルでのレルム固有のエンドポイント・テンプレートの有効化:

クライアント・レベルでレルム固有のエンドポイント・テンプレート機能を有効にするには、次のようにコードにフラグを設定します。

OCI SDK for Javaの場合:

ObjectStorage client = ObjectStorageClient.builder().build(provider);
client.useRealmSpecificEndpointTemplate(true);

完全な例については、GithubのUseRealmSpecificEndpointsExampleを参照してください。

レガシーOCI Java用SDKの場合:

ObjectStorage client = new ObjectStorageClient(provider);
client.useRealmSpecificEndpointTemplate(true);

完全な例については、GitHubのUseRealmSpecificEndpointsExampleを参照してください。

上位互換性と列挙型

列挙型に基づいた条件ロジックがある場合は、上位互換性を確保するためにコードでUnknownEnumValueケースを処理してください。一部のレスポンス・フィールドは列挙型ですが、将来的には、個々のサービスで返される値が、そのフィールドの既存の列挙型で対応されなくなる可能性があります。この可能性に対処するため、列挙型のすべてのレスポンス・フィールドには、UnknownEnumValueという名前の追加の値があります。サービスから返された値が、使用しているバージョンのSDKで認識されない場合、レスポンス・フィールドにこの値が設定されます。

新しいリージョンのサポート

新リージョン発表の前にリリースされたSDKのバージョンを使用している場合は、そのリージョンにアクセスするための対処方法を使用できます。

リージョンとは、限定された地理的領域のことです。リージョンの詳細と指定方法は、リージョンおよび可用性ドメインを参照してください。

レルムは、エンティティを共有する一連のリージョンです。ネットワーク・アドレスの最後にあるドメイン名を見ると、レルムがわかります。たとえば、xyz.abc.123.oraclecloud.comのレルムは、oraclecloud.comです。

最初にRegion.registerをコールして新しいリージョンを登録する必要があります。その後、構成ファイルを使用するか、setRegionメソッドをコールして、リージョンを設定できます。

ノート

リージョンが登録されると、インスタンス・プリンシパルを使用するときに、フェデレーション・エンドポイントはもう必要なくなります。例は、https://github.com/oracle/oci-java-sdk/blob/master/bmc-examples/src/main/java/NewRegionAndRealmSupportWithoutSDKUpdate.javaを参照してください。

oraclecloud.comレルム

oraclecloud.comレルムのリージョンの場合、SDKバージョンのリージョン列挙にすでに定義されているリージョン名を渡すのと同じように、新しいリージョン名を渡すことができます。

ノート

次のコード・サンプルでは、ご使用のリージョンに適切なエンドポイントを必ず指定してください。

SDK for Javaのバージョン1.2.34以上を使用している場合は、次のいずれかの方法で新しいリージョン名を文字列として渡すことができます:

  • 以前に作成したクライアント上でリージョンを設定するには:

    client.setRegion("ca-toronto-1");
  • 新しいクライアントの構築時にリージョンを設定するには:

    Identity identityClient = IdentityClient.builder()
            .region("ca-toronto-1")
            .build(provider); 
  • 構成ファイルでリージョンを渡すこともできます。詳細は、SDKおよびCLIの構成ファイルを参照してください。

他のレルム

oraclecloud.com以外のレルムのリージョンの場合は、次の対処方法を使用して、以前のバージョンのSDKで新しいリージョンにアクセスできます。

エンドポイントを指定するには:
AuthenticationDetailsProvider provider =
        new ConfigFileAuthenticationDetailsProvider(configurationFilePath, profile);

IdentityClient client = IdentityClient.builder()
        .endpoint("https://identity.ca-toronto-1.oraclecloud.com")
        .build(provider);
インスタンス・プリンシパルを介して認証している場合は、次のプロセスでendpointおよびfederationEndpointを設定できます:
InstancePrincipalsAuthenticationDetailsProvider provider = InstancePrincipalsAuthenticationDetailsProvider.builder()
        .federationEndpoint("https://auth.ca-toronto-1.oraclecloud.com/v1/x509")
        .build();

IdentityClient identityClient = IdentityClient.builder()
        .endpoint("https://identity.ca-toronto-1.oraclecloud.com")
        .build(provider);

ページ区切りされたレスポンス

一部のAPIではページ区切りされた結果セットが返されるため、さらにアイテムがないか確認して、必要であれば次のページをフェッチする必要があります。これは、手動で行うことも、イテレータを使用して行うこともできます。

ページの手動フェッチ

Responseオブジェクトには、次のページ・トークンをフェッチするメソッドが含まれています。トークンがnullの場合、これ以上アイテムはありません。nullでない場合は、Requestオブジェクトにトークンを設定して追加のリクエストを作成し、レスポンスの次のページを取得することができます。

ノート

APIによっては、追加の結果がなくてもトークンが返される場合があります。返されているアイテムがないかを確認して、ない場合に停止してください。

この例は、オブジェクト・ストレージAPIによって返されたページ・トークンの処理方法を示しています:

ObjectStorage client = ...;
 
ListBucketsRequest.Builder builder =
    ListBucketsRequest.builder().namespaceName(namespace);
String nextPageToken = null;
do {
    builder.page(nextPageToken);
    ListBucketsResponse listResponse = client.listBuckets(builder.build());
    List<Bucket> buckets = listResponse.getItems();
    // handle buckets
    nextPageToken = listResponse.getOpcNextPage();
} while (nextPageToken != null);

イテレータの使用

ページ・トークンを手動で操作するかわりに、イテレータを使用できます。各サービス・クライアントで公開されるgetPaginators()メソッドからPaginatorオブジェクトが返されます。このオブジェクトには、Iterable型のオブジェクトを返すメソッドが含まれています。iterableを使用するために、次の2つの方法をサポートされています:

  • レスポンス・イテレータ: リスト表示操作で返されるResponseオブジェクトに対して反復処理を行うことができます。これらはResponseIteratorと呼ばれ、そのメソッドには接尾辞としてResponseIteratorが付きます(たとえばlistUsersResponseIterator)。
    Iterable<ListUsersResponse> responseIterator = identityClient.getPaginators().listUsersResponseIterator(request);
    for (ListUsersResponse response : responseIterator) {
        for (User user : response.getItems()) {
            System.out.println(user);
        }
    }
  • レコード・イテレータ: リスト表示されるリソース/レコードに対して反復処理を行うことができます。これらはRecordIteratorと呼ばれ、そのメソッドには接尾辞としてRecordIteratorが付きます(たとえばlistUsersRecordIterator)。
    Iterable<User> recordIterator = identityClient.getPaginators().listUsersRecordIterator(request)
    for (User user : recordIterator) {
        System.out.println(user);
    }

クライアント側の暗号化

クライアント側の暗号化では、クライアント側のデータを、ローカルに格納する前、または他のOracle Cloud Infrastructureサービスでデータを使用する前に暗号化できます。

クライアント側の暗号化を使用するには、キー管理サービスを使用してマスター暗号化キー(MEK)を作成する必要があります。これは、CreateKeyまたはImportKey操作を使用して行います。

MEKは、各ペイロードを暗号化するデータ暗号化キー(DEK)の生成に使用されます。このDEKの暗号化されたコピー(MEKで暗号化済)およびその他のメタデータの断片は、復号化に使用できるように、SDKによって返される暗号化されたペイロードに含まれます。

Javaの前提条件

以前のリリースでの無制限のポリシー・ファイルは、8u161、7u171および6u16より前のJDK 8、7および6の更新にのみ必要です。これらのバージョン以降の場合、ポリシー・ファイルは含まれていますが、デフォルトで有効になっていません。

JDKの現在のバージョンでは、これらのポリシー・ファイルは必要ありません。これらは、古いバージョンのJDKで使用するためにここに提供されています。JDK 9以降は無制限のポリシー・ファイルとともに出荷され、デフォルトでこれらが使用されます。

次のコード例は、文字列の暗号化方法を示しています:


// String encryption example
			
final byte[] plainText = "Hello World".getBytes();
String masterKeyId = "OCID....";
Map<String, String> context = Collections.singletonMap("Example", "value");
 
OciCrypto ociCrypto = new OciCrypto();
KmsMasterKey kmsMasterKey = new KmsMasterKey(authenticationProvider, Region.US_ASHBURN_1.getRegionId(), vaultId, masterKeyId);
KmsMasterKeyProvider kmsMasterKeyProvider = new KmsMasterKeyProvider(kmsMasterKey);
 
//  Encrypt the data and embed the master key ID in the header
final OciCryptoResult encryptResult = ociCrypto.encryptData(kmsMasterKeyProvider, plainText, context);
final byte[] cipherText = encryptResult.getResult();
 
//  Decrypt the data
final OciCryptoResult decryptResult = ociCrypto.decryptData(kmsMasterKeyProvider, cipherText);

次の例は、ファイル・ストリームの暗号化方法を示しています:


// Create Encryption file stream
FileInputStream in = new FileInputStream(srcFile);
OciCrypto ociCrypto = new OciCrypto();
KmsMasterKey kmsMasterKey = new KmsMasterKey(authenticationProvider, Region.US_ASHBURN_1.getRegionId(), vaultId, masterKeyId);
KmsMasterKeyProvider kmsMasterKeyProvider = new KmsMasterKeyProvider(kmsMasterKey);
OciCryptoInputStream encryptingStream = ociCrypto.createEncryptingStream(kmsMasterKeyProvider, in);
 
// Write the encrypted data to file
FileOutputStream out = new FileOutputStream(srcFile + ".encrypted");
IOUtils.copy(encryptingStream, out);
encryptingStream.close();
out.close();
 
// For decryption, no need to pass key info
KmsMasterKeyProvider kmsMasterKeyProvider = new KmsMasterKeyProvider(authenticationProvider);
// Create the Decryption file stream.
in = new FileInputStream(srcFile + ".encrypted");
OciCryptoInputStream decryptingStream = ociCrypto.createDecryptingStream(kmsMasterKeyProvider, in);
 
 
// Return the plaintext data
out = new FileOutputStream(srcFile + ".decrypted");
IOUtils.copy(decryptingStream, out);
decryptingStream.close();
out.close();

例外の処理

例外を処理するとき、原因となったHTTPリクエストに関する詳細(ステータス・コードやタイムアウトなど)を取得できます。getOpcRequestIdメソッドを使用して、BmcExceptionを処理する際にリクエストIDを取得することもできます。

この例では、BmcExceptionを処理してリクエストIDを出力するtry-catchブロックを示します。

ObjectStorage client = ...;
try {
    GetBucketResponse response = client.getBucket(
	        GetBucketRequest.builder().namespaceName("myNamespace").bucketName("myBucket").build());
    String requestId = response.getOpcRequestId();
    System.out.println(requestId);
} catch (BmcException e) {
    String requestId = e.getOpcRequestId();
    System.out.println(requestId);
    e.printStackTrace();
}

SDK for Javaの例外は実行時例外(未チェック)であるため、メソッド・シグネチャには示されません。すべてのAPIでBmcExceptionがスローされる可能性があります。