Conceitos

Para fazer chamadas síncronas, crie uma instância do cliente síncrono. O padrão geral para clientes síncronos é que para um serviço chamado Example haverá uma interface ExampleService, e a implementação do cliente síncrono será denominada ExampleServiceClient. Este é um exemplo de criação de um cliente do Object Storage:

AuthenticationDetailsProvider provider = ...;
ObjectStorage clientWithDefaultClientConfig = new ObjectStorageClient(provider);
clientWithDefaultClientConfig.setRegion(Region.US_ASHBURN_1);

ClientConfiguration clientConfig = ...;
ObjectStorage clientWithExplicitClientConfig = new ObjectStorageClient(provider, clientConfig);
clientWithExplicitClientConfig.setRegion(Region.US_ASHBURN_1);

As chamadas síncronas serão bloqueadas até que a resposta esteja disponível. Todas as APIs SDK retornam um objeto de resposta (independentemente de a API enviar ou não conteúdo). O objeto de resposta normalmente contém pelo menos um ID de solicitação que você pode usar ao entrar em contato com o suporte da Oracle para obter ajuda sobre uma solicitação específica.

ObjectStorage client = ...;
GetBucketResponse response = client.getBucket(
    GetBucketRequest.builder().namespaceName("myNamespace").bucketName("myBucket").build());
String requestId = response.getOpcRequestId();
Bucket bucket = response.getBucket();
System.out.println(requestId);
System.out.println(bucket.getName());

Para fazer chamadas assíncronas, crie uma instância do cliente assíncrono. O padrão geral para clientes assíncronos é que para um serviço chamado Example haverá uma interface ExampleServiceAsync, e a implementação do cliente assíncrono será denominada ExampleServiceAsyncClient. Este é um exemplo de criação de um cliente do Object Storage:

AuthenticationDetailsProvider provider = ...;
ObjectStorageAsync clientWithDefaultClientConfig = new ObjectStorageAsyncClient(provider);
clientWithDefaultClientConfig.setRegion(Region.US_ASHBURN_1);
 
ClientConfiguration clientConfig = ...;
ObjectStorageAsync clientWithExplicitClientConfig = new ObjectStorageAsyncClient(provider, clientConfig);
clientWithExplicitClientConfig.setRegion(Region.US_ASHBURN_1);

As chamadas assíncronas são retornadas imediatamente. Você precisa fornecer um AsyncHandler que será invocado após a chamada ser concluída com ou sem sucesso:

ObjectStorageAsync client = ...;
 
AsyncHandler<GetBucketRequest, GetBucketResponse> handler = new AsyncHandler<GetBucketRequest, GetBucketResponse>() {
        @Override
        public void onSuccess(GetBucketRequest request, GetBucketResponse response) {
            String requestId = response.getOpcRequestId();
            Bucket bucket = response.getBucket();
            System.out.println(requestId);
            System.out.println(bucket.getName());
        }

        @Override
        public void onError(GetBucketRequest request, Throwable error) {
            error.printStackTrace();
        }
};
 
Future<GetBucketResponse> future = client.getBucket(
        GetBucketRequest.builder().namespaceName("myNamespace").bucketName("myBucket").build(),
        handler);

O SDK oferece waiters que permitem ao seu código aguardar até que um recurso específico atinja um estado desejado. Um waiter pode ser chamado com ou sem bloqueio (utilizando callback assíncrono) e aguarda até que o estado desejado seja atingido ou um timeout seja excedido. Os waiters já incorporam a lógica de sondagem que você teria de criar como uma chamada de método único fácil de usar.

Os waiters são obtidos por meio do cliente de serviço (client.getWaiters()). Get<Resource>Request e o estado do ciclo de vida desejado são especificados para o método waiters.for<Resource>. Por exemplo:

public static Instance waitForInstanceProvisioningToComplete(  ComputeClient computeClient, String instanceId) throws Exception {
        
    ComputeWaiters waiters = computeClient.getWaiters();
    GetInstanceResponse response = waiters.forInstance(
        GetInstanceRequest.builder().instanceId(instanceId).build(),
        Instance.LifecycleState.Running)
    .execute();
        
    return response.getInstance();
}

Cada método waiters.for<Resource> tem duas versões:

