DOCSEARCHbyAlgolia
Submit Docs

Oracle Cloud Infrastructure (OCI) Java SDK

repository·master·Indexed 42 days ago

https://github.com/oracle/oci-java-sdk

An open-source Java SDK for programmatically managing Oracle Cloud Infrastructure (OCI) resources. Includes support for Jersey and RestEasy client configurators, GraalVM native image compilation, and Maven enforcer rules to prevent mixing SDK versions.

Tokens
21.5K
Snippets
58
Records
92
Agent score
53%

What's inside OCI Java SDK

  1. Use the Apache Connector for OCI Java SDK

    master
    The oci-java-sdk-addons-apache module is discontinued. The Apache Connector functionality has been integrated into the core SDK. To use the Apache Connector for making service calls, you should now use the classes provided in the oci-java-sdk-common package. The SDK now supports the Jersey ApacheConnectorProvider by default instead of the Jersey default HttpUrlConnectorProvider.

  2. Configure Circuit Breakers in OCI Java SDK v3

    master

    The circuit breaker implementation has changed in v3:

    1. Renamed Interface: com.oracle.bmc.circuitbreaker.JaxRsCircuitBreaker is now com.oracle.bmc.circuitbreaker.OciCircuitBreaker.
    2. Builder Pattern: Use the builder for com.oracle.bmc.circuitbreaker.CircuitBreakerConfiguration instead of the constructor, as the constructor is no longer public.
    3. Factory Usage: To create a new circuit breaker from default configurations, use the build methods in com.oracle.bmc.circuitbreaker.CircuitBreakerFactory.

  3. Supported encryption algorithms in the Pem package

    master

    The package relies exclusively on base JDK libraries and does not use external providers like Bouncy Castle. Supported encryption details include:

    • PKCS1: Supports RSA public and private keys only. Supports AES encryption (128, 192, or 256 bit) for encrypted PKCS1 private keys. It also supports an MD5-based bespoke PBE algorithm; however, because MD5 is not FIPS compliant, encrypted PKCS1 private keys must not be used in FIPS compliant environments.
    • PKCS8 & X509: Supports multiple asymmetric encryption algorithms, but only RSA encryption has been verified via the oci-java-sdk test suites.

  4. Use RequestInterceptor for invocation callbacks

    master
    To decouple your implementation from the specific HTTP client being used, do not use the internal Consumer<Invocation.Builder>. Instead, use com.oracle.bmc.http.client.RequestInterceptor to register invocation callbacks.

  5. Prevent memory exhaustion when uploading large objects

    master

    The ApacheConfigurator buffers requests into memory by default, which can cause OutOfMemoryError when uploading large objects (e.g., via ObjectStorageClient.putObject()).

    To prevent buffering, use ApacheConfigurator.NonBuffering and ensure you provide the contentLength when creating the request. For ObjectStorageClient, ApacheConfigurator.NonBuffering is the default, but if you override the clientConfigurator, it may default back to the Jersey Default Connector.

    Warning: Do not wrap streams in a BufferedInputStream if the object size exceeds 2.14 GB, as the maximum buffer size is Integer.MAX_VALUE - 8. Doing so can lead to Connection pool shutdown or Out of memory errors.

    // Example: Providing contentLength to prevent buffering in ObjectStorage
PutObjectRequest request = PutObjectRequest.builder()
    .bucketName("my-bucket")
    .objectName("large-file")
    .contentLength(contentLength) // Crucial for non-buffering
    .putObjectBody(inputStream)
    .build();

  6. Run Jersey 3 examples using Maven exec:java

    master

    You can run specific examples by invoking the exec:java goal. You must provide the exec.mainClass property (the name of the example class) and the exec.args property (the command-line arguments required by that specific example).

    For example, to run the ObjectStorageGetBucketExample class, which requires three arguments—the compartment OCID, the bucket name, and the object name—use the following command:

    mvn -am -pl bmc-other-examples/bmc-jersey3-examples exec:java \
  -Dexec.mainClass=ObjectStorageGetBucketExample \
  -Dexec.args="compartment_ocid bucket_name object_name"

    To perform a clean build and run the example in a single step, use:

    mvn clean compile -am -pl bmc-other-examples/bmc-jersey3-examples exec:java \
  -Dexec.mainClass=ObjectStorageGetBucketExample \
  -Dexec.args="compartment_ocid bucket_name object_name"

    Note: Replace compartment_ocid, bucket_name, and object_name with your actual OCI resource values.

  7. Compile and run a Jersey example in one command

    master

    To ensure the environment is clean and all dependencies are compiled before execution, you can combine the clean, compile, and exec:java goals in a single command:

    mvn clean compile -am -pl bmc-other-examples/bmc-jersey-examples exec:java \
  -Dexec.mainClass=ObjectStorageGetBucketExample \
  -Dexec.args="compartment_ocid bucket_name object_name"

    Note: Replace compartment_ocid, bucket_name, and object_name with your actual OCI resource values.

  8. Install oci-java-sdk-enforcer-rules manually

    master

    If your environment does not have access to Maven Central, you must manually install the oci-java-sdk-enforcer-rules package into your local Maven repository.

    Use the mvn install:install-file command. Note that you must adjust the -Dfile and -DpomFile paths and the version number (e.g., 2.46.0) to match the specific version and file location provided in your OCI Java SDK distribution ZIP file.

    mvn install:install-file -Dfile=buildTools/oci-java-sdk-enforcer-rules/lib/oci-java-sdk-enforcer-rules-2.46.0.jar -DpomFile=buildTools/oci-java-sdk-enforcer-rules/lib/oci-java-sdk-enforcer-rules-2.46.0.pom

  9. Handle sensitive private key data securely

    master

    When working with PEM resources, follow these security guidelines:

    1. Public Keys and Certificates: Since these do not contain sensitive data, it is appropriate to use String-based APIs for reading and writing.
    2. Private Keys: Never use String-based APIs for private keys. Because String objects are immutable, sensitive data cannot be erased from memory after use.
    3. Memory Management: All private key APIs use byte[] for inputs and outputs. You must manually erase all byte[] instances after use.
    4. Best Practice: To avoid materializing private key data into visible buffers in memory, use the ReadableByteChannel and WritableByteChannel APIs provided by the Pem package.

  10. Run the OCI Java SDK Streaming example

    master

    This example demonstrates using the SDK with the Streaming service using the Jersey HTTP client implementation. To run it, you must configure the ociJavaSdk property in build.gradle and provide a compartment OCID.

    Prerequisites

    If you are running from the root directory and need to install local dependencies first:

    mvn install -pl bmc-streaming,bmc-common-httpclient-choices/bmc-common-httpclient-jersey -am -DskipTests

    If you performed the step above, ensure mavenLocal() is added as a repository in your build.gradle.

    Execution

    Set your compartment OCID as an environment variable and execute via Gradle:

    export COMPARTMENT_OCID="..."
./gradlew run --args=$COMPARTMENT_OCID

  11. Build the SDK using Maven profiles

    master

    The OCI Java SDK uses Maven profiles to control the build process. You can choose different profiles depending on whether you want to perform a full build, a quick compilation check, or a development-oriented build that includes code reformatting and license updates.

    Available profiles:

    • default: Compiles the code and generates Javadoc.
    • dev: Compiles, reformats code, and updates licenses.
    • dev with -Ddev.profile.skip.javadoc=false: Compiles, reformats code, updates licenses, and generates Javadoc.
    • quick: Performs a fast check for compilation errors only (skips Javadoc and tests).
    • jdk-17-and-above: Automatically activated when JDK 17+ is detected. It skips Javadoc generation and expects test failures to be ignored.
    # Run a build with the dev profile and generate Javadoc
mvn install -Pdev -Ddev.profile.skip.javadoc=false

  12. Configure Native Image build for GraalVM Java8

    master

    If you are using an older GraalVM Java8 distribution, you must apply specific configuration changes to the native-maven-plugin to ensure a successful build.

    Required Changes:

    1. Downgrade native-maven-plugin.version to 0.9.25 or earlier.
    2. Add the following <buildArgs> to the plugin configuration in your pom.xml:
    <plugin>
  <groupId>org.graalvm.buildtools</groupId>
  <artifactId>native-maven-plugin</artifactId>
  <version>0.9.25</version> <!-- or prior -->
  <configuration>
    <buildArgs>
      <buildArg>--allow-incomplete-classpath</buildArg>
      <buildArg>--report-unsupported-elements-at-runtime</buildArg>
    </buildArgs>
  </configuration>
</plugin>
    <plugin>
  <groupId>org.graalvm.buildtools</groupId>
  <artifactId>native-maven-plugin</artifactId>
  <configuration>
    <buildArgs>
      <buildArg>--allow-incomplete-classpath</buildArg>
      <buildArg>--report-unsupported-elements-at-runtime</buildArg>
    </buildArgs>
  </configuration>
</plugin>