Module io.helidon.integrations.oci.sdk.cdi
Package io.helidon.integrations.oci.sdk.cdi

Class OciExtension

java.lang.Object
io.helidon.integrations.oci.sdk.cdi.OciExtension
All Implemented Interfaces:
Extension
public final class OciExtension extends Object implements Extension
A CDI portable extension that enables the injection of any service interface, service client, service client builder, asynchronous service interface, asynchronous service client, or asynchronous service client builder from the Oracle Cloud Infrastructure Java SDK.

Terminology

The terms service interface, service client, service client builder, asynchronous service interface, asynchronous service client, and asynchronous service client builder are defined as follows:

Service
An Oracle Cloud Infrastructure service supported by the Oracle Cloud Infrastructure Java SDK.
Service interface
A Java interface describing the functionality of a service. Distinguished from an asynchronous service interface.

For a hypothetical service named Cloud Example, the corresponding service interface will be in a package named com.oracle.bmc.cloudexample. The service interface's simple name is often also named after the service, e.g. CloudExample, but need not be.

Service client
A concrete Java class that implements the service interface and has the same package name as it. Distinguished from an asynchronous service client.

The service client's simple name is formed by appending the simple name of the service interface with Client. The class name for the service client for the hypothetical com.oracle.bmc.cloudexample.CloudExample service interface described above will thus be com.oracle.bmc.cloudexample.CloudExampleClient.

Service client builder
A concrete Java "builder" class that creates possibly customized instances of its corresponding service client. Distinguished from an asynchronous service client builder.

The service client builder is nearly always a nested class of the service client whose instances it builds with a simple name of Builder. (In the single case in the entirety of the Oracle Cloud Infrastructure Java SDK where this pattern is not followed, the service client builder's simple name is formed by adding Builder to the service client's simple name.) The class name for the service client builder for the hypothetical com.oracle.bmc.cloudexample.CloudExampleClient service client described above will thus be com.oracle.bmc.cloudexample.CloudExampleClient$Builder.

Asynchronous service interface
A Java interface describing the functionality of a service. Distinguished from a service interface.

For a hypothetical service named Cloud Example, the corresponding service interface will be in the same package as that of the service interface. The asynchronous service interface's simple name is formed by adding Async to the service interface's simple name. The class name for the asynchronous service interface for the hypothetical com.oracle.bmc.cloudexample.CloudExample service interface described above will thus be com.oracle.bmc.cloudexample.CloudExampleAsync.

Asynchronous service client
A concrete Java class that implements the asynchronous service interface and has the same package name as it. Distinguised from a service client.

The asynchronous service client's simple name is formed by appending the simple name of the asynchronous service interface with Client. The class name for the asynchronous service client for the hypothetical com.oracle.bmc.cloudexample.CloudExample asynchronous service interface described above will thus be com.oracle.bmc.cloudexample.CloudExampleAsyncClient.

Asynchronous service client builder
A concrete Java "builder" class that creates possibly customized instances of its corresponding asynchronous service client. Distinguished from a service client builder.

The asynchronous service client builder is nearly always a nested class of the asynchronous service client whose instances it builds with a simple name of Builder. (In the single case in the entirety of the Oracle Cloud Infrastructure Java SDK where this pattern is not followed, the asynchronous service client builder's class name is formed by adding Builder to the asynchronous service client's class name.) The class name for the service client builder for the hypothetical com.oracle.bmc.cloudexample.CloudExampleAsyncClient service client described above will thus be com.oracle.bmc.cloudexample.CloudExampleAsyncClient$Builder.

Additionally, for any given service interface, service client, service client builder, asynchronous service interface, asynchronous service client, or asynchronous service client builder, this extension also enables the injection of an appropriate AbstractAuthenticationDetailsProvider, which allows the corresponding service client to authenticate with the service.

In all cases, user-supplied beans will be preferred over any otherwise installed by this extension.

Basic Usage

To use this extension, make sure it is on your project's runtime classpath. To inject a service interface named com.oracle.bmc.cloudexample.CloudExample (or an analogous asynchronous service interface), you will also need to ensure that its containing artifact is on your compile classpath (e.g. oci-java-sdk-cloudexample-$VERSION.jar, where $VERSION should be replaced by a suitable version number).

Advanced Usage and Customization

In the course of providing injection support for a service interface or an asynchronous service interface, this extension will also create service client builder and asynchronous service client builder instances by invoking the static builder() method that is present on all service client classes, and will then add those instances as beans. The resulting service client or asynchronous service client will be built by that builder's build(AbstractAuthenticationDetailsProvider) method and will itself be added as a bean.

