Skip to content

Commit f10284a

Browse files
ting-lan-wangting-lan-wang
authored
Update README.md to cover wallet_location and removed unused example … (#155)
* Update README.md to cover wallet_location and removed unused example classes. * Fix javadoc error * Update run-tests.yaml to use cache v4 * Optimize imports
1 parent 9188ce5 commit f10284a

File tree

7 files changed

+108
-462
lines changed

7 files changed

+108
-462
lines changed

‎.github/workflows/run-tests.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ jobs:
2121
with:
2222
java-version: 11
2323
- name: Cache Maven packages
24-
uses: actions/cache@v2
24+
uses: actions/cache@v4
2525
with:
2626
path: ~/.m2
2727
key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}

‎ojdbc-provider-azure/README.md

+16-39
Original file line numberDiff line numberDiff line change
@@ -53,23 +53,26 @@ JDK versions. The coordinates for the latest release are:
5353
The Config Provider for Azure is a Centralized Config Provider that provides Oracle JDBC with
5454
connection properties from the App Configuration service and the Key Vault service.
5555

56-
A new prefix of the JDBC URL `jdbc:oracle:thin:@config-azure://` is used by the Oracle DataSource to be able to identify that the configuration parameters should be loaded using Azure App Configuration. Users only need to indicate the App Config's name, a prefix for the key-names and a label (both optional) with the following syntax:
56+
A new prefix of the JDBC URL `jdbc:oracle:thin:@config-azure://` is used by the Oracle Data Source to be able to identify that the configuration parameters should be loaded using Azure App Configuration. Users only need to indicate the App Config's name, a prefix for the key-names and a label (both optional) using the following syntax, where option-value pairs separated by `&` are optional authentication parameters that vary by provider:
5757

5858
<pre>
5959
jdbc:oracle:thin:@config-azure://{appconfig-name}[?key=prefix&label=value&option1=value1&option2=value2...]
6060
</pre>
6161

