This topic describes how to install and configure the Oracle Cloud Infrastructure SDK for Java.
This topic describes how to install and configure the Oracle Cloud Infrastructure SDK for Java.
Tip
The SDK for Java is pre-configured with your credentials and ready to use
immediately from within Cloud Shell.
For more information on using the SDK for Java from within Cloud Shell, see SDK for Java Cloud Shell Quick Start.
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:
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
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:
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).
The private key supplier can be created with the file path directly, or using
the config file:
Copy
Supplier<InputStream> privateKeySupplier
= new SimplePrivateKeySupplier("~/.oci/oci_api_key.pem");
Supplier<InputStream> privateKeySupplierFromConfigEntry
= new SimplePrivateKeySupplier(config.get("key_file"));
Finally, if you use standard config file keys and the standard config file
location, you can simplify this further by using
ConfigFileAuthenticationDetailsProvider:
Copy
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:
In the config file, you can insert custom key-value pairs that you define, and then
reference them as necessary. For example, you can specify a frequently used
compartment ID in the config file:
There are two ways to use the Oracle Cloud Infrastructure SDK for Java in your project.
Import the oci-java-sdk-bom, followed by the HTTP client library and your project dependencies.
The HTTP client library is configurable, and no library is chosen by default. The OCI SDK for Java currently offers the following HTTP client libraries to choose from:
You must explicitly choose the library by declaring a dependency on oci-java-sdk-common-httpclient-jersey or oci-java-sdk-common-httpclient-jersey3. For example:
Copy
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.oracle.oci.sdk</groupId>
<artifactId>oci-java-sdk-bom</artifactId>
<!-- replace the version below with your required version -->
<version>3.0.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<!-- Since this is the "application" pom.xml, choose the httpclient to use. -->
<groupId>com.oracle.oci.sdk</groupId>
<artifactId>oci-java-sdk-common-httpclient-jersey</artifactId>
</dependency>
<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 -->
</dependencies>
Add the oci-java-sdk-shaded-full shaded dependency to your pom file. You can use the shaded dependency to include all the third-party classes and its transitive dependencies by renaming and including them in your project. It contains an Uber JAR, which is basically a combination of multiple JARs. All the packages inside the Uber JAR are renamed. This will prevent conflicts between the Oracle Cloud Infrastructure SDK dependencies and third-party dependencies that you might be using in your project.
For example, the classes in org.apache.commons are relocated to
shaded.com.oracle.oci.javasdk.org.apache.commons.
If you're using Maven to manage your dependencies, you can find the latest shaded dependency in the Maven repository.
Add the latest version of oci-java-sdk-shaded-full to your dependencies:
<dependency>
<groupId>com.oracle.oci.sdk</groupId>
<artifactId>oci-java-sdk-shaded-full</artifactId>
<!-- replace the version below with the latest version -->
<version>3.0.0</version>
<dependency>