• Uma versão usa os valores de sondagem padrão. Por exemplo:

  waiters.forInstance(GetInstanceRequest, LifecycleState)

• A outra versão oferece controle total sobre o tempo de espera e o tempo entre as tentativas de sondagem. Por exemplo:

  waiters.forInstance(GetInstanceRequest, LifecycleState, TerminationStrategy, DelayStrategy)

Um cliente torna-se thread-safe quando é inicializado. Após definir o ponto final, você pode usar com segurança um cliente em vários threads e com vários métodos de chamada concorrente.

Você pode reutilizar um cliente em várias solicitações, em threads concorrentes ou em um único thread. A menos que os recursos do ambiente sejam restritos, você só deverá fechar o cliente imediatamente se ele estiver prestes a sair do escopo.

O serviço Object Storage suporta uploads em várias partes para facilitar a divisão de objetos grandes em partes. O SDK para Java suporta operações de upload em várias partes brutas para casos de uso avançado e aceita uma classe de upload de nível mais alto que usa APIs de upload em várias partes. A seção Usando Uploads em várias partes fornece links para as APIs usadas para operações de upload em várias partes. Os uploads em várias partes de nível mais alto são implementados com o UploadManager, que: dividirá um objeto grande em partes para você, fará o upload das partes em paralelo e recalculará e confirmará as partes como um único objeto no armazenamento.

O exemplo UploadObject mostra como usar o UploadManager para dividir automaticamente um objeto em partes para que o upload simplifique a interação com o serviço Object Storage.

A partir da versão 2.10.0, o SDK para Java é configurado por padrão para repetir determinadas operações do SDK que falham. O SDK permite especificar a estratégia a ser usada de como as repetições são tratadas, incluindo o número de repetições, a condição sob a qual o SDK deve repetir uma operação e quando interromper a repetição de uma operação. Você pode definir esses parâmetros no nível de cliente e no nível de solicitação individual.

Para determinar quais operações de serviço têm repetições ativadas por padrão, consulte a descrição das operações de serviço no SDK.

Por padrão, o SDK repetirá operações com códigos de status de resposta HTTP 409 (com um código de erro IncorrectState), 429, 500, 502, 503, 504, erros de timeout (como timeouts de conexão HTTP e de leitura), erros de conexão de solicitação, exceções de solicitação e exceções de disjuntor.

A configuração de repetição padrão mais atual e a lista de erros que podem ser repetidos podem ser exibidas no Github.

Desativando Repetições Padrão

Para recusar o recurso de repetições padrão, você pode fazer o seguinte:

1. Defina a variável de ambiente OCI_SDK_DEFAULT_RETRY_ENABLED como false para desativar repetições padrão globalmente

2. Substitua as repetições padrão de uma instância cliente específica. Este exemplo mostra como substituir as repetições padrão de objectStorageClient:

   ClientConfiguration clientConfiguration =
           ClientConfiguration.builder()
                   .retryConfiguration(RetryConfiguration.builder().terminationStrategy(new MaxAttemptsTerminationStrategy(1))
                           .build())
                   .build();

   ObjectStorage objectStorageClient = ObjectStorageClient.builder().configuration(clientConfiguration).build(provider);
   

3. Substitua as repetições padrão de uma instância de solicitação específica. Este exemplo mostra como substituir repetições de putObjectRequest:

   PutObjectRequest putObjectRequest =
           PutObjectRequest.builder()
                   .putObjectBody(stream)
                   .bucketName(bucketName)
                   .objectName(objectName)
                   .namespaceName(namespace)
                   .retryConfiguration(RetryConfiguration.builder().terminationStrategy(new MaxAttemptsTerminationStrategy(1)).build())
                   .build();

Repetir Precedência de Comportamento

A partir da versão 2.10.0, o SDK para Java fornece suporte padrão para disjuntores para clientes de serviço que ativaram disjuntores SDK padrão. Os disjuntores ajudam a impedir que o cliente sobrecarregue o serviço, bloqueando as solicitações e impedindo o envio ao serviço após um determinado limite de falha ser atingido.

Para disjuntores padrão, todos os erros que podem ser repetidos serão tratados como falhas para os disjuntores. Para determinar quais clientes de serviço têm disjuntores ativados, consulte a descrição do cliente de serviço no SDK.

