Oracle Cloud Infrastructureドキュメント

構成

このトピックでは、Oracle Cloud Infrastructure SDK for Javaの互換性、拡張構成およびアドオンについて詳しく説明します。

このトピックでは、Oracle Cloud Infrastructure SDK for Javaの互換性、拡張構成およびアドオンについて詳しく説明します。

セキュリティ・マネージャの権限

アプリケーションをJava Security Manager内で実行する必要がある場合は、ポリシー・ファイルを更新するか、または追加すなわち別のポリシー・ファイルを実行時に指定することによって、追加の権限を付与する必要があります。

SDKでは、次の権限が必要です:

  • Jerseyで必要: 

    
permission java.lang.RuntimePermission "getClassLoader";
permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
permission java.lang.RuntimePermission "accessDeclaredMembers";
permission java.util.PropertyPermission "*", "read,write";
permission java.lang.RuntimePermission "setFactory";

  • SDKが予約済ヘッダーを上書きするために必要: 

    permission java.util.PropertyPermission "sun.net.http.allowRestrictedHeaders", "write";

  • SDKがソケット接続を開くために必要: 

    permission java.net.SocketPermission "*", "connect";

Java Runtime Environmentのデフォルト・ポリシー・ファイルに加えて、別のポリシー・ファイルを含めるには、次のようにJava Virtual Machineを起動します:

java -Djava.security.manager -Djava.security.policy=</path/to/other_policy>

デフォルト・ポリシー・ファイルを置き換えるには、Java Virtual Machineを次のように起動します:

java -Djava.security.manager -Djava.security.policy==</path/to/other_policy>
ノート

追加のポリシー・ファイルを指定するときは、等号を1つ(=)使用します。等号を2つ(==)使用するのは、デフォルト・ポリシー・ファイルを置き換える場合のみです。

DNS名前参照のJava Virtual Machine TTL

Java Virtual Machine (JVM)は、参照に対するDNS応答を一定時間キャッシュしますが、この時間はtime-to-live (TTL)と呼ばれます。これにより、頻繁に名前を解決する必要があるコードでの応答時間が短縮されます。

JVMは、networkaddress.cache.ttlプロパティを使用して、DNS名前参照のキャッシュ・ポリシーを指定します。値は、成功した参照をキャッシュする秒数を表す整数です。多くのJVMのデフォルト値は-1ですが、これは参照が永久にキャッシュされることを指定します。

Oracle Cloud Infrastructureのリソースが使用するDNS名は変わる可能性があるため、TTL値を60秒に変更することをお薦めします。こうすると、次のDNS問合せでリソースの新しいIPアドレスが返されるようになります。この値はグローバルに変更することも、ご使用のアプリケーションについてのみ変更することもできます:

  • JVMを使用してグローバルにすべてのアプリケーションのTTLを設定するには、$JAVA_HOME/jre/lib/security/java.securityファイルに次を追加します: 

    networkaddress.cache.ttl=60

  • ご使用のアプリケーションのみのTTLを設定するには、アプリケーションの初期化コードに次を設定します: 

    java.security.Security.setProperty("networkaddress.cache.ttl" , "60");

JerseyのデフォルトであるHttpUrlConnectorProviderの使用

バージョン2.0.0以降、SDK for Javaでは、JerseyのデフォルトであるHttpUrlConnectorProviderではなく、Jersey ApacheConnectorProviderの使用がデフォルトでサポートされており、Apache HttpClientによるOCIサービス・コールの実行が可能になっています。

クライアント・レベルでJerseyのデフォルト・コネクタに変更する手順

クライアント・レベルでは、SDKによって、古いJerseyのデフォルト・コネクタに戻す次の方法が提供されます:

ObjectStorageClient nonBufferingObjectStorageClient = ObjectStorageClient
        .builder()
        .clientConfigurator(builder -> {
            builder.property(JerseyClientProperties.USE_APACHE_CONNECTOR, false);
        })
        // ...
        .build(provider);
ノート