A user may wish to customize this builder so that the resulting service client or asynchronous service client reflects the customization. She has two options:

  1. She may supply her own bean with the service client builder type (or asynchronous client builder type) as one of its bean types. In this case, this extension does not supply the service client builder (or asynchronous service client builder) and the user is in full control of how her service client (or asynchronous service client) is constructed.
  2. She may customize the service client builder (or asynchronous service client builder) supplied by this extension. To do this, she declares an observer method that observes the service client builder object (or asynchronous service client builder object) that is returned from the static service client (or asynchronous service client) builder() method. In her observer method, she may call any method on the supplied service client builder (or asynchronous service client builder) and her customizations will be retained.

Configuration

This extension uses the following MicroProfile Config property names (note, however, that no configuration is required):

MicroProfile Config property names
Name Type Description Default Value Notes
oci.auth-strategies String[] A comma-separated list of descriptors describing the strategy, or strategies, to use to select an appropriate AbstractAuthenticationDetailsProvider when one is called for. auto Zero or more of the following:
  • auto
  • config
  • config-file
  • instance-principals
  • oke-workload-identity
  • resource-principal
  • session-token-builder
  • session-token-config-file

A strategy descriptor of config will cause a SimpleAuthenticationDetailsProvider to be used, populated with other MicroProfile Config properties described here.

A strategy descriptor of config-file will cause a ConfigFileAuthenticationDetailsProvider to be used, loaded from an OCI configuration file, with a loading process customized with other MicroProfile Config properties described here.

A strategy descriptor of instance-principals will cause an InstancePrincipalsAuthenticationDetailsProvider to be used.

A strategy descriptor of oke-workload-identity will cause a OkeWorkloadIdentityAuthenticationDetailsProvider to be used.

A strategy descriptor of resource-principal will cause a ResourcePrincipalAuthenticationDetailsProvider to be used.

A strategy descriptor of session-token-builder will cause a SessionTokenAuthenticationDetailsProvider to be used, built from a SessionTokenAuthenticationDetailsProviderBuilder instance, customizable using other facilities described in this documentation.

A strategy descriptor of session-token-config-file will cause a SessionTokenAuthenticationDetailsProvider to be used, loaded from an OCI configuration file, with a loading process customized with other MicroProfile Config properties described here.

If there are many strategy descriptors supplied, the first one that is deemed to be available or suitable will be used and all others will be ignored.

If auto is present in the list, or if no value for this property can be found, the behavior will be as if auto were replaced with config,config-file,session-token-config-file,session-token-builder,instance-principals,resource-principal,oke-workload-identity instead. (The replacement values are subject to change in subsequent revisions of this class.)
oci.config.path String A String that is a path to a valid OCI configuration file A default location This configuration property has an effect only when either config-file or session-token-config-file is, explicitly or implicitly, present in the value for the oci.auth-strategies configuration property described elsewhere in this table.
oci.config.profile String An OCI configuration file profile. DEFAULT This configuration property has an effect only when either config-file or session-token-config-file is, explicitly or implicitly, present in the value for the oci.auth-strategies configuration property described elsewhere in this table.
oci.auth.fingerprint String An API signing key's fingerprint. This configuration property has an effect only when config is, explicitly or implicitly, present in the value for the oci.auth-strategies configuration property described elsewhere in this table.
oci.auth.region Region (String representation) A region identifier. This configuration property has an effect only when config is, explicitly or implicitly, present in the value for the oci.auth-strategies configuration property described elsewhere in this table.
oci.auth.tenant-id String An OCID of a tenancy. This configuration property has an effect only when config is, explicitly or implicitly, present in the value for the oci.auth-strategies configuration property described elsewhere in this table.
oci.auth.user-id String An OCID of a user. This configuration property has an effect only when config is, explicitly or implicitly, present in the value for the oci.auth-strategies configuration property described elsewhere in this table.
oci.extension.classname-vetoes String[] A comma-separated list of class names beginning with com.oracle.bmc. that should be skipped, even if they match the service pattern described above. It is recommended not to supply a value for this property name except in extraordinary circumstances.
oci.extension.lenient-classloading boolean If true, classes that cannot be loaded will not cause a definition error and will simply be skipped (recommended). true It is recommended not to supply a value for this property name except in extraordinary circumstances.
See Also: