Concepts

Pour effectuer des appels synchrones, créez une instance du client synchrone. Le modèle général relatif aux clients synchrones est le suivant : pour un service nommé Example, il existe une interface nommée ExampleService et l'implémentation du client synchrone est nommée ExampleServiceClient. Voici un exemple de création d'un client 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);

Les appels synchrones sont bloqués jusqu'à ce que la réponse soit disponible. Toutes les API de kit SDK renvoient un objet de réponse (que l'API renvoie du contenu ou non). L'objet de réponse contient généralement au moins un ID de demande que vous pouvez utiliser lorsque vous contactez le support technique Oracle en vue d'obtenir de l'aide sur une demande précise.

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());

Pour effectuer des appels asynchrones, créez une instance du client asynchrone. Le modèle général relatif aux clients asynchrones est le suivant : pour un service nommé Example, il existe une interface nommée ExampleServiceAsync et l'implémentation du client asynchrone est nommée ExampleServiceAsyncClient. Voici un exemple de création d'un client 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);

Les appels asynchrones sont renvoyés immédiatement. Vous devez fournir un AsyncHandler qui sera appelé une fois que l'appel sera terminé, avec ou sans succès :

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

Le kit SDK inclut des processus en attente permettant au code d'attendre jusqu'à ce qu'une ressource spécifique atteigne un état souhaité. Un processus en attente peut être appelé de façon bloquante ou non bloquante (avec callback asynchrone) et attend que l'état souhaité soit atteint ou que le délai d'expiration soit dépassé. Les processus en attente extraient la logique d'interrogation, que vous devriez sinon écrire, dans un appel de méthode unique facile à utiliser.

Les processus en attente sont obtenus via le client de service (client.getWaiters()). A la fois Get<Resource>Request et l'état de cycle de vie souhaité sont transmis à la méthode waiters.for<Resource>. Par exemple :

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();
}

Chaque méthode waiters.for<Resource> a deux versions :

• Une version utilise les valeurs d'interrogation par défaut. Par exemple :

  waiters.forInstance(GetInstanceRequest, LifecycleState)

• L'autre version offre un contrôle total sur la durée d'attente et sur l'intervalle de temps entre les tentatives d'interrogation. Par exemple :

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

Les threads d'un client sont sécurisés lorsque celui-ci est initialisé. Une fois son adresse définie, vous pouvez utiliser un client en toute sécurité dans plusieurs threads et appeler des méthodes simultanément sur celui-ci.

Vous pouvez réutiliser un client dans plusieurs demandes, sur des threads simultanés ou dans un même thread. A moins que les ressources de l'environnement ne soient limitées, vous devez fermer le client juste avant qu'il ne soit hors de portée.

Le service Object Storage prend en charge les téléchargements multipart pour simplifier les téléchargements d'objets volumineux en les divisant en plusieurs parties. Le kit SDK pour Java prend en charge les opérations de téléchargement multipart brutes pour les cas d'emploi avancés, ainsi qu'une classe de téléchargement de niveau supérieur utilisant les API de téléchargement multipart. La rubrique relative à l'utilisation des téléchargements multipart fournit des liens vers les API utilisées pour les opérations de téléchargement multipart. Les téléchargements multipart de niveau supérieur sont implémentés à l'aide d'UploadManager, qui fractionne un objet volumineux en plusieurs parties, télécharge les parties en parallèle, puis recombine et valide les parties en un seul objet dans le stockage.

L'exemple UploadObject montre comment utiliser UploadManager pour fractionner automatiquement un objet en plusieurs parties à télécharger afin de simplifier l'interaction avec le service Object Storage.

A partir de la version 2.10.0, le kit SDK pour Java est configuré par défaut pour réessayer certaines de ses opérations en échec. Le kit SDK vous permet de spécifier la stratégie à utiliser pour la gestion des tentatives, y compris le nombre de tentatives, la condition dans laquelle le kit SDK doit retenter une opération et le moment auquel arrêter les tentatives. Vous pouvez définir ces paramètres au niveau du client et au niveau de la demande individuelle.

Afin de déterminer les opérations de service pour lesquelles les nouvelles tentatives sont activées par défaut, reportez-vous à la description des opérations de service dans le kit SDK.

Par défaut, le kit SDK tente à nouveau les opérations sur les codes de statut de réponse HTTP 409 (avec code d'erreur IncorrectState), 429, 500, 502, 503, 504, les erreurs de délai d'expiration (comme les délais d'expiration de connexion HTTP et de lecture), les erreurs de connexion de demande, les exceptions de demande et les exceptions de disjoncteur.

La configuration par défaut la plus récente concernant les nouvelles tentatives et la liste des erreurs pouvant faire l'objet d'une nouvelle tentative sont consultables sur GitHub.

Désactivation des nouvelles tentatives par défaut

Pour renoncer à la fonctionnalité des nouvelles tentatives par défaut, vous pouvez effectuer l'une des opérations suivantes :

1. Définissez la variable d'environnement OCI_SDK_DEFAULT_RETRY_ENABLED sur false pour désactiver globalement les nouvelles tentatives par défaut.

2. Remplacez les nouvelles tentatives par défaut pour une instance client particulière. Cet exemple présente le remplacement des nouvelles tentatives par défaut pour objectStorageClient :

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

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

3. Remplacez les nouvelles tentatives par défaut pour une instance de demande particulière. Cet exemple présente le remplacement des nouvelles tentatives pour putObjectRequest :

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

Priorité sur le comportement lié aux nouvelles tentatives

A partir de la version 2.10.0, le kit SDK pour Java prend en charge par défaut les disjoncteurs pour les clients de service qui ont activé les disjoncteurs de kit SDK par défaut. Les disjoncteurs empêchent le client de submerger le service en bloquant l'envoi des demandes au service une fois qu'un certain seuil d'échec est atteint.

Pour les disjoncteurs par défaut, toutes les erreurs pouvant faire l'objet d'une nouvelle tentative sont traitées comme des échecs. Afin de déterminer les clients de service pour lesquels les disjoncteurs sont activés, reportez-vous à la description des clients de service dans le kit SDK.

Configuration de disjoncteur

Les paramètres suivants définissent un disjoncteur :

Configuration de disjoncteur par défaut

Voici la configuration de disjoncteur par défaut :

Désactivation du disjoncteur par défaut

Pour renoncer à la fonctionnalité du disjoncteur par défaut, vous pouvez effectuer l'une des opérations suivantes :

Priorité sur le comportement lié aux disjoncteurs

Toute configuration de disjoncteur définie explicitement au niveau du client remplace la configuration globale de disjoncteur par défaut et le remplacement au niveau de l'environnement pour ce client.

Pour plus d'informations sur les disjoncteurs et sur la configuration de disjoncteur par défaut, reportez-vous à cet exemple sur GitHub.

Les demandes brutes sont utiles, et dans certains cas, nécessaires. Les cas d'emploi standard sont les suivants : lorsque vous utilisez votre propre client HTTP, lorsque vous effectuez une demande authentifiée par OCI à une autre adresse et lorsque vous effectuez une demande à une API OCI qui n'est pas prise en charge actuellement dans le kit SDK. Le kit SDK pour Java affiche la classe DefaultRequestSigner que vous pouvez utiliser afin de créer une instance RequestSigner pour les demandes non standard.

L'exemple de demande brute sur GitHub indique comment :

• créer un fournisseur d'authentification et un signataire de demande,
• effectuer l'intégration à un client HTTP (Jersey dans cet exemple) pour authentifier les demandes.

Les adresses de service peuvent être définies de trois façons.

• Appel de setEndpoint() sur l'instance de service. Vous pouvez ainsi spécifier un nom d'hôte complet (par exemple, https://www.example.com).
• Appel de setRegion() sur l'instance de service. Cette opération sélectionne le nom d'hôte approprié pour le service de la région donnée. Toutefois, si le service n'est pas pris en charge dans la région définie, le kit SDK pour Java renvoie une erreur.
• Transmission de la région dans le fichier de configuration. Pour plus d'informations, reportez-vous à Fichier de configuration du kit SDK et de l'interface de ligne de commande.

Une instance de service ne peut pas être utilisée pour communiquer avec différentes régions. Si vous devez effectuer des demandes dans différentes régions, créez plusieurs instances de service.

Si vous avez une logique conditionnelle basée sur une énumération, assurez-vous que le code gère le cas UnknownEnumValue pour garantir la compatibilité descendante. Certains champs de réponse sont de type énumération mais, à l'avenir, les services individuels pourront renvoyer des valeurs non couvertes par les énumérations existantes pour ce champ. Pour répondre à cette possibilité, chaque champ de réponse de type énumération a une valeur supplémentaire nommée UnknownEnumValue. Lorsqu'un service renvoie une valeur non reconnue par votre version du kit SDK, le champ de réponse est défini sur cette valeur.

Si vous utilisez une version du kit SDK publiée avant l'annonce d'une nouvelle région, vous pouvez utiliser une solution de contournement pour l'atteindre.

Une région est une zone géographique localisée. Pour plus d'informations sur les régions et leur identification, reportez-vous à Régions et domaines de disponibilité.

Un domaine est un ensemble de régions qui partagent des entités. Vous pouvez identifier votre domaine en observant le nom de domaine à la fin de l'adresse réseau. Par exemple, le domaine de xyz.abc.123.oraclecloud.com est oraclecloud.com.

Vous devez tout d'abord appeler Region.register pour inscrire la nouvelle région, puis définir la région à l'aide du fichier de configuration ou en appelant la méthode 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);

Certaines API renvoient des ensembles de résultats paginés. Vous devez donc rechercher si des éléments supplémentaires existent et, si nécessaire, extraire la page suivante. Vous pouvez procéder manuellement ou utiliser un itérateur.

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

Le cryptage côté client vous permet de crypter les données côté client avant de les stocker en local ou de les utiliser avec d'autres services Oracle Cloud Infrastructure.

Pour utiliser le cryptage côté client, vous devez créer une clé de cryptage maître (MEK) à l'aide du service Key Management. Pour ce faire, vous pouvez utiliser l'opération CreateKey ou ImportKey.

La clé MEK permet de générer une clé de cryptage de données (DEK) utilisée pour crypter chaque charge utile. Une copie cryptée de cette clé DEK (sous la clé MEK) et d'autres métadonnées sont incluses dans la charge utile cryptée renvoyée par les kits SDK en vue d'être utilisées pour le décryptage.

// 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();

Lors de la gestion d'une exception, vous pouvez obtenir plus d'informations sur la demande HTTP qui l'a générée, comme le code de statut ou le délai d'expiration. Vous pouvez également obtenir l'ID de la demande lors de la gestion d'une exception BmcException à l'aide de la méthode getOpcRequestId.

Cet exemple présente un bloc try-catch qui gère une exception BmcException et imprime l'ID de la demande.

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();
}

Les exceptions dans le kit SDK pour Java sont des exceptions d'exécution (non vérifiées). Elles n'apparaissent donc pas dans les signatures de méthode. Toutes les API peuvent générer une exception BmcException.