Concepts

Pour effectuer des appels synchrones, créez une instance du client synchrone. Selon le modèle général pour les clients synchrones : pour un service nommé Example, il y aura une interface nommée ExampleService et la mise en oeuvre du client synchrone sera appelée ExampleServiceClient. Voici un exemple de création d'un client de stockage d'objets :

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 trousse SDK retournent 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 demande que vous pouvez utiliser lors de la communication avec le soutien technique d'Oracle pour obtenir de l'aide sur une demande particulière.

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. Selon le modèle général pour les clients asynchrones : pour un service nommé Example, il y aura une interface nommée ExampleServiceAsync et la mise en oeuvre du client asynchrone sera appelée ExampleServiceAsyncClient. Voici un exemple de création d'un client de stockage d'objets :

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 retournés immédiatement. Vous devez fournir un AsyncHandler qui sera appelé une fois l'appel réussi ou en échec :

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

La trousse SDK offre des processus d'attente qui permettent à votre code d'attendre qu'une ressource spécifique atteigne l'état souhaité. Un processus en attente peut être appelé à la fois de manière bloquante ou non bloquante (avec rappel asynchrone), et attendra jusqu'à ce que l'état souhaité soit atteint ou qu'une temporisation soit dépassée. Les processus en attente convertissent la logique de scrutation (que vous auriez à écrire autrement) en un appel de méthode unique facile à utiliser.

Les processus en attente sont obtenus au moyen du client du service (client.getWaiters()). Les deux états Get<Resource>Request et celui du cycle de vie désiré 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> comporte deux versions :

• Une version utilise les valeurs de scrutation par défaut. Par exemple :

  waiters.forInstance(GetInstanceRequest, LifecycleState)

• L'autre version vous donne un contrôle total sur la durée d'attente et la durée entre les tentatives de scrutation. Par exemple :

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

Le client prend l'état thread-safe lorsqu'il est initialisé. Après avoir défini son point d'extrémité, vous pouvez utiliser en toute sécurité un client dans plusieurs fils et méthodes d'appel simultanément.

Vous pouvez réutiliser un client dans plusieurs demandes, tant dans des fils simultanés que dans un seul fil. À moins que les ressources de l'environnement ne soient restreintes, vous devez seulement fermer le client juste avant qu'il ne soit hors de portée.

Le service de stockage d'objets prend en charge les chargements en plusieurs parties pour faciliter les chargements d'objets volumineux en fractionnant l'objet volumineux en parties. La trousse SDK pour Java prend en charge les opérations de chargement en plusieurs parties brutes pour des cas d'utilisation avancés, ainsi qu'une classe de chargement de niveau supérieur utilisant les API de chargement en plusieurs parties. L'utilisation de chargements en plusieurs parties fournit des liens aux API utilisées pour les opérations de chargement en plusieurs parties. Les chargements en plusieurs parties de niveau supérieur sont mis en oeuvre à l'aide d'UploadManager qui fractionne un objet volumineux en plusieurs parties pour vous, 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 afin de simplifier les interactions avec le service de stockage d'objets.

À partir de la version 2.10.0, la trousse SDK pour Java est configurée par défaut pour retenter certaines opérations de trousse SDK qui échouent. La trousse SDK vous permet de spécifier la stratégie à utiliser pour le mode de traitement des nouvelles tentatives, notamment le nombre de nouvelles tentatives, la condition selon laquelle la trousse SDK doit retenter une opération et le moment auquel arrêter les nouvelles tentatives. Vous pouvez définir ces paramètres au niveau du client et au niveau de la demande individuelle.

Pour savoir pour quelles opérations de service les nouvelles tentatives sont activées par défaut, consultez la description des opérations de service de la trousse SDK.

