Updates in Version 3 of the OCI SDK for Java

This topic explains some of the key changes introduced in version 3 of the Oracle Cloud Infrastructure SDK for Java.

Note

See the release notes for full details and refer to the Examples topic for more information.

HTTP Client Libraries

No HTTP client library is configured by default. You must explicitly choose an HTTP client library. The OCI SDK for Java offers the following choices for HTTP client libraries:

Jakarta EE 8/Jersey 2 - bmc-common-httpclient-jersey
Jakarta EE 9/Jersey 3 - bmc-common-httpclient-jersey3

Specify the HTTP client library by declaring a dependency on oci-java-sdk-common-httpclient-jersey or oci-java-sdk-common-httpclient-jersey3. For 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>

Invocation Callbacks

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

Simplified Client Configuration

The customizeClient(HttpClientBuilder builder) method for com.oracle.bmc.http.ClientConfigurator replaced the customizeBuilder, customizeClient, and customizeRequest methods. For example:

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

The properties that can be set depend on the HTTP client you're using. You can also define your own properties. For a comprehensive list of predefined settable properties, refer to the following:

Client Configuration Examples
Configuration	Example
Setting whether to buffer a request	`builder.property( StandardClientProperties.BUFFER_REQUEST, shouldBuffer);`
Setting an Apache connection manager	`builder.property( ApacheClientProperties.CONNECTION_MANAGER, connectionManager);`
Setting a trust store	`// Server CA goes into the trust store KeyStore trustStore = keystoreGenerator.createTrustStoreWithServerCa(tlsConfig.getCaBundle()); builder.property(StandardClientProperties.TRUST_STORE, trustStore);`
Setting a key store	`builder.property( StandardClientProperties.KEY_STORE, new KeyStoreWithPassword(keyStore, keystorePassword));`
Setting the SSL context	`builder.property( StandardClientProperties.SSL_CONTEXT, sslContext);`
Setting a proxy	`builder.property( StandardClientProperties.PROXY, proxyConfig);`
Setting a hostname verifier	`builder.property( StandardClientProperties.HOSTNAME_VERIFIER, NoopHostnameVerifier.INSTANCE);`

The following client configuration examples are also available:

Apache Connector Changes

Several changes were made in order to decouple the Apache Connector implementation from the choice of the HTTP client.

com.oracle.bmc.http.ApacheConfigurator was replaced by com.oracle.bmc.http.client.jersey.ApacheClientProperties or com.oracle.bmc.http.client.jersey3.ApacheClientProperties (for Jersey 3).

The following example is for clients that shouldn't 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, refer to the following example:

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) for more information.

Also consider using com.oracle.bmc.http.client.jersey.apacheconfigurator.ApacheConfigurator from the oci-java-sdk-addons-apache-configurator-jersey add-on module, or com.oracle.bmc.http.client.jersey3.apacheconfigurator.ApacheConfigurator from the oci-java-sdk-addons-apache-configurator-jersey3 add-on module.

See DisableNoConnectionReuseStrategyUsingApacheConfiguratorExample.java and DisableNoConnectionReuseStrategyUsingApacheConfiguratorExample.java (Jersey 3) for more information.

Circuit Breaker Changes

The circuit breaker interface was 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 isn't public anymore.

The com.oracle.bmc.util.CircuitBreakerUtils class doesn't deal with circuit breakers anymore, just with com.oracle.bmc.circuitbreaker.CircuitBreakerConfiguration. Therefore, 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.