クライアントのclientConfiguratorプロパティをオーバーライドすると、Jerseyのデフォルトに戻ります。Apacheコネクタを使用してclientConfiguratorを構成するには、additionalClientConfiguratorまたはadditionalClientConfiguratorsを使用します。

グローバル・レベルでJerseyのデフォルト・コネクタに変更する手順

Apache HttpClient依存関係を除外することも、環境変数を使用することも可能です。HttpClient依存関係の除外

依存関係を自分で管理する場合:

  • クラスパスからorg.apache.httpcomponents.httpclientおよびorg.glassfish.jersey.connectors.jersey-apache-connector JARを削除します

Mavenを使用して依存性を管理する場合:

  • org.apache.httpcomponents.httpclientおよびorg.glassfish.jersey.connectors.jersey-apache-connector依存関係の除外を追加します

    • Jersey 2を使用している場合に除外を追加するには:

      <dependencies>
    ...
    <dependency>
        <groupId>com.oracle.oci.sdk</groupId>
        <artifactId>oci-java-sdk-common-httpclient-jersey</artifactId>
        <version>...</version>
        <exclusions>
            <exclusion>
                <groupId>org.glassfish.jersey.connectors</groupId>
                <artifactId>jersey-apache-connector</artifactId>
            </exclusion>
            <exclusion>
                <groupId>org.apache.httpcomponents</groupId>
                <artifactId>httpclient</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    ...
<dependencies>

    • Jersey 3を使用している場合に除外を追加するには:

      <dependencies>
    ...
    <dependency>
        <groupId>com.oracle.oci.sdk</groupId>
        <artifactId>oci-java-sdk-common-httpclient-jersey3</artifactId>
        <version>...</version>
        <exclusions>
            <exclusion>
                <groupId>org.glassfish.jersey.connectors</groupId>
                <artifactId>jersey-apache-connector</artifactId>
            </exclusion>
            <exclusion>
                <groupId>org.apache.httpcomponents</groupId>
                <artifactId>httpclient</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    ...
<dependencies>
環境変数を使用した切替え

SDK for Javaには、グローバル・レベルでJerseyの以前のデフォルト・コネクタに切り替えるための環境変数が用意されています。OCI_JAVASDK_JERSEY_CLIENT_DEFAULT_CONNECTOR_ENABLED環境変数の値をtrueに設定します。デフォルトでは、この値はfalseに設定されています。

ストリームの自動終了をオフに切替え

バイナリ/ストリーム・レスポンスを返すAPIコールの場合、ストリームが完全に読み取られると、そのストリームはSDKによって自動的に終了されます。これはSDK for Javaで、リクエストの送信とサービスへの接続管理のためにApacheコネクタがサポートされているためです。デフォルトでは、Apacheコネクタでは接続プーリングがサポートされています。レスポンスのストリームが終了していない場合、接続は接続プールから解放されません。

自動終了の動作を無効にするには、ResponseHelper.shouldAutoCloseResponseInputStream(false)をコールします。

パフォーマンスを最適化するためのApacheコネクタでの接続の切断方法の選択

Apacheコネクタでは、ApacheConnectionClosingStrategy.GracefulClosingStrategyとApacheConnectionClosingStrategy.ImmediateClosingStrategyの2つ戦略で接続を切断できます。

ApacheConnectionClosingStrategy.GracefulClosingStrategyを使用すると、レスポンスから返されたストリームは、ストリームを終了するときにストリームの最後まで読み取られます。このため、残りのストリームの大きさによっては、部分読取りが行われるストリームを終了するときに、別途時間がかかる可能性があります。この遅延を回避するため、部分読取りが行われる大規模ファイルでは、ApacheConnectionClosingStrategy.ImmediateClosingStrategyの使用を検討してください。小規模なストリーム・サイズ(1MB未満のストリーム)で部分読取りを使用する場合は、ApacheConnectionClosingStrategy.ImmediateClosingStrategyに時間がかかることに注意してください。

ノート

