Conceitos Básicos

Este tópico descreve como instalar e configurar o Oracle Cloud Infrastructure SDK for Java.

Dica

O SDK para Java é pré-configurado com suas credenciais e está pronto para uso imediato no Cloud Shell. Para obter mais informações sobre como usar o SDK para Java no Cloud Shell, consulte Início Rápido do SDK para Java Cloud Shell.

Instalando com o Gerenciador de Recursos

Você pode usar o Gerenciador de Recursos para instalar o Oracle Cloud Development Kit em uma instância do serviço Compute no seu compartimento. O Oracle Cloud Development Kit inclui o SDK para Java, em conjunto com outras ferramentas de desenvolvimento da Oracle.

Download do SDK no GitHub

No GitHub, você pode fazer o download do SDK para Java como um arquivo zip. O GitHub contém o SDK, todas as suas dependências, documentação e exemplos. Para obter melhor compatibilidade e evitar problemas, use a versão das dependências incluídas no arquivo compactado. Alguns problemas conhecidos são:

Bouncy Castle: Os pacotes do SDK 1.60 (incluídos nesta distribuição). Se precisar de conformidade com FIPS, consulte Usando BC-FIPS em vez de Bouncy Castle.
Jersey Core e Cliente: o SDK inclui a versão 2.24.1, que é necessária para suportar uploads de objetos grandes no serviço Object Storage. As versões mais antigas não suportam uploads maiores que ~2.1 GB.
API Jax-RS: o SDK inclui a versão 2.0.1 da especificação. As versões mais antigas causarão problemas.

Observação

O SDK para Java é empacotado com Jersey (incluído nesta distribuição), mas você também pode usar sua própria implementação do JAX-RS. Para obter detalhes, consulte Usando a Sua Própria Implementação JAX-RS

Download do SDK no Maven ou JCenter

Maven Central e

JCenter.

Instalando com o yum

Se você estiver usando o Oracle Linux 7 ou 8, poderá usar o yum para instalar o OCI SDK para Java.

Para Oracle Linux 7:

sudo yum-config-manager --enable ol7_developer
sudo yum install java-oci-sdk

Para Oracle Linux 8:

sudo yum-config-manager --enable ol8_developer
sudo yum install java-oci-sdk

O arquivo jar do OCI será localizado em: /usr/lib64/java-oci-sdk/lib/oci-java-sdk-full-<version>.jar e as bibliotecas de terceiros estarão em /usr/lib64/java-oci-sdk/third-party/lib.

