diff --git a/java/jdbc-resource-providers/README.md b/java/jdbc-resource-providers/README.md new file mode 100644 index 00000000..c3680560 --- /dev/null +++ b/java/jdbc-resource-providers/README.md @@ -0,0 +1,141 @@ +# Resource Providers Sample + +Simple Sample Application demonstrating use of Resource Providers. + +- __Oracle JDBC Version `ojdbc11-production` - `v23.5.0.24.07`__ +- __Java Version used `21`__ +- __Oracle Autonomous Database used `19c`__ + +## Environment Variables +The following environment variables are expected by the application. +In order to successfully run the application, the required environment variables below are marked and some are optional: + +| Variable | Required | Name | Default | Description | +|------------------------|:-----------:|--------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------| +| `ORACLE_PASSWORD` | Conditional | Database Password | - | Database Credential if required | +| `ORACLE_USERNAME` | Conditional | Database User | | Database Credentials if required, user must exist | +| `COMPARTMENT_OCID` | Conditional | Compartment OCID | | Compartment Oracle Cloud Identifier(OCID) in which the Oracle Database lives in, used by Access Token Provider in determining scope | +| `DATABASE_OCID` | Conditional | Database OCID | | Database Oracle Cloud Identifier(OCID), used by multiple providers | +| `KEY_VAULT_URL` | Conditional | Azure Key Vault URL | | Key Vault URL used by Azure Key Vault Providers | +| `USERNAME_SECRET_NAME` | Conditional | Azure Key Vault Username Secret Name | | Name of secret in Azure Key Vault used by the Azure Key Vault Username Providers | +| `PASSWORD_SECRET_NAME` | Conditional | Azure Key Vault Password Secret Name | | Name of secret in Azure Key Vault used by the Azure Key Vault Password Providers | + +### Demo Files +- [demo-1.properties](properties/demo-1.properties) - Property file for OCI Connection TLS + OCI Connection String Providers +- [demo-2.properties](properties/demo-2.properties) - Property file for OCI Connection TLS + OCI Connection String + OCI Access Token Providers +- [demo-3.properties](properties/demo-3.properties) - Property file for OCI Connection TLS + OCI Connection String + Azure Key Vault Username and Password Providers + + + + +# Building the Application +The application uses Maven to build and manage the project with its dependencies. +```bash +mvn clean package +``` + +# Running the Application +To run the application JAR, you can run the following commmand: +```bash +java -jar target/java-basic-1.0-SNAPSHOT.jar +``` + +# Running the Demos + +### Example 1: OCI Connection TLS + OCI Connection String Providers + +To run this example, in [main.java](src/main/java/org/oracle/Main.java), set the following environment variables +referenced in the following lines, as user credentials are required. +```java + String PASSWORD = System.getenv("ORACLE_PASSWORD"); + String USERNAME = System.getenv("ORACLE_USERNAME"); +``` +Make sure the User and Password are set: +```java +OracleDataSource ods = new OracleDataSource(); +ods.setURL("jdbc:oracle:thin:@"); +ods.setUser(USERNAME); +ods.setPassword(PASSWORD); +``` +Set the following system property to the demo-1.properties file. +```bash + System.setProperty("oracle.jdbc.config.file", "properties/demo-1.properties"); +``` + +This `.properties` file requires the environment variable: +- DATABASE_OCID + + +Refer to the following documentations in regard to authentication and further configurations: +1. [Configuring Authentication for Resource Providers](https://github.com/oracle/ojdbc-extensions/blob/main/ojdbc-provider-oci/README.md#configuring-authentication-1) +2. [OCI Connection TLS Provider](https://github.com/oracle/ojdbc-extensions/blob/main/ojdbc-provider-oci/README.md#database-tls-provider) +3. [OCI Connection String Provider](https://github.com/oracle/ojdbc-extensions/blob/main/ojdbc-provider-oci/README.md#database-connection-string-provider) + +### Example 2: OCI Connection TLS + OCI Connection String + OCI Access Token Providers + +To run this example, in [main.java](src/main/java/org/oracle/Main.java), __remove__ or __comment out__ the following lines as user credentials are not required. +```java + String PASSWORD = System.getenv("ORACLE_PASSWORD"); + String USERNAME = System.getenv("ORACLE_USERNAME"); +``` + +Make sure the credentials are NOT set: +```java +OracleDataSource ods = new OracleDataSource(); +ods.setURL("jdbc:oracle:thin:@"); +``` + +Set the following system property to the demo-2.properties file. + +```bash + System.setProperty("oracle.jdbc.config.file", "properties/demo-2.properties"); +``` + +This `.properties` file requires the environment variable: +- DATABASE_OCID +- COMPARTMENT_OCID + + +Refer to the following documentations in regard to authentication and further configurations: +1. [Configuring Authentication for Resource Providers](https://github.com/oracle/ojdbc-extensions/blob/main/ojdbc-provider-oci/README.md#configuring-authentication-1) +2. [OCI Access token Provider](https://github.com/oracle/ojdbc-extensions/blob/main/ojdbc-provider-oci/README.md#access-token-provider) +3. [Authenticating into the Database using Oracle Cloud IAM and Access Tokens](https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/manage-users-iam.html) + + + +### Example 3: OCI Connection TLS + OCI Connection String Providers + +To run this example, in [main.java](src/main/java/org/oracle/Main.java), __remove__ or __comment out__ the following lines as user credentials are not required. +```java + String PASSWORD = System.getenv("ORACLE_PASSWORD"); + String USERNAME = System.getenv("ORACLE_USERNAME"); +``` + +Make sure the credentials are NOT set: +```java +OracleDataSource ods = new OracleDataSource(); +ods.setURL("jdbc:oracle:thin:@"); +``` + +Set the following system property to the demo-3.properties file. + +```bash + System.setProperty("oracle.jdbc.config.file", "properties/demo-3.properties"); +``` + +This `.properties` file requires the environment variables: +- DATABASE_OCID +- KEY_VAULT_URL +- USERNAME_SECRET_NAME +- PASSWORD_SECRET_NAME + + +Refer to the following documentations in regard to authentication and further configurations: +1. [Configuring Authentication for Resource Providers](https://github.com/oracle/ojdbc-extensions/blob/main/ojdbc-provider-oci/README.md#configuring-authentication-1) +2. [Azure Key Vault Username Provider](https://github.com/oracle/ojdbc-extensions/blob/main/ojdbc-provider-azure/README.md#key-vault-username-provider) +3. [Azure Key Vault Password Provider](https://github.com/oracle/ojdbc-extensions/blob/main/ojdbc-provider-azure/README.md#key-vault-password-provider) + +# Documentation +- [GitHub: Oracle JDBC Extensions](https://github.com/oracle/ojdbc-extensions/tree/main) + + diff --git a/java/jdbc-resource-providers/pom.xml b/java/jdbc-resource-providers/pom.xml new file mode 100644 index 00000000..fe6b747a --- /dev/null +++ b/java/jdbc-resource-providers/pom.xml @@ -0,0 +1,51 @@ + + + 4.0.0 + + org.oracle + jdbc-resource-providers + 1.0-SNAPSHOT + + + 21 + 21 + UTF-8 + 2.0.16 + + + + + com.oracle.database.jdbc + ojdbc11-production + 23.5.0.24.07 + pom + + + + com.oracle.database.jdbc + ojdbc-provider-oci + 1.0.1 + + + + com.oracle.database.jdbc + ojdbc-provider-azure + 1.0.1 + + + + + org.slf4j + slf4j-api + ${slf4j.version} + + + org.slf4j + slf4j-simple + ${slf4j.version} + + + + diff --git a/java/jdbc-resource-providers/properties/demo-1.properties b/java/jdbc-resource-providers/properties/demo-1.properties new file mode 100644 index 00000000..7a0f6ba4 --- /dev/null +++ b/java/jdbc-resource-providers/properties/demo-1.properties @@ -0,0 +1,54 @@ +################################################################################ +# Copyright (c) 2024 Oracle and/or its affiliates. +# +# The Universal Permissive License (UPL), Version 1.0 +# +# Subject to the condition set forth below, permission is hereby granted to any +# person obtaining a copy of this software, associated documentation and/or data +# (collectively the "Software"), free of charge and under any and all copyright +# rights in the Software, and any and all patent rights owned or freely +# licensable by each licensor hereunder covering either (i) the unmodified +# Software as contributed to or provided by such licensor, or (ii) the Larger +# Works (as defined below), to deal in both +# +# (a) the Software, and +# (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if +# one is included with the Software (each a "Larger Work" to which the Software +# is contributed by such licensors), +# +# without restriction, including without limitation the rights to copy, create +# derivative works of, display, perform, and distribute the Software and make, +# use, sell, offer for sale, import, export, have made, and have sold the +# Software and the Larger Work(s), and to sublicense the foregoing rights on +# either these or other terms. +# +# This license is subject to the following condition: +# The above copyright notice and either this complete permission notice or at +# a minimum a reference to the UPL must be included in all copies or +# substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +# SOFTWARE. +################################################################################ + + +# Configures the OCI Database Connection String Provider. The OCID of the database +# is configured as an environment variable or JVM system property named +# "DATABASE_OCID": +# https://github.com/oracle/ojdbc-extensions/blob/main/ojdbc-provider-oci/README.md#database-connection-string-provider +oracle.jdbc.provider.connectionString=ojdbc-provider-oci-database-connection-string +oracle.jdbc.provider.connectionString.ocid=${DATABASE_OCID} +oracle.jdbc.provider.connectionString.profile=DEFAULT + +# Configures the OCI Database TLS Provider. Again, the OCID of the database +# is configured as an environment variable or JVM system property named +# "DATABASE_OCID": +# https://github.com/oracle/ojdbc-extensions/blob/main/ojdbc-provider-oci/README.md#database-tls-provider +oracle.jdbc.provider.tlsConfiguration=ojdbc-provider-oci-database-tls +oracle.jdbc.provider.tlsConfiguration.ocid=${DATABASE_OCID} +oracle.jdbc.provider.tlsConfiguration.profile=DEFAULT diff --git a/java/jdbc-resource-providers/properties/demo-2.properties b/java/jdbc-resource-providers/properties/demo-2.properties new file mode 100644 index 00000000..4232bc0a --- /dev/null +++ b/java/jdbc-resource-providers/properties/demo-2.properties @@ -0,0 +1,61 @@ +################################################################################ +# Copyright (c) 2024 Oracle and/or its affiliates. +# +# The Universal Permissive License (UPL), Version 1.0 +# +# Subject to the condition set forth below, permission is hereby granted to any +# person obtaining a copy of this software, associated documentation and/or data +# (collectively the "Software"), free of charge and under any and all copyright +# rights in the Software, and any and all patent rights owned or freely +# licensable by each licensor hereunder covering either (i) the unmodified +# Software as contributed to or provided by such licensor, or (ii) the Larger +# Works (as defined below), to deal in both +# +# (a) the Software, and +# (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if +# one is included with the Software (each a "Larger Work" to which the Software +# is contributed by such licensors), +# +# without restriction, including without limitation the rights to copy, create +# derivative works of, display, perform, and distribute the Software and make, +# use, sell, offer for sale, import, export, have made, and have sold the +# Software and the Larger Work(s), and to sublicense the foregoing rights on +# either these or other terms. +# +# This license is subject to the following condition: +# The above copyright notice and either this complete permission notice or at +# a minimum a reference to the UPL must be included in all copies or +# substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +# SOFTWARE. +################################################################################ + +# Configures the OCI Database Connection String Provider. The OCID of the database +# is configured as an environment variable or JVM system property named +# "DATABASE_OCID": +# https://github.com/oracle/ojdbc-extensions/blob/main/ojdbc-provider-oci/README.md#database-connection-string-provider +oracle.jdbc.provider.connectionString=ojdbc-provider-oci-database-connection-string +oracle.jdbc.provider.connectionString.ocid=${DATABASE_OCID} +oracle.jdbc.provider.connectionString.profile=DEFAULT + +# Configures the OCI Database TLS Provider. Again, the OCID of the database +# is configured as an environment variable or JVM system property named +# "DATABASE_OCID": +# https://github.com/oracle/ojdbc-extensions/blob/main/ojdbc-provider-oci/README.md#database-tls-provider +oracle.jdbc.provider.tlsConfiguration=ojdbc-provider-oci-database-tls +oracle.jdbc.provider.tlsConfiguration.ocid=${DATABASE_OCID} +oracle.jdbc.provider.tlsConfiguration.profile=DEFAULT + +# Configures the OCI OAUTH Token Provider. The OCID of the database and its +# compartment are configured as an environment variables or JVM system +# properties named "DATABASE_OCID" and "COMPARTMENT_OCID": +# https://github.com/oracle/ojdbc-extensions/blob/main/ojdbc-provider-oci/README.md#access-token-provider +oracle.jdbc.provider.accessToken=ojdbc-provider-oci-token +oracle.jdbc.provider.accessToken.scope=urn:oracle:db::id::${COMPARTMENT_OCID}::${DATABASE_OCID} +oracle.jdbc.provider.accessToken.profile=DEFAULT \ No newline at end of file diff --git a/java/jdbc-resource-providers/properties/demo-3.properties b/java/jdbc-resource-providers/properties/demo-3.properties new file mode 100644 index 00000000..3aab174d --- /dev/null +++ b/java/jdbc-resource-providers/properties/demo-3.properties @@ -0,0 +1,70 @@ +################################################################################ +# Copyright (c) 2024 Oracle and/or its affiliates. +# +# The Universal Permissive License (UPL), Version 1.0 +# +# Subject to the condition set forth below, permission is hereby granted to any +# person obtaining a copy of this software, associated documentation and/or data +# (collectively the "Software"), free of charge and under any and all copyright +# rights in the Software, and any and all patent rights owned or freely +# licensable by each licensor hereunder covering either (i) the unmodified +# Software as contributed to or provided by such licensor, or (ii) the Larger +# Works (as defined below), to deal in both +# +# (a) the Software, and +# (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if +# one is included with the Software (each a "Larger Work" to which the Software +# is contributed by such licensors), +# +# without restriction, including without limitation the rights to copy, create +# derivative works of, display, perform, and distribute the Software and make, +# use, sell, offer for sale, import, export, have made, and have sold the +# Software and the Larger Work(s), and to sublicense the foregoing rights on +# either these or other terms. +# +# This license is subject to the following condition: +# The above copyright notice and either this complete permission notice or at +# a minimum a reference to the UPL must be included in all copies or +# substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +# SOFTWARE. +################################################################################ + +# Configures the OCI Database Connection String Provider. The OCID of the database +# is configured as an environment variable or JVM system property named +# "DATABASE_OCID": +# https://github.com/oracle/ojdbc-extensions/blob/main/ojdbc-provider-oci/README.md#database-connection-string-provider +oracle.jdbc.provider.connectionString=ojdbc-provider-oci-database-connection-string +oracle.jdbc.provider.connectionString.ocid=${DATABASE_OCID} +oracle.jdbc.provider.connectionString.profile=DEFAULT + +# Configures the OCI Database TLS Provider. Again, the OCID of the database +# is configured as an environment variable or JVM system property named +# "DATABASE_OCID": +# https://github.com/oracle/ojdbc-extensions/blob/main/ojdbc-provider-oci/README.md#database-tls-provider +oracle.jdbc.provider.tlsConfiguration=ojdbc-provider-oci-database-tls +oracle.jdbc.provider.tlsConfiguration.ocid=${DATABASE_OCID} +oracle.jdbc.provider.tlsConfiguration.profile=DEFAULT + +# Configures the Azure Key Vault Username Provider. The vault URL and secret name +# are configured as an environment variables or JVM system properties +# named "KEY_VAULT_URL" and "USERNAME_SECRET_NAME". +# https://github.com/oracle/ojdbc-extensions/blob/main/ojdbc-provider-azure/README.md#key-vault-username-provider +oracle.jdbc.provider.username=ojdbc-provider-azure-key-vault-username +oracle.jdbc.provider.username.vaultUrl=${KEY_VAULT_URL} +oracle.jdbc.provider.username.secretName=${USERNAME_SECRET_NAME} + +# Configures the Azure Key Vault Password Provider. The vault URL and secret name +# are configured as an environment variables or JVM system properties +# named "KEY_VAULT_URL" and "PASSWORD_SECRET_NAME". +# https://github.com/oracle/ojdbc-extensions/blob/main/ojdbc-provider-azure/README.md#key-vault-password-provider +oracle.jdbc.provider.password=ojdbc-provider-azure-key-vault-password +oracle.jdbc.provider.password.vaultUrl=${KEY_VAULT_URL} +oracle.jdbc.provider.password.secretName=${PASSWORD_SECRET_NAME} + diff --git a/java/jdbc-resource-providers/src/main/java/org/oracle/Main.java b/java/jdbc-resource-providers/src/main/java/org/oracle/Main.java new file mode 100644 index 00000000..1ef5c4aa --- /dev/null +++ b/java/jdbc-resource-providers/src/main/java/org/oracle/Main.java @@ -0,0 +1,79 @@ +/* + ** Copyright (c) 2024 Oracle and/or its affiliates. + ** + ** The Universal Permissive License (UPL), Version 1.0 + ** + ** Subject to the condition set forth below, permission is hereby granted to any + ** person obtaining a copy of this software, associated documentation and/or data + ** (collectively the "Software"), free of charge and under any and all copyright + ** rights in the Software, and any and all patent rights owned or freely + ** licensable by each licensor hereunder covering either (i) the unmodified + ** Software as contributed to or provided by such licensor, or (ii) the Larger + ** Works (as defined below), to deal in both + ** + ** (a) the Software, and + ** (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if + ** one is included with the Software (each a "Larger Work" to which the Software + ** is contributed by such licensors), + ** + ** without restriction, including without limitation the rights to copy, create + ** derivative works of, display, perform, and distribute the Software and make, + ** use, sell, offer for sale, import, export, have made, and have sold the + ** Software and the Larger Work(s), and to sublicense the foregoing rights on + ** either these or other terms. + ** + ** This license is subject to the following condition: + ** The above copyright notice and either this complete permission notice or at + ** a minimum a reference to the UPL must be included in all copies or + ** substantial portions of the Software. + ** + ** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + ** IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + ** FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + ** AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + ** LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + ** OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + ** SOFTWARE. + */ + +package org.oracle; + +import oracle.jdbc.pool.OracleDataSource; + +import java.sql.SQLException; +import java.sql.PreparedStatement; +import java.sql.ResultSet; +import java.sql.Connection; + + +public class Main { + public static void main(String[] args) throws SQLException { + + // Retrieve credentials, if needed + // comment out if username, password not required + String PASSWORD = System.getenv("ORACLE_PASSWORD"); + String USERNAME = System.getenv("ORACLE_USERNAME"); + // Set custom location for the config properties file with the property oracle.jdbc.config.file + System.setProperty("oracle.jdbc.config.file", "properties/demo-1.properties"); + + // Configure OracleDataSource + OracleDataSource ods = new OracleDataSource(); + ods.setURL("jdbc:oracle:thin:@"); + // comment out if username, password not required + ods.setUser(USERNAME); + ods.setPassword(PASSWORD); + + // try-with: establish a connection and retrieve database version + try (Connection connection = ods.getConnection(); + PreparedStatement ps = connection.prepareStatement("select BANNER from v$version"); + ResultSet rs = ps.executeQuery() + ) { + rs.next(); + System.out.println(rs.getString("BANNER")); + + } catch (SQLException e) { + throw new RuntimeException(e); + } + + } +} \ No newline at end of file diff --git a/java/jdbc-resource-providers/src/main/resources/simplelogger.properties b/java/jdbc-resource-providers/src/main/resources/simplelogger.properties new file mode 100644 index 00000000..9a9b2a0f --- /dev/null +++ b/java/jdbc-resource-providers/src/main/resources/simplelogger.properties @@ -0,0 +1 @@ +org.slf4j.simpleLogger.defaultLogLevel = error \ No newline at end of file