Class OciExtension
- All Implemented Interfaces:
Extension
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 hypotheticalcom.oracle.bmc.cloudexample.CloudExample
service interface described above will thus becom.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 addingBuilder
to the service client's simple name.) The class name for the service client builder for the hypotheticalcom.oracle.bmc.cloudexample.CloudExampleClient
service client described above will thus becom.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 hypotheticalcom.oracle.bmc.cloudexample.CloudExample
service interface described above will thus becom.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 hypotheticalcom.oracle.bmc.cloudexample.CloudExample
asynchronous service interface described above will thus becom.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 addingBuilder
to the asynchronous service client's class name.) The class name for the service client builder for the hypotheticalcom.oracle.bmc.cloudexample.CloudExampleAsyncClient
service client described above will thus becom.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:
- 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.
- 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):
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:
A strategy descriptor of A strategy descriptor of A strategy descriptor of A strategy descriptor of A strategy descriptor of A strategy descriptor of A strategy descriptor of 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 |
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:
-
Constructor Summary
-
Method Summary
-
Constructor Details
-
OciExtension
Deprecated.ForServiceLoader
use only.Creates a newOciExtension
.
-
ServiceLoader
use only.