Configuração do Disjuntor

Os seguintes parâmetros definem um disjuntor:

Configuração do Disjuntor Padrão

Veja a seguir a configuração do disjuntor padrão:

Desativando o Disjuntor Padrão

Para optar por não utilizar o recurso de disjuntor padrão, você pode executar um dos seguintes procedimentos:

Precedência de Comportamento do Disjuntor

Qualquer configuração de disjuntor definida explicitamente no nível do cliente substituirá a configuração global do disjuntor padrão e a substituição no nível do ambiente desse cliente.

Para obter informações adicionais sobre disjuntores e a configuração do disjuntor padrão, consulte este exemplo no Github.

As solicitações brutas são úteis e, em alguns casos, necessárias. Os casos de uso típicos são: para usar o seu próprio cliente HTTP, fazer uma solicitação autenticada pelo OCI para um ponto final alternativo e fazer uma solicitação para uma API do OCI não suportada atualmente no SDK. O SDK para Java expõe a classe DefaultRequestSigner que você pode usar para criar uma instância RequestSigner para solicitações não padrão.

O exemplo Solicitação Bruta no GitHub mostra como:

• criar um provedor de autenticação e o signatário da solicitação
• integrar-se com um cliente HTTP (Jersey neste exemplo) para autenticar solicitações

Os pontos finais de serviço podem ser definidos de três maneiras.