Você pode adicionar as seguintes entradas ao classpath: /usr/lib64/java-oci-sdk/lib/oci-java-sdk-full-<version>.jar:/usr/lib64/java-oci-sdk/third-party/lib/* Por exemplo:

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

Configurando o SDK

Os serviços SDK precisam de dois tipos de configuração: credenciais e definições HTTP do cliente.

Configurando Credenciais

Primeiro, você precisa configurar as suas credenciais e o arquivo de configuração. Para obter instruções, consulte Arquivo de Configuração da CLI e do SDK.

Em seguida, você precisa configurar o cliente para usar as credenciais. As credenciais são obtidas por meio de uma interface AuthenticationDetailsProvider. No entanto, os clientes poderão implementá-las se você permitir. Incluímos uma classe POJO/builder simples para ajudar com essa tarefa (SimpleAuthenticationDetailsProvider).

Você pode carregar uma configuração com ou sem um perfil:

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

O fornecedor de chave privada pode ser criado com o caminho de arquivo diretamente ou usando o arquivo de configuração:

Supplier<InputStream> privateKeySupplier 
    = new SimplePrivateKeySupplier("~/.oci/oci_api_key.pem");
Supplier<InputStream> privateKeySupplierFromConfigEntry 
    = new SimplePrivateKeySupplier(config.get("key_file"));

Para criar um provedor de autenticação usando o builder:

AuthenticationDetailsProvider provider 
    = SimpleAuthenticationDetailsProvider.builder()
        .tenantId("myTenantId")
        .userId("myUserId")
        .fingerprint("myFingerprint")
        .privateKeySupplier(privateKeySupplier)
        .build();

Para criar um provedor de autenticação usando o builder com um arquivo de configuração:

AuthenticationDetailsProvider provider 
    = SimpleAuthenticationDetailsProvider.builder()
        .tenantId(config.get("tenancy"))
        .userId(config.get("user"))
        .fingerprint(config.get("fingerprint"))
        .privateKeySupplier(privateKeySupplier)
        .build();

Por fim, se você usar as chaves padrão e a localização padrão do arquivo de configuração, poderá simplificar ainda mais o processo usando ConfigFileAuthenticationDetailsProvider:
```
AuthenticationDetailsProvider provider 
    = new ConfigFileAuthenticationDetailsProvider("ADMIN_USER");
```

Configurando Opções do Cliente

Crie uma configuração do cliente por meio da classe ClientConfiguration. Se você não fornecer a sua própria configuração, o SDK para Java usará uma configuração padrão. Para fornecer a sua própria configuração, use o seguinte:

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

Quando tiver tanto uma configuração de credencial quanto a configuração de cliente opcional, você poderá iniciar a criação de instâncias de serviço.

Para obter uma amostra de código que demonstre como configurar e usar timeouts de conexão e leitura na configuração do cliente, consulte o exemplo de Timeout de Configuração do Cliente no GitHub.

Configurando Opções Personalizadas

No arquivo de configuração, você poderá inserir pares de chave e valor personalizados e referenciá-los conforme necessário. Por exemplo, você pode especificar um ID de compartimento usado com frequência no arquivo de configuração:

[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..<unique_ID>


custom_compartment_id=ocid1.compartment.oc1..<unique_ID>

Depois, você poderá recuperar o valor:

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

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

Usando o SDK para Java

Há duas maneiras de usar o SDK do Oracle Cloud Infrastructure para Java em seu projeto.

Importe o oci-java-sdk-bom, seguido pela biblioteca de cliente HTTP e suas dependências de projeto.

A biblioteca de clientes HTTP é configurável e nenhuma biblioteca é escolhida por padrão. No momento, o OCI SDK para Java oferece as seguintes bibliotecas de cliente HTTP para escolha:

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

Você deve escolher explicitamente a biblioteca declarando uma dependência em oci-java-sdk-common-httpclient-jersey ou oci-java-sdk-common-httpclient-jersey3. Por exemplo:

<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>

Adicione a dependência sombreada oci-java-sdk-shaded-full ao seu arquivo pom. Você pode usar a dependência sombreada para incluir todas as classes de terceiros e suas dependências transitivas renomeando-as e incluindo-as em seu projeto. Ela contém um Uber JAR, que é basicamente uma combinação de vários JARs. Todos os pacotes dentro do Uber JAR são renomeados. Isso evitará conflitos entre as dependências do Oracle Cloud Infrastructure SDK e dependências de terceiros que você pode estar usando no seu projeto.

Por exemplo, as classes em org.apache.commons são realocadas para shaded.com.oracle.oci.javasdk.org.apache.commons.

O conteúdo do Uber JAR é o seguinte:
```
shaded/com/oracle/oci/javasdk/org/apache/commons/codec/BinaryDecoder.class
shaded/com/oracle/oci/javasdk/org/apache/commons/logging/LogFactory.class
```
Se você estiver usando o Maven para gerenciar suas dependências, poderá encontrar a dependência sombreada mais recente no repositório do Maven.

Adicione a versão mais recente do oci-java-sdk-shaded-full às suas dependências:
```
<dependency>
  <groupId>com.oracle.oci.sdk</groupId>
  <artifactId>oci-java-sdk-shaded-full</artifactId>
  
  <version>3.0.0</version>
<dependency>
```

Documentação do Oracle Cloud Infrastructure