oci-java-sdk provides an SDK for Java that you can use to manage your Oracle Cloud Infrastructure resources.

The project is open source and maintained by Oracle Corp. The home page for the project is here.

The OCI Java SDK versions 1.x.y and 2.x.y are now referred as OCI Legacy Java SDK. Any updates or bug fixes related to OCI Legacy Java SDK can be found in legacy/v2/master branch. Please refer README.md to learn more about these legacy versions.

This GitHub repository will refer to OCI Java SDK version 3.x.y by default where support for new features and services will be added.

Full documentation, including prerequisites, installation, supported JDK versions and configuration instructions, is available here.

API reference can be found here.

For basic set up, see Getting Started.

For details on compatibility, advanced configurations, and add-ons, see Configuration.

• Circuit Breaker: By default, circuit breaker feature is enabled, if it is not expected, please explicitly set the environment variable:

  export OCI_SDK_DEFAULT_CIRCUITBREAKER_ENABLED=FALSE
  

• Token Refresh Retries: By default, the token refresh retires are enabled for 401s and processing exceptions. You have the flexibility to disable these retries if needed. This can be achieved by setting the system property

  System.setProperty("oci.javasdk.token.refresh.enabled", "false");
  

For full details, look at the changelog for version 3.0.0-beta1.

There is no HTTP client library configured by default. The OCI Java SDK offers the following two choices for HTTP client libraries to choose from.

• Jakarta EE 8/Jersey 2 - bmc-common-httpclient-jersey

• Jakarta EE 9/Jersey 3 - bmc-common-httpclient-jersey3

• The OCI Java SDK does not choose an HTTP client library for you, and there is no default. You have to explicitly choose one, by declaring a dependency on oci-java-sdk-common-httpclient-jersey or oci-java-sdk-common-httpclient-jersey3

• Example:

    <dependency>
      <!-- Since this is the "application" pom.xml, we do want to
           choose the httpclient to use. -->
      <groupId>com.oracle.oci.sdk</groupId>
      <artifactId>oci-java-sdk-common-httpclient-jersey</artifactId>
    </dependency>
  

• The serializer is now pluggable and determined by the HttpProvider. For the Jersey 2 and Jersey 3 HTTP clients, Jackson continues to be used as the serializer
• As part of the pluggable Serializer changes, when using the Jersey and Jersey 3 HTTP clients, the underlying Jackson ObjectMapper can now be obtained using com.oracle.bmc.serialization.jackson.JacksonSerializer.getDefaultObjectMapper(). The com.oracle.bmc.http.client.Serialization.getObjectMapper() method does not exist anymore.

OCI Java SDK Jersey HTTP client and Jersey 3 Http client are both ready for GraalVM Native Image. See bmc-examples/native-gradle-example and bmc-other-examples/native-maven-example for configuration details for building Native Image executables.

Instead of using com.oracle.bmc.util.internal.Consumer<Invocation.Builder> to register invocation callbacks, use com.oracle.bmc.http.client.RequestInterceptor instead, to decouple the implementation from the choice of the HTTP client.

com.oracle.bmc.http.ClientConfigurator has a single customizeClient(HttpClientBuilder builder) method, instead of customizeBuilder, customizeClient, and customizeRequest methods. Example:

    IdentityClient.builder()
                  .clientConfigurator(
                          builder -> {
                      builder.property(
                              StandardClientProperties.BUFFER_REQUEST, false);
                  })
                  // ...
                  .build(authenticationDetailsProvider);

• For a comprehensive list of pre-defined settable properties, see
  • StandardClientProperties.java
  • ApacheClientProperties.java or ApacheClientProperties.java (Jersey 3)
• You can also define your own properties.
• The actual properties that can be set depends on the HTTP client you are using.

        builder.property(
                StandardClientProperties.BUFFER_REQUEST, shouldBuffer);

        builder.property(
                ApacheClientProperties.CONNECTION_MANAGER,
                connectionManager);

        // Server CA goes into the trust store
        KeyStore trustStore =
                keystoreGenerator.createTrustStoreWithServerCa(tlsConfig.getCaBundle());
        builder.property(StandardClientProperties.TRUST_STORE, trustStore);

        builder.property(
                StandardClientProperties.KEY_STORE,
                new KeyStoreWithPassword(keyStore, keystorePassword));

        builder.property(
                StandardClientProperties.SSL_CONTEXT, sslContext);

        builder.property(
                StandardClientProperties.PROXY, proxyConfig);

        builder.property(
                StandardClientProperties.HOSTNAME_VERIFIER,
                NoopHostnameVerifier.INSTANCE);

• ApacheConnectorPropertiesExample.java
• HttpProxyExample.java
• DisableNoConnectionReuseStrategyUsingApacheConfiguratorExample.java and DisableNoConnectionReuseStrategyUsingApacheConfiguratorExample.java (Jersey 3)

There were numerous changes to decouple the implementation from the choice of the HTTP client.