• Chamar setEndpoint() na instância de serviço. Isso permite especificar um nome de host completo (por exemplo, https://www.example.com).
• Chamar o setRegion() na instância do serviço. Isso seleciona o nome do host apropriado para o serviço na região em questão. No entanto, se o serviço não for suportado na região definida, o SDK para Java retornará um erro.
• Especificar a região no arquivo de configuração. Para obter mais informações, consulte Arquivo de Configuração da CLI e do SDK.

Observe que uma instância de serviço não pode ser usada para comunicação com regiões distintas. Se você precisar fazer solicitações para regiões distintas, crie várias instâncias de serviço.

Se você tiver uma lógica condicional baseada em enumeração, certifique-se de que o seu código seja capaz de lidar com o caso UnknownEnumValue para garantir uma compatibilidade futura. Alguns campos de resposta são do tipo enum. No entanto, no futuro, os serviços individuais podem retornar valores não cobertos pelas enumerações existentes para esse campo. Para abranger essa possibilidade, todos os campos de resposta do tipo enum têm um valor adicional chamado UnknownEnumValue. Se um serviço retornar um valor que não seja reconhecido pela sua versão do SDK, o campo de resposta será definido para esse valor.

Se você estiver usando uma versão do SDK liberada antes do anúncio de uma nova região, poderá usar uma solução alternativa para acessá-la.

Uma região é uma área geográfica localizada. Para obter mais informações sobre regiões e como identificá-las, consulte Regiões e Domínios de Disponibilidade.

Um realm é um conjunto de regiões que compartilham entidades. Você pode identificar o seu realm examinando o nome do domínio no final do endereço da rede. Por exemplo, o realm para xyz.abc.123.oraclecloud.com é oraclecloud.com.

Primeiro, chame Region.register para registrar a nova região e, em seguida, você pode definir a região usando o arquivo de configuração ou chamando o método setRegion.

AuthenticationDetailsProvider provider =
        new ConfigFileAuthenticationDetailsProvider(configurationFilePath, profile);

IdentityClient client = IdentityClient.builder()
        .endpoint("https://identity.ca-toronto-1.oraclecloud.com")
        .build(provider);

InstancePrincipalsAuthenticationDetailsProvider provider = InstancePrincipalsAuthenticationDetailsProvider.builder()
        .federationEndpoint("https://auth.ca-toronto-1.oraclecloud.com/v1/x509")
        .build();

IdentityClient identityClient = IdentityClient.builder()
        .endpoint("https://identity.ca-toronto-1.oraclecloud.com")
        .build(provider);

Algumas APIs retornam conjuntos de resultados paginados; portanto, você deve verificar itens adicionais e, se necessário, extrair a próxima página. Você pode fazer isso manualmente ou usar um iterador.

ObjectStorage client = ...;
 
ListBucketsRequest.Builder builder =
    ListBucketsRequest.builder().namespaceName(namespace);
String nextPageToken = null;
do {
    builder.page(nextPageToken);
    ListBucketsResponse listResponse = client.listBuckets(builder.build());
    List<Bucket> buckets = listResponse.getItems();
    // handle buckets
    nextPageToken = listResponse.getOpcNextPage();
} while (nextPageToken != null);

A Criptografia do Cliente permite criptografar dados no cliente antes de armazená-los localmente ou usá-los com outros serviços do Oracle Cloud Infrastructure.

Para usar a criptografia do cliente, é necessário criar uma chave de criptografia mestra (MEK) usando o Serviço Key Management. Isso pode ser feito usando as operações CreateKey ou ImportKey.

A MEK é usada para gerar uma Chave de Criptografia de Dados (DEK) para criptografar cada payload. Uma cópia criptografada dessa DEK (criptografada na MEK) e outras partes de metadados são incluídas no payload criptografado retornado pelos SDKs para que possam ser usadas para decriptografia.

// String encryption example
			
final byte[] plainText = "Hello World".getBytes();
String masterKeyId = "OCID....";
Map<String, String> context = Collections.singletonMap("Example", "value");
 
OciCrypto ociCrypto = new OciCrypto();
KmsMasterKey kmsMasterKey = new KmsMasterKey(authenticationProvider, Region.US_ASHBURN_1.getRegionId(), vaultId, masterKeyId);
KmsMasterKeyProvider kmsMasterKeyProvider = new KmsMasterKeyProvider(kmsMasterKey);
 
//  Encrypt the data and embed the master key ID in the header
final OciCryptoResult encryptResult = ociCrypto.encryptData(kmsMasterKeyProvider, plainText, context);
final byte[] cipherText = encryptResult.getResult();
 
//  Decrypt the data
final OciCryptoResult decryptResult = ociCrypto.decryptData(kmsMasterKeyProvider, cipherText);

// Create Encryption file stream
FileInputStream in = new FileInputStream(srcFile);
OciCrypto ociCrypto = new OciCrypto();
KmsMasterKey kmsMasterKey = new KmsMasterKey(authenticationProvider, Region.US_ASHBURN_1.getRegionId(), vaultId, masterKeyId);
KmsMasterKeyProvider kmsMasterKeyProvider = new KmsMasterKeyProvider(kmsMasterKey);
OciCryptoInputStream encryptingStream = ociCrypto.createEncryptingStream(kmsMasterKeyProvider, in);
 
// Write the encrypted data to file
FileOutputStream out = new FileOutputStream(srcFile + ".encrypted");
IOUtils.copy(encryptingStream, out);
encryptingStream.close();
out.close();
 
// For decryption, no need to pass key info
KmsMasterKeyProvider kmsMasterKeyProvider = new KmsMasterKeyProvider(authenticationProvider);
// Create the Decryption file stream.
in = new FileInputStream(srcFile + ".encrypted");
OciCryptoInputStream decryptingStream = ociCrypto.createDecryptingStream(kmsMasterKeyProvider, in);
 
 
// Return the plaintext data
out = new FileOutputStream(srcFile + ".decrypted");
IOUtils.copy(decryptingStream, out);
decryptingStream.close();
out.close();

Ao tratar uma exceção, você pode obter mais informações sobre a solicitação HTTP que a causou, como o código de status ou o timeout. Você também pode obter o ID da solicitação ao tratar uma BmcException usando o método getOpcRequestId.

Este exemplo mostra um bloco try-catch que trata uma BmcExceptione imprime o ID da solicitação.

ObjectStorage client = ...;
try {
    GetBucketResponse response = client.getBucket(
	        GetBucketRequest.builder().namespaceName("myNamespace").bucketName("myBucket").build());
    String requestId = response.getOpcRequestId();
    System.out.println(requestId);
} catch (BmcException e) {
    String requestId = e.getOpcRequestId();
    System.out.println(requestId);
    e.printStackTrace();
}

As exceções no SDK para Java são exceções de runtime (não são verificadas). Portanto, elas não são mostradas nas assinaturas de método. Todas as APIs podem gerar uma BmcException.