Par défaut, la trousse SDK retente les opérations avec les codes de statut de réponse HTTP 409 (avec un code d'erreur IncorrectState), 429, 500, 502, 503, 504, les erreurs de temporisation (temporisations de connexion HTTP et de lecture, par exemple), les erreurs de connexion de demande, les exceptions de demande et les exceptions de disjoncteur.

La configuration par défaut la plus courante et la liste des erreurs qui peuvent faire l'objet de nouvelles tentatives sont visibles dans Github.

Désactivation des nouvelles tentatives par défaut

Pour désactiver la fonction de nouvelles tentatives par défaut, vous pouvez effectuer l'une des opérations suivantes :

1. Réglez la variable d'environnement OCI_SDK_DEFAULT_RETRY_ENABLED à false pour désactiver les nouvelles tentatives par défaut globalement.

2. Remplacez les nouvelles tentatives par défaut pour une instance client spécifique. Cet exemple montre comment remplacer les 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 spécifique. Cet exemple illustre 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é du comportement des nouvelles tentatives

À partir de la version 2.10.0, la trousse SDK pour Java fournit la prise en charge par défaut des disjoncteurs pour les clients de service pour lesquels les disjoncteurs de trousse SDK par défaut sont activés. Les disjoncteurs permettent d'éviter que le client submerge le service en bloquant l'envoi des demandes à celui-ci après qu'un certain seuil d'échec a été atteint.

Pour les disjoncteurs par défaut, toutes les erreurs pour lesquelles une nouvelle tentative est possible sont traitées comme des défaillances. Pour identifier les clients de service pour lesquels les disjoncteurs sont activés, consultez la description des clients dans la trousse SDK.

Configuration du disjoncteur

Les paramètres suivants définissent un disjoncteur :

Configuration des disjoncteurs par défaut

La configuration des disjoncteurs par défaut est la suivante :

Désactivation du disjoncteur par défaut

Pour désactiver la fonction de disjoncteur par défaut, vous pouvez effectuer l'une des opérations suivantes :

Priorité du comportement du disjoncteur

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

Pour plus d'informations sur les disjoncteurs et leur configuration par défaut, voir cet exemple sur Github.

Les demandes brutes sont utiles et, dans certains cas, nécessaires. Cas d'utilisation courants : Lors de l'utilisation de votre propre client HTTP, qui soumet une demande OCI authentifiée à un autre point d'extrémité, et qui soumet une demande à une API OCI qui n'est pas prise en charge actuellement dans la trousse SDK. La trousse SDK pour Java présente la classe DefaultRequestSigner que vous pouvez utiliser pour créer une instance RequestSigner pour les demandes non standard.

L'exemple de demande brute sur GitHub montre comment :

• Créer un fournisseur d'authentification et un signataire de demande
• Intégrer à un client HTTP (Jersey dans cet exemple) pour authentifier les demandes

Les points d'extrémité de service peuvent être définis de trois façons.

• Appelez setEndpoint() sur l'instance de service. Vous pouvez ainsi spécifier un nom d'hôte complet (par exemple, https://www.example.com).
• Appelez setRegion() sur l'instance de service. Cela sélectionne le nom d'hôte approprié pour le service dans la région indiquée. Toutefois, si le service n'est pas pris en charge dans la région que vous définissez, la trousse SDK pour Java retourne une erreur.
• Transmettez la région dans le fichier de configuration. Pour plus d'informations, voir Fichier de configuration des trousses SDK et de l'interface de ligne de commande.

Notez qu'une instance de service ne peut pas être utilisée pour communiquer avec différentes régions. Si vous devez faire des demandes à différentes régions, créez plusieurs instances de service.

Si vous avez une logique conditionnelle basée sur une énumération, veillez à ce que le code traite le cas UnknownEnumValue pour garantir la compatibilité ascendante. Certains champs de réponse sont de type énumération, mais, dans le futur, des services individuels pourraient retourner des valeurs qui ne seraient pas couvertes par des é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. Si un service retourne une valeur qui n'est pas reconnue par votre version de trousse SDK, le champ de réponse sera réglé à cette valeur.

Si vous utilisez une version de trousse SDK antérieure à l'annonce d'une nouvelle région, vous pouvez utiliser une solution de rechange pour l'atteindre.

Une région est une zone géographique localisée. Pour plus d'informations sur les régions et comment les identifier, voir Régions et domaines de disponibilité.

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

Vous devez d'abord appeler Region.register pour enregistrer la nouvelle région, puis vous pouvez définir la région en utilisant le 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 retournent des jeux de résultats paginés; vous devez donc vérifier les éléments supplémentaires et, si nécessaire, extraire la page suivante. Vous pouvez le faire 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 chiffrement côté client vous permet de chiffrer les données du côté client avant de les stocker localement ou de les utiliser avec d'autres services Oracle Cloud Infrastructure.

Pour utiliser le chiffrement côté client, vous devez créer une clé de chiffrement principale à l'aide du service de gestion des clés. Cette création peut être effectuée à l'aide des opérations CreateKey ou ImportKey.

La clé de chiffrement principale sert à générer une clé de chiffrement des données pour chiffrer les données utiles. Une copie chiffrée de cette clé de chiffrement des données (chiffrée à l'aide de la clé de chiffrement principale) et d'autres éléments de métadonnées sont inclus dans les données utiles chiffrées retournées par les trousses SDK pour pouvoir être utilisés pour le déchiffrement.

// 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 du traitement d'une exception, vous pouvez obtenir plus d'informations sur la demande HTTP qui l'a générée, notamment le code de statut ou la temporisation. Vous pouvez également obtenir l'ID demande lors du traitement d'une exception BmcException à l'aide de la méthode getOpcRequestId.

Cet exemple présente un bloc try-catch qui traite une exception BmcException et imprime l'ID 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 la trousse SDK pour Java sont des exceptions d'exécution (non vérifiées). Elles ne s'affichent pas dans les signatures de méthode. Toutes les API peuvent générer un message BmcException.