Oracle Cloud Infrastructure - Dokumentation

Konfiguration

Dieses Thema enthält Details zu Kompatibilität, erweiterten Konfigurationen und Add-ons für das Oracle Cloud Infrastructure-SDK für Java.

Dieses Thema enthält Details zu Kompatibilität, erweiterten Konfigurationen und Add-ons für das Oracle Cloud Infrastructure-SDK für Java.

Security Manager-Berechtigungen

Wenn Ihre Anwendung im Java Security Manager ausgeführt werden muss, müssen Sie zusätzliche Berechtigungen erteilen, indem Sie eine Policy-Datei aktualisieren oder eine zusätzliche oder andere Policy-Datei zur Laufzeit angeben.

Für das SDK sind folgende Berechtigungen erforderlich:

  • Für Jersey erforderlich: 

    
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";

  • Zum Überschreiben reservierter Header für das SDK erforderlich: 

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

  • Zum Öffnen von Socket-Verbindungen für das SDK erforderlich: 

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

Um eine weitere Policy-Datei aufzunehmen, starten Sie zusätzlich zur Standard-Policy-Datei von Java Runtime Environment die Java Virtual Machine mit:

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

Um die Standard-Policy-Datei zu ersetzen, starten Sie die Java Virtual Machine mit:

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

Verwenden Sie ein einzelnes Gleichheitszeichen (=), wenn Sie eine zusätzliche Policy-Datei angeben. Verwenden Sie ein doppeltes Gleichheitszeichen (==) nur, wenn Sie die Standard-Policy-Datei ersetzen möchten.

Java Virtual Machine-TTL für DNS-Namen-Lookups

Java Virtual Machine (JVM) cacht DNS-Antworten aus Lookups für einen festgelegten Zeitraum, der als Gültigkeitsdauer (Time to Live; TTL) bezeichnet wird. Dadurch wird eine kürzere Antwortzeit in Code gewährleistet, der häufige Namensauflösungen erfordert.

Die JVM verwendet die Eigenschaft networkaddress.cache.ttl zur Angabe der Caching-Policy für DNS-Namen-Lookups. Der Wert ist eine Ganzzahl, die angibt, wie viele Sekunden der erfolgreiche Lookup im Cache gespeichert wird. Der Standardwert für viele JVMs, -1, gibt an, dass der Lookup unbegrenzt gecacht werden soll.

Da Ressourcen in Oracle Cloud Infrastructure DNS-Namen verwenden, die sich ändern können, wird empfohlen, den TTL-Wert auf 60 Sekunden zu setzen. Dadurch wird sichergestellt, dass die neue IP-Adresse für die Ressource bei der nächsten DNS-Abfrage zurückgegeben wird. Sie können diesen Wert global oder speziell für Ihre Anwendung ändern:

  • Um TTL für alle Anwendungen global mit der JVM festzulegen, fügen Sie Folgendes in der Datei $JAVA_HOME/jre/lib/security/java.security hinzu: 

    networkaddress.cache.ttl=60

  • Um TTL nur für Ihre Anwendung festzulegen, legen Sie Folgendes im Initialisierungscode Ihrer Anwendung fest: 

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

Jersey-Standardwert HttpUrlConnectorProvider verwenden

Ab Version 2.0.0 unterstützt das SDK für Java die Verwendung des Jersey-Wertes ApacheConnectorProvider anstelle des Jersey-Standardwertes HttpUrlConnectorProvider, damit Apache-HttpClient OCI-Serviceaufrufe ausführen kann.

So wechseln Sie auf Clientebene zum Jersey-Standard-Connector

Auf Clientebene bietet das SDK folgende Möglichkeit, um wieder zum alten Jersey-Standard-Connector zu wechseln:

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

Wenn Sie die Eigenschaft clientConfigurator des Clients außer Kraft setzen, werden die Jersey-Standardwerte wiederhergestellt. Um clientConfigurator mit dem Apache-Connector zu konfigurieren, verwenden Sie additionalClientConfigurator oder additionalClientConfigurators.

So ändern Sie den Jersey-Standard-Connector auf globaler Ebene

Sie können die Apache-HttpClient-Abhängigkeiten ausschließen oder eine Umgebungsvariable verwenden. Abhängigkeiten von HttpClient ausschließen

Wenn Sie Abhängigkeiten selbst verwalten:

  • Entfernen Sie die JAR-Dateien org.apache.httpcomponents.httpclient und org.glassfish.jersey.connectors.jersey-apache-connector aus dem Classpath.

Wenn Sie Maven verwenden, um Ihre Abhängigkeiten zu verwalten:

  • Fügen Sie Ausschlüsse für die Abhängigkeiten org.apache.httpcomponents.httpclient und org.glassfish.jersey.connectors.jersey-apache-connector hinzu.

    • So fügen Sie bei Verwendung von Jersey 2 einen Ausschluss hinzu:

      <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>

    • So fügen Sie bei Verwendung von Jersey 3 einen Ausschluss hinzu:

      <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>
Mit einer Umgebungsvariablen zurückwechseln

Das SDK für Java stellt eine Umgebungsvariable für den Wechsel zum alten Jersey-Standard-Connector auf globaler Ebene bereit. Belegen Sie die Umgebungsvariable OCI_JAVASDK_JERSEY_CLIENT_DEFAULT_CONNECTOR_ENABLED mit dem Wert true. Standardmäßig ist dieser Wert auf false gesetzt.

Automatisches Schließen von Streams deaktivieren