これらのApache接続の切断方法でお客様のユース・ケースが最適な結果にならない場合は、前述の方法で、JerseyのデフォルトであるHttpUrlConnectorProviderに切り替えることができます。

詳細は、https://github.com/oracle/oci-java-sdk/blob/master/ApacheConnector-README.mdを参照してください。

Bouncy CastleのかわりにBC-FIPSを使用

FIPSに準拠する必要がある場合は、FIPS認定バージョンをダウンロードして使用する必要があります。SDKではbc-fips 1.0.2およびbcpkix-fips 1.0.3がサポートされています。これらはhttps://www.bouncycastle.org/fips-java/からダウンロードできます

Bouncy Castle FIPSのインストールおよび構成のヘルプは、ユーザーズ・ガイドの「BC FIPSドキュメント」およびBouncy Castleのドキュメントのセキュリティ・ポリシーを参照してください。

依存関係の自己管理

依存関係を自分で管理する場合:

  1. FIPS Bouncy Castle jar以外のファイルをクラス・パスから削除します:
    1. bcprov-jdk15on-1.60.jar
    2. bcpkix-jdk15on-1.60.jar
  2. かわりに、FIPS Bouncy Castle jarファイルをクラス・パスに追加します:
    1. bc-fips-1.0.2.jar
    2. bcpkix-fips-1.0.3.jar

依存関係のMavenでの管理

Mavenを使用して依存性を管理する場合:

  1. 正しいバージョンのbc-fipsおよびbcpkix-fipsを依存関係に追加します:
    <dependencies>
  . . .
  <dependency>
    <groupId>bc-fips</groupId>
    <artifactId>bc-fips</artifactId>
    <version>1.0.2</version>
  </dependency>
  <dependency>
    <groupId>bcpkix-fips</groupId>
    <artifactId>bcpkix-fips</artifactId>
    <version>1.0.3</version>
  </dependency>
  . . .
</dependencies>
  2. oci-java-sdk*パッケージに依存しているため、FIPS Bouncy Castle以外の依存関係を削除する必要があります:
    <dependencies>
  . . .
  <dependency>
    <groupId>com.oracle.oci.sdk</groupId>
    <artifactId>oci-java-sdk-common</artifactId>
    <version> . . . </version>
    <exclusions>
      <exclusion>
        <groupId>org.bouncycastle</groupId>
        <artifactId>bcprov-jdk15on</artifactId>
      </exclusion>
      <exclusion>
        <groupId>org.bouncycastle</groupId>
        <artifactId>bcpkix-jdk15on</artifactId>
      </exclusion>
    </exclusions>
  </dependency>
  . . .
</dependencies>

独自のJAX-RS実装の使用

SDK for JavaにはJerseyがバンドルされていますが、独自のJAX-RS実装を使用することもできます。

RESTEasyクライアント・コンフィギュレータのアドオン

代替JAX-RS実装の構成方法を説明するために、oci-java-sdk-addons-resteasy-client-configuratorが用意されています。このアドオンは、SDKのbmc-addonsディレクトリにあります。

インストールと構成の詳細は、アドオンのReadmeを参照してください。

クライアントの構成方法を示すコード・サンプルについては、次を参照してください:

SLF4Jを使用したロギング

SDKのロギングは、SLF4Jを使用して行われます。SLF4Jは、ユーザー指定のロギング・ライブラリ(log4jなど)を使用できるするロギング抽象化機能です。詳細は、SLF4Jのマニュアルを参照してください。

次に示す例では、標準出力への基本ロギングを有効にします。log4jバインディングを使用すると、さらに高度なロギング・オプションを構成できます。

  1. SLF4J Simple Binding jarをダウンロードします: SLF4J Simple Binding
  2. jarをクラス・パスに追加します(たとえば、SDKダウンロードの/third-party/libディレクトリに追加します)
  3. 次のVM引数を追加して、debugレベル・ロギングを有効にします(デフォルトではinfoレベルが使用されます): -Dorg.slf4j.simpleLogger.defaultLogLevel=debug