• com.oracle.bmc.http.ApacheConfigurator, has been replaced by com.oracle.bmc.http.client.jersey.ApacheClientProperties or com.oracle.bmc.http.client.jersey3.ApacheClientProperties (for Jersey 3).

  • For clients that should not buffer requests into memory:

    ObjectStorageClient nonBufferingObjectStorageClient = ObjectStorageClient
        .builder()
        .clientConfigurator(builder -> {
            builder.property(StandardClientProperties.BUFFER_REQUEST, false);
            builder.property(ApacheClientProperties.RETRY_HANDLER, null);
            builder.property(ApacheClientProperties.REUSE_STRATEGY, null);
        })
        .region(Region.US_PHOENIX_1)
        .build(provider);
    

  • For clients that should buffer requests into memory:

    IdentityClient bufferingIdentityClient = IdentityClient
        .builder()
        .clientConfigurator(builder -> {
            builder.property(StandardClientProperties.BUFFER_REQUEST, true);
            builder.property(ApacheClientProperties.RETRY_HANDLER, null);
            builder.property(ApacheClientProperties.REUSE_STRATEGY, null);
        })
        .region(Region.US_PHOENIX_1)
        .build(provider);
    

    • See DisableNoConnectionReuseStrategyUsingApacheConfiguratorExample.java and DisableNoConnectionReuseStrategyUsingApacheConfiguratorExample.java (Jersey 3)

    • Also consider using com.oracle.bmc.http.client.jersey.apacheconfigurator.ApacheConfigurator from the oci-java-sdk-addons-apache-configurator-jerseyadd-on module; orcom.oracle.bmc.http.client.jersey3.apacheconfigurator.ApacheConfiguratorfrom theoci-java-sdk-addons-apache-configurator-jersey3` add-on module.

      • See DisableNoConnectionReuseStrategyUsingApacheConfiguratorExample.java and DisableNoConnectionReuseStrategyUsingApacheConfiguratorExample.java (Jersey 3)
      • If TLS initialization fails, these configurators now throw SSLInitializationException; they no longer map https routes to plaintext. Applications that intentionally require plaintext transport can provide an explicit connection manager, as shown in PlainConnectionSocketFactoryExample.java and PlainConnectionSocketFactoryExample.java (Jersey 3).

• The circuit breaker interface has been renamed from com.oracle.bmc.circuitbreaker.JaxRsCircuitBreaker to com.oracle.bmc.circuitbreaker.OciCircuitBreaker
• Instead of using the constructor of com.oracle.bmc.circuitbreaker.CircuitBreakerConfiguration, use the builder. The constructor is not public anymore.
• The com.oracle.bmc.util.CircuitBreakerUtils class does not deal with actual circuit breakers anymore, just with com.oracle.bmc.circuitbreaker.CircuitBreakerConfiguration. As such, the DEFAULT_CIRCUIT_BREAKER field and the getUserDefinedCircuitBreaker method were removed. Construct a new circuit breaker from the default configuration if necessary using the build methods in com.oracle.bmc.circuitbreaker.CircuitBreakerFactory.

• Class com.oracle.bmc.Options was moved to com.oracle.bmc.http.client.Options
• Class com.oracle.bmc.http.Serialization was moved to com.oracle.bmc.http.client.Serialization and is available from OCI Java SDK versions 3.0.0 to 3.13.1
• Class com.oracle.bmc.io.DuplicatableInputStream was moved to com.oracle.bmc.http.client.io.DuplicatableInputStream

• The signing strategy OBJECT_STORAGE was removed from com.oracle.bmc.http.signing.SigningStrategy; it had been deprecated for years and had been replaced by EXCLUDE_BODY.
• The getPublicKey() and getPrivateKey() methods were removed from com.oracle.bmc.auth.SessionKeySupplier and implementing classes; they had been deprecated for years and had been replaced by the getKeyPair() method.

• The setInstanceMetadataServiceClientConfig method in com.oracle.bmc.Region was removed; it never had any effect.
• AbstractFederationClientAuthenticationDetailsProviderBuilder.simpleRetry method has been removed without replacement, since it is not needed in the OCI Java SDK 3.0.0 and higher.
• You can copy and paste the previous implementation if you need it.
• Starting OCI Java SDK version 3.14.0, class com.oracle.bmc.http.client.Serialization has been removed.

• Guava: Guava types have been replaced with JDK types:
  • com.google.common.base.Optional has been replaced with java.util.Optional
  • com.google.common.base.Function has been replaced with java.util.function.Function
  • com.google.common.base.Predicate has been replaced with java.util.function.Predicate
  • com.google.common.base.Supplier has been replaced with java.util.function.Supplier

Examples for OCI Java SDK 3.x.y can be found bmc-examples/src/main/java.

In order to use Jersey 2 as HTTP client library, a dependency on oci-java-sdk-common-httpclient-jersey needs to be explicitly declared in application's pom.xml. Please refer bmc-jersey-examples/pom.xml

Examples for Jersey 2 as HTTP client library can be found in bmc-other-examples/bmc-jersey-examples

In order to use Jersey 3 as HTTP client library, a dependency on oci-java-sdk-common-httpclient-jersey3 needs to be explicitly declared in application's pom.xml. Please refer bmc-jersey3-examples/pom.xml

Examples for Jersey 3 as HTTP client library can be found in bmc-other-examples/bmc-jersey3-examples

Examples for OCI Legacy Java SDK can be found here.

For details on contributions, questions, or feedback, see Contact Us.

See CHANGELOG.

oci-java-sdk is an open source project. See CONTRIBUTING for details.

Oracle gratefully acknowledges the contributions to oci-java-sdk that have been made by the community.

You can find information on any known issues with the SDK here and under the “Issues” tab of this GitHub repository.

To learn about known issues with OCI Legacy Java SDK, please refer Known Issues in OCI Legacy Java SDK

Details: When using version 1.25.1 or earlier of the OCI Java SDK clients that upload streams of data (for example ObjectStorageClient or FunctionsInvokeClient), either synchronously and asynchronously, and you use a RefreshableOnNotAuthenticatedProvider (for example, for Resource Principals or Instance Principals) you may be affected by silent data corruption.

Workaround: Update the OCI Java SDK client to version 1.25.2 or later. For more information about this issue and workarounds, see Potential data corruption issue for OCI Java SDK on binary data upload with RefreshableOnNotAuthenticatedProvider.

Direct link to this issue: Potential data corruption issue with OCI Java SDK on binary data upload with RefreshableOnNotAuthenticatedProvider

If the request to the server hangs for an indefinite time and the program gets stuck, it could be because the connection is not released from the Apache connection pool. If you're calling APIs that return a binary/stream response, please make sure to close all the streams returned from the response to release the connections from the connection pool in case of partial reads. If reading the stream completely, the SDK will automatically try to close the stream to release the connection from the connection pool, to disable this feature of auto-closing streams on full read, please call Options.shouldAutoCloseResponseInputStream(false). This is because the SDK for Java supports the Apache Connector for sending requests and managing connections to the service. By default, the Apache Connector supports connection pooling and in the cases where the stream from the response is not closed, the connections don't get released from the connection pool and in turn results in an indefinite wait time. This can be avoided either by closing the streams or switching back to the Jersey default connector, i.e. HttpUrlConnector. You can find more information about the same in the OCI Java SDK Troubleshooting section.

The Java SDK supports the Apache Connector as the default. The Apache Connector supports the use of two connection closing strategies - ApacheConnectionClosingStrategy.GracefulClosingStrategy and ApacheConnectionClosingStrategy.ImmediateClosingStrategy. When using ApacheConnectionClosingStrategy.GracefulClosingStrategy, streams returned from response are read till the end of the stream when closing the stream. This can introduce additional time when closing the stream with partial read, depending on how large the remaining stream is. Use ApacheConnectionClosingStrategy.ImmediateClosingStrategy for large files with partial reads instead for faster close. One of the disadvantages of using ApacheConnectionClosingStrategy.ImmediateClosingStrategy on the other hand takes longer when using partial read for smaller stream size (< 1MB). Please consider your use-case and change accordingly. For more info please look into : https://github.com/oracle/oci-java-sdk/blob/master/ApacheConnector-README.md.

Note : If both the above Apache Connection closing strategies do not give you optimal results for your use-cases, please consider switching back to Jersey Default HttpUrlConnectorProvider. For more info on Apache Connector, please look into ApacheConnector-README.

The following error message might be encountered:

java.lang.ClassNotFoundException: com.oracle.bmc.auth.AbstractAuthenticationDetailsProvider

This issue is a result of the listed Java versions, which have a default maximum signature file size smaller than some Java SDK JARs.

To resolve this problem, you can run Maven with the following parameter: -Djdk.jar.maxSignatureFileSize=16000000

The low default value in Java will be addressed and resolved in upcoming minor Java version releases.

When using the Jersey HTTP client, SDK requests are executed through Jersey's async request path. After request execution, idle jersey-client-async-executor-* threads may remain in a waiting state. By default, this behavior is preserved for compatibility.

Customers who want idle core threads in the SDK-managed Jersey async executor to time out can opt in separately for sync and async SDK clients:

ClientConfiguration configuration =
        ClientConfiguration.builder()
                .syncRequestsAsyncCoreThreadTimeoutEnabled(true)
                .asyncRequestsAsyncCoreThreadTimeoutEnabled(true)
                .build();

The same behavior can also be enabled with system properties:

-Doci.javasdk.sync.requests.async.core.thread.timeout.enabled=true
-Doci.javasdk.async.requests.async.core.thread.timeout.enabled=true

Copyright (c) 2016, 2020, 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.

See LICENSE for more details.