Bei API-Aufrufen, die eine Binär-/Streamantwort zurückgeben, schließt das SDK den Stream automatisch, sobald der Stream vollständig gelesen wurde. Der Grund dafür ist, dass das SDK für Java den Apache-Connector für das Senden von Anforderungen und das Verwalten von Verbindungen zum Service unterstützt. Standardmäßig unterstützt der Apache-Connector das Verbindungspooling. Wenn der Stream aus der Antwort nicht geschlossen wird, werden die Verbindungen nicht aus dem Verbindungspool freigegeben.

Um das automatische Schließverhalten zu deaktivieren, rufen Sie ResponseHelper.shouldAutoCloseResponseInputStream(false) auf.

Verbindungsschließungsstrategien mit dem Apache-Connector zur Performanceoptimierung auswählen

Der Apache-Connector unterstützt zwei Verbindungsschließungsstrategien: ApacheConnectionClosingStrategy.GracefulClosingStrategy und ApacheConnectionClosingStrategy.ImmediateClosingStrategy.

Wenn Sie ApacheConnectionClosingStrategy.GracefulClosingStrategy verwenden, werden die von einer Antwort zurückgegebenen Streams bis zum Ende gelesen, bevor der Stream geschlossen wird. Dies kann je nach Größe des restlichen Streams beim Schließen des Streams mit einem partiellen Lesevorgang zusätzliche Zeit erfordern. Um diese Verzögerung zu vermeiden, können Sie ApacheConnectionClosingStrategy.ImmediateClosingStrategy für große Dateien mit partiellen Lesevorgängen verwenden. Beachten Sie, dass ApacheConnectionClosingStrategy.ImmediateClosingStrategy länger dauert, wenn partielle Lesevorgänge für kleinere Streamgrößen (unter 1 MB) verwendet werden.

Hinweis

Wenn diese Apache-Verbindungsschließungsstrategien keine optimalen Ergebnisse für Ihre Anwendungsfälle liefern, können Sie mit der oben angegebenen Methode wieder zum Jersey-Standard-Connector HttpUrlConnectorProvider wechseln.

Weitere Informationen finden Sie unter: https://github.com/oracle/oci-java-sdk/blob/master/ApacheConnector-README.md.

BC-FIPS statt Bouncy Castle verwenden

Wenn Sie FIPS-Compliance benötigen, müssen Sie eine FIPS-zertifizierte Version herunterladen und verwenden. Das SDK unterstützt bc-fips 1.0.2 und bcpkix-fips 1.0.3. Sie können sie hier herunterladen: https://www.bouncycastle.org/fips-java/

Weitere Informationen zur Installation und Konfiguration von Bouncy Castle-FIPS finden Sie in der BC-FIPS-Dokumentation in den Benutzerhandbüchern und der Sicherheits-Policy der Bouncy Castle-Dokumentation.

Selbstverwaltete Abhängigkeiten

Wenn Sie Abhängigkeiten selbst verwalten:

  1. Entfernen Sie die Nicht-FIPS-Bouncy Castle-JAR-Dateien aus dem Classpath:
    1. bcprov-jdk15on-1.60.jar
    2. bcpkix-jdk15on-1.60.jar
  2. Fügen Sie stattdessen die FIPS-Bouncy Castle-JAR-Dateien dem Classpath hinzu:
    1. bc-fips-1.0.2.jar
    2. bcpkix-fips-1.0.3.jar

Von Maven verwaltete Abhängigkeiten

Wenn Sie Maven verwenden, um Ihre Abhängigkeiten zu verwalten:

  1. Fügen Sie den Abhängigkeiten die korrekten Versionen von bc-fips und bcpkix-fips hinzu:
    <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. Da eine Abhängigkeit von einem oci-java-sdk*-Package vorliegt, müssen Sie die Nicht-FIPS-Bouncy Castle-Abhängigkeiten entfernen:
    <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>

Eigene JAX-RS-Implementierung verwenden

Das SDK für Java ist in Jersey gebündelt, Sie können jedoch auch Ihre eigene JAX-RS-Implementierung verwenden.

RESTEasy Client Configurator-Add-on

Die Datei oci-java-sdk-addons-resteasy-client-configurator wird bereitgestellt, um zu veranschaulichen, wie eine alternative JAX-RS-Implementierung konfiguriert wird. Das Add-on befindet sich im Verzeichnis bmc-addons des SDK.

Details zur Installation und Konfiguration finden Sie in der Readme-Datei für das Add-on.

Codebeispiele, die zeigen, wie der Client konfiguriert wird, finden Sie unter:

SLF4J für Logging verwenden

Das Logging im SDK erfolgt über SLF4J. SLF4J ist eine Loggingabstraktion, die die Verwendung einer vom Benutzer angegebenen Logging-Library (z.B. log4j) ermöglicht. Weitere Informationen finden Sie im SLF4J-Handbuch.

Im Folgenden finden Sie ein Beispiel für das grundlegende Logging für die Standardausgabe. Erweiterte Loggingoptionen können mit dem log4j-Binding konfiguriert werden.

  1. Laden Sie die SLF4J-JAR-Datei für einfaches Binding herunter: SLF4J für einfaches Binding
  2. Fügen Sie die JAR-Datei zum Classpath hinzu (fügen Sie sie z.B. zum Verzeichnis /third-party/lib des SDK-Downloads hinzu).
  3. Fügen Sie das folgende VM-Argument hinzu, um das Logging auf Debugebene zu aktivieren (standardmäßig wird die Informationsebene verwendet): -Dorg.slf4j.simpleLogger.defaultLogLevel=debug