QuickStart Java applications with Oracle Autonomous Database

Follow these easy steps to connect your Java applications to the Autonomous Database (ADB), using the Oracle JDBC driver and Universal Connection Pool. Oracle Autonomous Database allows both one-way TLS as well as mutual TLS (mTLS) for connection, the default being the later. With one-way TLS aka TLS, you no longer need either Oracle Wallets or JKS to connect to Autonomous Database. When you remove the mTLS requirement, connections can be established with both one-way TLS and with mutual TLS. Pre-requisites section addresses both these approaches. Oracle recommends using the latest Oracle JDBC version 19c which is the Long Term Release. Alternatively you can use the latest Oracle JDBC version 21c-Innovation Release if you require its new features or you can use Oracle JDBC version 23c Free-Developer Release to access the new community supported release.

If you want to connect to the Oracle Database (On-Premises) or Oracle Cloud Database that uses TCP connections then see QuickStart Java applications with Oracle Database (On-premises). Refer to Oracle JDBC and UCP landing page for other technical briefs, blogs, videos etc.,

Pre-requisites (one-wayTLS and mTLS)
Maven and Gradle
Eclipse and IntelliJ
No Build Tools

    Pre-requisites (one way TLS)

    Open all Close all

  • 1. Provision an Autonomous Database (ADB) Instance

    Get access to the Oracle Autonomous Database (ADB). Click on these links to walk through the steps to provision an ADB instance if you have not provisioned an ADB instance already.

    Remember the password that you used for ADMIN user. For this demo purpose, we will be using ADMIN user but, our recommendation is to create other database users either using SQLDeveloper or using SQL Developer web console.

  • 2. Remove Mutual TLS (mTLS) Requirement

      After the creation of an Autonomous Database, mutual TLS is enabled as a default option. Follow these instructions to remove mutual TLS (mTLS) requirement and enable one-way TLS. Once TLS is enabled, you can use both TLS and mTLS to connect to Autonomous Database. Refer to the section JDBC Thin TLS Connections without a Wallet for more details.

    • From the Oracle Cloud Console, go to the Autonomous Database Details page of your Oracle Autonomous Database instance. In the details, find the section titled 'Network' and click on 'Edit' next to 'Access Control List'.
    • In the 'Edit Access Control List' dialog, choose the type of entry that you'd like to make and enter the appropriate value. You can add entries by IP Address (your local IP), CIDR Block, and VCN (by name or OCID). Add as many as necessary.
    • Click on 'Edit' in the 'Mutual TLS (mTLS) Authentication' field and uncheck the 'Require mutual TLS (mTLS) authentication'
    • It takes sometime to update and the status will be changed to Available. After the changes, your network settings should look as shown below.

  • 3. Install latest JDK8 or higher

    Download latest JDK81 or higher JDK versions

    1 Make sure to use JDK8u162 or higher. Use "java -version" to check the JDK version that you have installed. Use "java -jar ojdbc8.jar" to check the JDBC driver version.

  • 4. Download a sample program from Github

    • Download ADBQuickStart.java from Github. This sample application uses the Sales History (SH) sample schema and displays 20 records from SH.CUSTOMERS table.

    • Modify ADBQuickStart.java to include your ADB connection information:

      • DB_USER: You can use ADMIN which is the user created by default during the creation of Autonomous Database. (If you created another ADB user, you can use that user instead.)
      • DB_PASSWORD: Use the database user's password. If connecting as the ADMIN user, set this to the password you chose during the Create Autonomous Database step while provisioning Autonomous Database. For security reasons, you will need to enter password through the console when you run the sample.
      • DB_URL: Click on 'DB Connection' tab of your Autonomous Database. From the 'Connection Strings' dialog box, choose 'TLS' from the dropdown menu and copy the appropriate connection string based on your requirement. If you are directly using in the Java program, you need to escape " in the connection string with \"

        • Example : DB_URL = "jdbc:oracle:thin:@jdbc:oracle:thin:@(description= (retry_count=20)(retry_delay=3)(address=(protocol=tcps)(port=1521)(host=adb.us-sanjose-1.oraclecloud.com))(connect_data=(service_name=g13ec47eade81f7_demodb_low.adb.oraclecloud.com))(security=(ssl_server_cert_dn=\"CN=adb.us-sanjose-1.oraclecloud.com, OU=Oracle ADB SANJOSE, O=Oracle Corporation, L=Redwood City, ST=California, C=US\")))" DB_USER="ADMIN" and DB_PASSWORD="enter_it_from_console"

    • Save changes to ADBQuickStart.java
    • Troubleshooting and Debugging: If you encounter any errors, check out Troubleshooting Tips page for some helpful hints.

    Pre-requisites (mutual TLS)

    Open all Close all

  • 1. Provision an Autonomous Database (ADB) Instance

    Get access to the Oracle Autonomous Database (ADB). Click on these links to walk through the steps to provision an ADB instance if you have not provisioned an ADB instance already.

    Remember the password that you used for ADMIN user. For this demo purpose, we will be using ADMIN user but, our recommendation is to create other database users either using SQLDeveloper or using SQL Developer web console.

  • 2. Obtain Client Credentials

      After the creation of an Autonomous Database, follow these instructions to download the client credentials from the Oracle Cloud Console. The client credentials (wallet_[dbname].zip) contains required wallet files and tnsnamea.ora that give mutual TLS, providing enhanced security for authentication and encryption.
    • From the Oracle Cloud Console, go to the Autonomous Database Details page of your Oracle Autonomous Database instance.
    • Click the DB Connection button. A new window will appear.
    • Click the Download Wallet button. Leave the 'Wallet Type' to be 'Instance Wallet'.
    • Enter a wallet password in the Password field and confirm the password in the Confirm password field. Then, click the Download button. The password must be at least 8 characters long and include at least 1 letter and either 1 numeric character or 1 special character.
    • Save and unzip the client credentials zip (wallet_[dbname].zip) file to a secure directory. You will need this directory location later on.

  • 3. Install JDK8 or higher

    Download JDK81 or higher JDK versions

    1 Use "java -version" to check the JDK version that you have installed. Use "java -jar ojdbc8.jar" to check the JDBC driver version.

  • 4. Download a sample program from Github

    • Download ADBQuickStart.java from Github. This sample application uses the Sales History (SH) sample schema and displays 20 records from SH.CUSTOMERS table.

    • Modify ADBQuickStart.java to include your ADB connection information:

      • DB_USER: You can use ADMIN which is the user created by default during the creation of Autonomous Database. (If you created another ADB user, you can use that user instead.)
      • DB_PASSWORD: Use the database user's password. If connecting as the ADMIN user, set this to the password you chose during the Create Autonomous Database step while provisioning Autonomous Database. For security reasons, you will need to enter password through the console when you run the sample.
      • DB_URL: Enter the net service name (aka TNS Alias) DBName_medium where DBName is Database Name entered during the Create Autonomous Database step while provisioning Autonomous Database. The available net service names can be seen in tnsnames.ora file which is part of the client credentials zip file.
        TNS_ADMIN should point to the location where you have unzipped the client credentials of your Autonomous Database (ADB).

        • Example : DB_URL = "jdbc:oracle:thin:@DBName_medium?TNS_ADMIN=/Users/test/wallet_DBName" DB_USER="ADMIN" and DB_PASSWORD="enter_it_from_console"

    • Save changes to ADBQuickStart.java
    • Troubleshooting and Debugging: If you encounter any errors, check out Troubleshooting Tips page for some helpful hints.

    Maven Project

    Open all Close all

  • 1. Setup a Maven project

    • Pre-requisites: Make sure to complete all the steps from pre-requisites section.

    • Create a Maven project : Download Apache Maven and make sure to set the PATH before using mvn commands. Use the following maven command to create a project. 

      