62+
For more details about the option-value pairs, see [Common Parameters for Centralized Config Providers](#common-parameters-for-centralized-config-providers).
63+
6264
If prefix and label are not informed, the provider will retrieve all the values that are not labeled or prefixed.
6365

64-
There are 3 fixed values that are looked at by the provider in the retrieved configuration:
66+
There are 4 fixed values that are looked at by the provider in the retrieved configuration:
6567

6668
- connect_descriptor (required)
6769
- user (optional)
6870
- password (optional)
71+
- wallet_location (optional)
6972

7073
The rest are dependent on the driver, in our case `/jdbc`. The key-value pairs that are with sub-prefix `/jdbc` will be applied to a DataSource. The key values are constant keys which are equivalent to the properties defined in the [OracleConnection](https://docs.oracle.com/en/database/oracle/oracle-database/23/jajdb/oracle/jdbc/OracleConnection.html) interface.
7174

72-
For example, let's suppose an url like:
75+
For example, let's suppose a URL like:
7376

7477
<pre>
7578
jdbc:oracle:thin:@config-azure://myappconfig?key=/sales_app1/&label=dev
@@ -78,15 +81,16 @@ jdbc:oracle:thin:@config-azure://myappconfig?key=/sales_app1/&label=dev
7881
And the configuration in App Configuration '**myappconfig**' as follows (note that some values such as password can be a reference to a Key Vault secret):
7982

8083
| Key | Value | Label |
81-
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
84+
|-------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ----- |
8285
| /sales_app1/user | scott | dev |
8386
| /sales_app1/connect_descriptor | (description=(address=(protocol=tcps)(port=1521)(host=adb.us-phoenix-1.oraclecloud.com))(connect_data=(service_name=gebqqvpozhjbqbs_dbtest_medium.adb.oraclecloud.com))) | dev |
8487
| /sales_app1/password | {"uri":"myvault.vault.azure.net/secrets/mysecret"} | dev |
88+
| /sales_app1/wallet_location | {"uri":"myvault.vault.azure.net/secrets/mywallet"} | dev |
8589
| /sales_app1/jdbc/autoCommit | false | dev |
8690
| /sales_app1/jdbc/oracle.jdbc.fanEnabled | true | dev |
8791
| /sales_app1/jdbc/oracle.jdbc.loginTimeout | 20 | dev |
8892

89-
In this case the OracleDataSource that gets generated uses the above values as its properties.
93+
In this case the Oracle Data Source that gets generated uses the above values as its properties.
9094

9195
The sample code below executes as expected with the previous configuration (and the Azure Credentials set as explained below).
9296

@@ -101,15 +105,15 @@ The sample code below executes as expected with the previous configuration (and
101105
```
102106
## Azure Vault Config Provider
103107
Similar to [OCI Vault Config Provider](../ojdbc-provider-oci/README.md#oci-vault-config-provider), JSON Payload can also be stored in the content of Azure Key Vault Secret.
104-
The Oracle DataSource uses a new prefix `jdbc:oracle:thin:@config-azurevault://`. Users only need to indicate the Vault Secret’s secret identifier, with the following syntax:
108+
The Oracle Data Source uses a new prefix `jdbc:oracle:thin:@config-azurevault://`. Users only need to indicate the Vault Secret’s secret identifier using the following syntax, where option-value pairs separated by `&` are optional authentication parameters that vary by provider:
105109

106110
<pre>
107-
jdbc:oracle:thin:@config-azurevault://{secret-identifier}
111+
jdbc:oracle:thin:@config-azurevault://{secret-identifier}[?option1=value1&option2=value2...]
108112
</pre>
109113

110-
To view an example format of JSON Payload, please refer to [JSON Payload format](../ojdbc-provider-oci/README.md#json-payload-format).
111-
114+
For more details about the option-value pairs, see [Common Parameters for Centralized Config Providers](#common-parameters-for-centralized-config-providers).
112115

116+
To view an example format of JSON Payload, please refer to [JSON Payload format](../ojdbc-provider-oci/README.md#json-payload-format).
113117

114118
## Common Parameters for Centralized Config Providers
115119
Provider that are classified as Centralized Config Providers in this module share the same sets of parameters for authentication configuration.
@@ -183,36 +187,9 @@ The Azure SDK `DefaultAzureCredential` class tries the following flow in order t
183187
## Caching configuration
184188

185189
Config providers in this module store the configuration in caches to minimize
186-
the number of RPC requests to remote location. Every stored items has a property
187-
that defines the time-to-live (TTL) value. When TTL expires, the configuration
188-
becomes "softly expired" and the stored configuration will be refreshed by a
189-
background thread. If configuration cannot be refreshed, it can still be used
190-
for another 30 minutes until it becomes "hardly expired". In other words, it takes
191-
24 hours and 30 minutes for configuration before it becomes completely expired.
192-
193-
The default value of TTL is 24 hours and it can be configured using the
194-
"config_time_to_live" property in the unit of seconds.
195-
An example of App Configuration in Azure with TTL of 60 seconds is listed below.
196-
197-
<table>
198-
<thead><tr>
199-
<th>Key</th>
200-
<th>Value</th>
201-
</tr></thead>
202-
<tbody><tr>
203-
<td>user</td>
204-
<td>myUsername</td>
205-
</tr><tr>
206-
<td>password</td>
207-
<td>myPassword</td>
208-
</tr><tr>
209-
<td>connect_descriptor</td>
210-
<td>myHost:5521/myService</td>
211-
</tr><tr>
212-
<td>config_time_to_live</td>
213-
<td>60</td>
214-
</tr></tbody>
215-
</table>
190+
the number of RPC requests to remote location. See
191+
[Caching configuration](../ojdbc-provider-oci/README.md#caching-configuration) for more
192+
details of the caching mechanism.
216193

217194
## Access Token Provider
218195
The Access Token Provider provides Oracle JDBC with an access token that authorizes

‎ojdbc-provider-oci/README.md

+91-31
Original file line numberDiff line numberDiff line change
@@ -63,38 +63,48 @@ JDK versions. The coordinates for the latest release are:
6363
## OCI Database Tools Connections Config Provider
6464

6565
The OCI Database Tools Connections is a managed service that can be used to configure connections to a database.
66-
The created resource stores connection properties, including user, password and wallets (these last two optionally as references to a secret in OCI Vault).
67-
Each configuration has an identifier (OCID) that is used to identify which connection is requested by the driver.
66+
The created resource stores connection properties, including user, password and wallet (these last two optionally as references to a secret in OCI Vault).
6867

69-
JDBC URL Sample that uses the OCI DBTools provider:
68+
Users only need to indicate the OCID of the resource using the following syntax, where option-value pairs separated by `&` are optional authentication parameters that vary by provider:
7069

7170
<pre>
72-
jdbc:oracle:thin:@config-ocidbtools://ocid1.databasetoolsconnection.oc1.phx.ama ...
71+
jdbc:oracle:thin:@config-ocidbtools://{oci-database-tools-ocid}[?option1=value1&option2=value2...]
72+
</pre>
73+
74+
For more details about the option-value pairs, see [Common Parameters for Centralized Config Providers](#common-parameters-for-centralized-config-providers).
75+
76+
For example:
77+
78+
<pre>
79+
jdbc:oracle:thin:@config-ocidbtools:ocid1.databasetoolsconnection.oc1.phx.ama...
7380
</pre>
7481

7582
Provider can now support Database Tools Connections with Proxy Authentication,
7683
only if username is provided in Proxy Authentication Info, without the password and roles.
7784

7885
## OCI Object Storage Config Provider
79-
The Oracle DataSource uses a new prefix `jdbc:oracle:thin:@config-ociobject://` to be able to identify that the configuration parameters should be loaded using OCI Object Storage. Users only need to indicate the URL Path of the Object containing the JSON payload, with the following syntax:
86+
The Oracle Data Source uses a new prefix `jdbc:oracle:thin:@config-ociobject://` to be able to identify that the configuration parameters should be loaded using OCI Object Storage. Users only need to indicate the URL Path of the Object containing the JSON payload using the following syntax, where option-value pairs separated by `&` are optional authentication parameters that vary by provider:
8087

8188
<pre>
8289
jdbc:oracle:thin:@config-ociobject://{url_path}[?option1=value1&option2=value2...]
8390
</pre>
8491

85-
The insturctions of obtaining a URL Path can be found in [Get the URI or Pre-Authenticated Request URL to Access the Object Store](https://docs.oracle.com/en/cloud/paas/autonomous-database/csgru/get-uri-access-object-store.html).
92+
The instructions of obtaining a URL Path can be found in [Get the URI or Pre-Authenticated Request URL to Access the Object Store](https://docs.oracle.com/en/cloud/paas/autonomous-database/csgru/get-uri-access-object-store.html).
93+
94+
For more details about the option-value pairs, see [Common Parameters for Centralized Config Providers](#common-parameters-for-centralized-config-providers).
8695

8796
### JSON Payload format
8897

89-
There are 3 fixed values that are looked at the root level.
98+
There are 4 fixed values that are looked at the root level.
9099

91100
- connect_descriptor (required)
92101
- user (optional)
93102
- password (optional)
103+
- wallet_location (optional)
94104

95-
The rest are dependent on the driver, in our case `/jdbc`. The key-value pairs that are with sub-prefix `/jdbc` will be applied to a DataSource. The key values are constant keys which are equivalent to the properties defined in the [OracleConnection](https://docs.oracle.com/en/database/oracle/oracle-database/23/jajdb/oracle/jdbc/OracleConnection.html) interface.
105+
The rest are dependent on the driver, in our case `/jdbc`. The key-value pairs that are with sub-prefix `/jdbc` will be applied to a Data Source. The key values are constant keys which are equivalent to the properties defined in the [OracleConnection](https://docs.oracle.com/en/database/oracle/oracle-database/23/jajdb/oracle/jdbc/OracleConnection.html) interface.
96106

97-
For example, let's suppose an url like:
107+
For example, let's suppose a URL like:
98108

99109
<pre>
100110
jdbc:oracle:thin:@config-ociobject://mytenancy.objectstorage.us-phoenix-1.oci.customer-oci.com/n/mytenancy/b/bucket1/o/payload_ojdbc_objectstorage.json
@@ -104,11 +114,21 @@ And the JSON Payload for the file **payload_ojdbc_objectstorage.json** in the **
104114

105115
```json
106116
{
107-
"connect_descriptor": "(description=(retry_count=20)(retry_delay=3)(address=(protocol=tcps)(port=1521)(host=adb.us-phoenix-1.oraclecloud.com))(connect_data=(service_name=xsxsxs_dbtest_medium.adb.oraclecloud.com))(security=(ssl_server_dn_match=yes)))",
117+
"connect_descriptor": "(description=...)",
108118
"user": "scott",
109-
"password": {
119+
"password": {
120+
"type": "ocivault",
121+
"value": "ocid1.vaultsecret.oc1.phx.amaaaaaxxxx",
122+
"authentication": {
123+
"method": "OCI_INSTANCE_PRINCIPAL"
124+
}
125+
},
126+
"wallet_location": {
110127
"type": "ocivault",
111-
"value": "ocid1.vaultsecret.oc1.phx.amaaaaaxxxx"
128+
"value": "ocid1.vaultsecret.oc1.phx.amaaaaY",
129+
"authentication": {
130+
"method": "OCI_INSTANCE_PRINCIPAL"
131+
}
112132
},
113133
"jdbc": {
114134
"oracle.jdbc.ReadTimeout": 1000,
@@ -132,28 +152,41 @@ The sample code below executes as expected with the previous configuration.
132152

133153
### Password JSON Object
134154

135-
For the JSON type of provider (OCI Object Storage, HTTP/HTTPS, File) the password is an object itself with the following spec:
155+
For the JSON type of provider (OCI Object Storage, HTTPS, File) the password is an object itself with the following spec:
136156

137-
- type
157+
- `type`
138158
- Mandatory
139-
- Possible values
140-
- ocivault
141-
- azurevault
142-
- base64
143-
- awssecretsmanager
144-
- value
159+
- Possible values:
160+
- `ocivault`
161+
- `azurevault`
162+
- `base64`
163+
- `awssecretsmanager`
164+
- `value`
145165
- Mandatory
146-
- Possible values
166+
- Possible values:
147167
- OCID of the secret (if ocivault)
148168
- Azure Key Vault URI (if azurevault)
149169
- Base64 Encoded password (if base64)
150-
- AWS Secret name (if awssecretsmanager)
151-
- Text
152-
- authentication
153-
- Optional (it will apply defaults in the same way as described in [Configuring Authentication](#configuring-authentication)).
154-
- Possible Values
155-
- method
156-
- optional parameters (depends on the cloud provider, applies the same logic as [Config Provider for Azure](../ojdbc-provider-azure/README.md#config-provider-for-azure)).
170+
- AWS resource name of the secret (if awssecretsmanager)
171+
- `authentication`
172+
- Optional. It will apply defaults in the same way as described in [Configuring Authentication](#configuring-authentication)
173+
- Possible Values:
174+
- `method`: equivalent to the 'AUTHENTICATION' Param Value in [Configuring Authentication](#configuring-authentication)
175+
- Optional parameters: depends on the cloud provider. Equivalent to the Optional Parameters in [Configuring Authentication](#configuring-authentication)
176+
177+
### Wallet_location JSON Object
178+
179+
The "oracle.net.wallet_location" connection property is not allowed in the "jdbc" object due to security reasons. Instead, users should use the "wallet_location" object to specify the wallet in the configuration.
180+
181+
For the JSON type of provider (OCI Object Storage, HTTPS, File) the wallet_location is an object itself with the same spec as the [password JSON object](#password-json-object) mentioned above.
182+
183+
The value stored in the secret should be the Base64 representation of the bytes in cwallet.sso. This is equivalent to setting the "oracle.net.wallet_location" connection property in a regular JDBC application using the following format:
184+
185+
```
186+
data:;base64,<Base64 representation of the bytes in cwallet.sso>
187+
```
188+
189+
<i>*Note: When storing a wallet as a secret in OCI Vault, choose the Plain-Text secret type template instead of Base64 to prevent double decoding when the provider retrieves the value.</i>
157190

158191
## OCI Vault Config Provider
159192
Apart from OCI Object Storage, users can also store JSON Payload in the content of OCI Vault Secret. Users need to indicate the OCID of the Secret with the following syntax:
@@ -226,9 +259,36 @@ in Optional Parameters</td>
226259
## Caching configuration
227260

228261
Config providers in this module store the configuration in caches to minimize
229-
the number of RPC requests to remote location. See
230-
[Caching configuration](../ojdbc-provider-azure/README.md#caching-configuration) for more
231-
details of the caching mechanism.
262+
the number of RPC requests to remote location. Every stored items has a property
263+
that defines the time-to-live (TTL) value. When TTL expires, the configuration
264+
becomes "softly expired" and the stored configuration will be refreshed by a
265+
background thread. If configuration cannot be refreshed, it can still be used
266+
for another 30 minutes until it becomes "hardly expired". In other words, it takes
267+
24 hours and 30 minutes for configuration before it becomes completely expired.
268+
269+
The default value of TTL is 24 hours, and it can be configured using the
270+
"config_time_to_live" property in the unit of seconds.
271+
An example of App Configuration in Azure with TTL of 60 seconds is listed below.
272+
273+
<table>
274+
<thead><tr>
275+
<th>Key</th>
276+
<th>Value</th>
277+
</tr></thead>
278+
<tbody><tr>
279+
<td>user</td>
280+
<td>myUsername</td>
281+
</tr><tr>
282+
<td>password</td>
283+
<td>myPassword</td>
284+
</tr><tr>
285+
<td>connect_descriptor</td>
286+
<td>myHost:5521/myService</td>
287+
</tr><tr>
288+
<td>config_time_to_live</td>
289+
<td>60</td>
290+
</tr></tbody>
291+
</table>
232292

233293
## Database Connection String Provider
234294
The Database Connection String Provider provides Oracle JDBC with the connection string of an

‎ojdbc-provider-samples/src/main/java/oracle/jdbc/provider/aws/configuration/AwsSecretsManagerConfigurationExample.java

-1
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,6 @@
3838
package oracle.jdbc.provider.aws.configuration;
3939

4040
import oracle.jdbc.datasource.impl.OracleDataSource;
41-
import oracle.jdbc.provider.oci.configuration.ObjectStorageExample;
4241

4342
import java.sql.Connection;
4443
import java.sql.ResultSet;

0 commit comments

Comments
 (0)