Getting Started

This topic describes how to install and configure the Oracle Cloud Infrastructure SDK for Java.

To use the Oracle Cloud Infrastructure SDK for Java in your project, import the oci-java-sdk-bom, followed by your project dependencies. For example:

 <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>com.oracle.oci.sdk</groupId>
        <artifactId>oci-java-sdk-bom</artifactId>
        <!-- replace the version below with your required version -->
        <version>1.5.2</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
  <dependencies>
  <dependency>
    <groupId>com.oracle.oci.sdk</groupId>
    <artifactId>oci-java-sdk-audit</artifactId>
  </dependency>
  <dependency>
    <groupId>com.oracle.oci.sdk</groupId>
    <artifactId>oci-java-sdk-core</artifactId>
  </dependency>
  <dependency>
    <groupId>com.oracle.oci.sdk</groupId>
    <artifactId>oci-java-sdk-database</artifactId>
  </dependency>
  <!-- more dependencies if needed -->

Downloading the SDK from GitHub

You can download the SDK for Java as a zip archive from GitHub. It contains the SDK, all of its dependencies, documentation, and examples. For best compatibility and to avoid issues, use the version of the dependencies included in the archive. Some notable issues are:

  • Bouncy Castle: The SDK bundles 1.60 (included in this distribution). If you need FIPS compliance, see Using BC-FIPS Instead of Bouncy Castle.
  • Jersey Core and Client: The SDK bundles 2.24.1, which is required to support large object uploads to Object Storage. Older versions will not support uploads greater than ~2.1 GB.
  • Jax-RS API: The SDK bundles 2.0.1 of the spec. Older versions will cause issues.
Note

The SDK for Java is bundled with Jersey (included in this distribution), but you can also use your own JAX-RS implementation. For details, see Using Your Own JAX-RS Implementation

Installing with yum

If you're using Oracle Linux 7, you can use yum to install the OCI SDK for Java:

sudo yum install java-oci-sdk.x86_64

The OCI jar file will be located in:/usr/lib64/java-oci-sdk/lib/oci-java-sdk-full-<version>.jar, and third-party libraries will be in /usr/lib64/java-oci-sdk/third-party/lib.

You can add the following entries to your classpath:

/usr/lib64/java-oci-sdk/lib/oci-java-sdk-full-<version>.jar:/usr/lib64/java-oci-sdk/third-party/lib/*

For example:
javac -cp "/usr/lib64/java-oci-sdk/third-party/lib/*:/usr/lib64/java-oci-sdk/lib/oci-java-sdk-full-1.8.2.jar" MyFile.java

Configuring the SDK

The SDK services need two types of configuration: credentials and client-side HTTP settings.

Configuring Credentials

First, you need to set up your credentials and config file. For instructions, see SDK and CLI Configuration File.

Next you need to set up the client to use the credentials. The credentials are abstracted through an AuthenticationDetailsProvider interface. Clients can implement this however you choose. We have included a simple POJO/builder class to help with this task (SimpleAuthenticationDetailsProvider).

  • You can load a config with or without a profile:

    ConfigFile config 
        = ConfigFileReader.parse("~/.oci/config");
    ConfigFile configWithProfile 
        = ConfigFileReader.parse("~/.oci/config", "DEFAULT");
  • The private key supplier can be created with the file path directly, or using the config file:

    Supplier<InputStream> privateKeySupplier 
        = new SimplePrivateKeySupplier("~/.oci/oci_api_key.pem");
    Supplier<InputStream> privateKeySupplierFromConfigEntry 
        = new SimplePrivateKeySupplier(config.get("key_file"));
  • To create an auth provider using the builder:

    AuthenticationDetailsProvider provider 
        = SimpleAuthenticationDetailsProvider.builder()
            .tenantId("myTenantId")
            .userId("myUserId")
            .fingerprint("myFingerprint")
            .privateKeySupplier(privateKeySupplier)
            .build();
  • To create an auth provider using the builder with a config file:

    AuthenticationDetailsProvider provider 
        = SimpleAuthenticationDetailsProvider.builder()
            .tenantId(config.get("tenancy"))
            .userId(config.get("user"))
            .fingerprint(config.get("fingerprint"))
            .privateKeySupplier(privateKeySupplier)
            .build();
  • Finally, if you use standard config file keys and the standard config file location, you can simplify this further by using ConfigFileAuthenticationDetailsProvider:

    AuthenticationDetailsProvider provider 
        = new ConfigFileAuthenticationDetailsProvider("ADMIN_USER");

Configuring Client-side Options

Create a client-side configuration through the ClientConfiguration class. If you do not provide your own configuration, the SDK for Java uses a default configuration. To provide your own configuration, use the following:

ClientConfiguration clientConfig 
    = ClientConfiguration.builder()
        .connectionTimeoutMillis(3000)
        .readTimeoutMillis(60000)
        .build();

After you have both a credential configuration and the optional client configuration, you can start creating service instances.

Configuring Custom Options

In the config file, you can insert custom key-value pairs that you define, and then reference them as necessary. For example, you could specify a frequently used compartment ID in the config file like so (highlighted in red italics):

[DEFAULT]
user=ocid1.user.oc1..aaaaaaaat5nvwcna5j6aqzjcmdy5eqbb6qt2jvpkanghtgdaqedqw3rynjq
fingerprint=20:3b:97:13:55:1c:5b:0d:d3:37:d8:50:4e:c5:3a:34
key_file=~/.oci/oci_api_key.pem
tenancy=ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f15p2bcmdyt2j6rx32uzr4h25vqstifsfdsq


custom_compartment_id=ocid1.compartment.oc1..aaaaaaaayzfqeibduyox6iib3olcmdar3ugly4fmameq4h7lcdlihrvur7xq



Then you can retrieve the value like so:

ConfigFile config 
    = ConfigFileReader.parse("~/.oci/config");

String compartmentId = config.get("custom_compartment_id");