mvn archetype:generate -DgroupId=com.oracle.jdbctest -DartifactId=jdbc-test-project -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

    • Copy ADBQuickStart.java to src directory : Make sure to copy ADBQuickStart.java to the src/main/java/com/oracle/jdbctest directory.

    • Modify pom.xml with the following changes:
      Add Oracle JDBC driver as a dependency. Note: ojdbc8-production will download Oracle JDBC driver (ojdbc8.jar ) along with other companion jars such as ucp.jar (It is a jar required for using UCP as a client side connection pool), oraclepki.jar, osdt_core.jar, osdt_cert.jar (These jars are required for using Oracle Wallets while connecting to Autonomous Database) etc., Refer to Maven Central Guide for more details. 

      

<properties>
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
</properties>
<dependencies>
  <dependency>
    <groupId>com.oracle.database.jdbc</groupId>
    <artifactId>ojdbc8-production</artifactId>
    <version>19.18.0.0</version>
    <type>pom</type>
  </dependency>
</dependencies>

  • 2. Build and Run a Sample Java Program

    Make sure you are in the directory where pom.xml is present.

    • Clean and Compile the Java code: Use the following commands.

      

mvn clean

      

mvn compile

    • Run the sample Java program

      

mvn exec:java -Dexec.cleanupDaemonThreads=false -Dexec.mainClass="com.oracle.jdbctest.ADBQuickStart"
    • Sample Output:

      You will see the queried rows returned from the database and a message Congratulations! You have successfully used Oracle Autonomous Database as shown in the screenshot below.
      Note: If you connect to ADB from behind a firewall, you will likely encounter a connection timeout error. Make sure to be outside the firewall while running this sample or update the tnsnames.ora file to use an HTTPS proxy. Learn how to do this in "JDBC Thin Connections with an HTTP Proxy" section of the ADB documentation.


    Gradle Project

    Open all Close all

  • 1. Setup a Gradle project

    • Pre-requisites: Make sure to complete all the steps from pre-requisites section.

    • Create a Gradle project : Follow the instructions from Gradle Guide for Gradle download and build instructions. Make sure to set the PATH before using gradle commands. As a first step, create a gradle project using the below command. Make sure to choose "2: application" for 'Select type of project to generate'. Also, for "Source package (default: temp):" use com.oracle.jdbctest. 

      

gradle init

    • Copy ADBQuickStart.java to src directory : Make sure to copy ADBQuickStart.java to the src/main/java/com/oracle/jdbctest directory.

    • Modify build.gradle with the following changes:

      • Add mavenCentral() as a repository
      • Add the Oracle JDBC driver as a dependency.
        Note: ojdbc8-production will download Oracle JDBC driver (ojdbc8.jar ) along with other companion jars such as ucp.jar (It is a required jar for using UCP as a client side connection pool), oraclepki.jar, osdt_core.jar, osdt_cert.jar (These jars are required for using Oracle Wallets while connecting to Autonomous Database) etc., Refer to Maven Central Guide for more details.
      • Update the 'mainClassName' to ADBQuickStart.
      • Add run block to pause for reading password from console 

       

repositories { 
  // Maven Central
   mavenCentral()
 } 

dependencies { 
  // Get the 19.18.0.0 Oracle JDBC driver along with other companion jars
  implementation("com.oracle.database.jdbc:ojdbc8-production:19.18.0.0")
 }
application { 
  // Define the main class for the application
  mainClassName ='{your_project_directory}.ADBQuickStart' 
} 
// To pause to read the password from console
run {
  standardInput = System.in
}

  • 2. Build and Run the Gradle App

    Make sure you are in the directory where build.gradle is present.

    • Compile the Java code: Use the below command.

      

./gradlew build

    • Run the sample Java program

      

./gradlew run
    • Sample Output:

      You will see the queried rows returned from the database and a message Congratulations! You have successfully used Oracle Autonomous Database as shown in the screenshot below.
      Note: If you connect to ADB from behind a firewall, you will likely encounter a connection timeout error. Make sure to be outside the firewall while running this sample or update the tnsnames.ora file to use an HTTPS proxy. Learn how to do this in "JDBC Thin Connections with an HTTP Proxy" section of the ADB documentation.


    Eclipse

    Open all Close all

  • 1. Setup a Maven project

    • Pre-requisites: Make sure to complete all the steps from pre-requisites section.

    • Create a Maven project :

      • File -->New --> New Maven Project. You can either use maven archetype or check on 'Create a simple project (skip archetype selection)' .
      • Choose GAV for your Maven project: These will appear in pom.xml for the project.
        Group Id: com.oracle
        Artifact Id: ADBquickstart
        Version: Leave it as 0.0.1-SNAPSHOT

    • Create ADBQuickStart.java: Right click on src/main/java . and click on, New -> Class. Enter the following values.
      Package: com.oracle.jdbctest
      Name: ADBQuickStart and Click 'Finish'.
      Make sure to copy contents of ADBQuickStart.java to this new file created.

    • Modify pom.xml with the following changes:
      Add Oracle JDBC driver as a dependency. Note: ojdbc8-production will download Oracle JDBC driver (ojdbc8.jar ) along with other companion jars such as ucp.jar (It is a jar required for using UCP as a client side connection pool), oraclepki.jar, osdt_core.jar, osdt_cert.jar (These jars are required for using Oracle Wallets while connecting to Autonomous Database) etc., Refer to Maven Central Guide for more details. 

      

<properties>
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
</properties>
<dependencies>
  <dependency>
    <groupId>com.oracle.database.jdbc</groupId>
    <artifactId>ojdbc8-production</artifactId>
    <version>19.18.0.0</version>
    <type>pom</type>
  </dependency>
</dependencies>

  • 2. Build and Run a Sample Java Program

    Make sure you do not have any compilation error in the Java code and you are using the latest JDK version.

    • Run the sample Java program: Right Click on ADBQuickStart.java --> Run As --> Java Application.
      You will be shown a prompt to enter the database password and once you enter the password, the results will be shown.

    • Sample Output:

      You will see the queried rows returned from the database and a message Congratulations! You have successfully used Oracle Autonomous Database as shown in the screenshot below.
      Note: If you connect to ADB from behind a firewall, you will likely encounter a connection timeout error. Make sure to be outside the firewall while running this sample or update the tnsnames.ora file to use an HTTPS proxy. Learn how to do this in "JDBC Thin Connections with an HTTP Proxy" section of the ADB documentation.


    IntelliJ

    Open all Close all

  • 1. Setup a Maven project

    • Pre-requisites: Make sure to complete all the steps from pre-requisites section.

    • Create a Maven project :

      • Click on File --> New --> Project
      • Choose 'Maven' on the left hand side and choose the latest version of JDK as 'Project SDK'. Click Next.
      • Give 'Name' as ADBQuickstart

    • Create ADBQuickStart.java : Right click on src/main/java . Click on New --> Java Class. Enter com.oracle.jdbctest.ADBQuickStart.java This will create the required package structure as well. Make sure to copy contents of ADBQuickStart.java to this new file.

    • Modify pom.xml with the following changes:
      Add Oracle JDBC driver as a dependency. Note: ojdbc8-production will download Oracle JDBC driver (ojdbc8.jar ) along with other companion jars such as ucp.jar (It is a jar required for using UCP as a client side connection pool), oraclepki.jar, osdt_core.jar, osdt_cert.jar (These jars are required for using Oracle Wallets while connecting to Autonomous Database) etc., Refer to Maven Central Guide for more details. 

      

<properties>
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
</properties>
<dependencies>
  <dependency>
    <groupId>com.oracle.database.jdbc</groupId>
    <artifactId>ojdbc8-production</artifactId>
    <version>19.18.0.0</version>
    <type>pom</type>
  </dependency>
</dependencies>

  • 2. Build and Run ADBQuickStart

    • Compile the Java code: Right click on ADBQuickStart.java --> Build Module 'ADBQuickStart'. Make sure there are no compilation errors.

    • Run the sample Java program: Right click on ADBQuickStart.java --> Run 'ADBQuickStart.main()'. Make sure to enter the database password on the console.

    • Sample Output:

      You will see the queried rows returned from the database and a message Congratulations! You have successfully used Oracle Autonomous Database as shown in the screenshot below.
      Note: If you connect to ADB from behind a firewall, you will likely encounter a connection timeout error. Make sure to be outside the firewall while running this sample or update the tnsnames.ora file to use an HTTPS proxy. Learn how to do this in "JDBC Thin Connections with an HTTP Proxy" section of the ADB documentation.


    No Build Tools

    Open all Close all

  • 1. Download JDBC Driver and other Jars

    • Make sure to complete all the steps from pre-requisites section.

    • Download latest 19c version of ojdbc8-full.tar.gz from OTN and unzip the contents to your classpath.
      Note: ojdbc8-full.tar.gz contains the latest JDBC driver ojdbc8.jar, ucp.jar (It is a required jar for using UCP as a client side connection pool), oraclepki.jar, osdt_core.jar, osdt_cert.jar (These jars are required for using Oracle Wallets while connecting to Autonomous Database)

  • 2. Build and Run a Sample Java Program

    • Compile the Java program
      Make sure to provide the correct path for the required jars in the classpath. 

      
 javac -classpath ./lib/ojdbc8.jar:./lib/ucp.jar:/lib/oraclepki.jar:./lib/osdt_core.jar:./lib/osdt_cert.jar com/oracle/jdbctest/ADBQuickStart.java

    • Run the sample Java program
      Make sure to provide the correct path for the required jars in the classpath.

      
 java -classpath ./lib/ojdbc8.jar:./lib/ucp.jar:/lib/oraclepki.jar:./lib/osdt_core.jar:./lib/osdt_cert.jar:. com.oracle.jdbctest.ADBQuickStart
    • Sample Output:

      You will see the queried rows returned from the database and a message Congratulations! You have successfully used Oracle Autonomous Database as shown in the screenshot below.
      Note: If you connect to ADB from behind a firewall, you will likely encounter a connection timeout error. Make sure to be outside the firewall while running this sample or update the tnsnames.ora file to use an HTTPS proxy. Learn how to do this in "JDBC Thin Connections with an HTTP Proxy" section of the ADB documentation.