QuickStart Java applications with Oracle Database (On-premises)

• 1. Install Oracle AI Database

  Follow the steps described on this page to install Oracle AI Database Free. If you already have installed database and have database credentials, then you can skip this step.

• 2. Install the JDK

  Install the JDK: JDK8, JDK11, JDK17, JDK21 and JDK25 are long term support releases. Make sure to use any one of these versions.

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

• 3. Create the Database User (Optional)

  Note: If you already have a database user and password then you can skip this step.

  We recommend using a new database user when verifying the database connection. If you are not familiar with creating a database user and assigning privileges then you can use CreateUser.java to create a new database user.

  - Edit the file CreateUser.java , provide connection string, admin user, and admin password along with new database user and password to be created.

  - Download the latest Oracle JDBC driver and UCP.

  - Make sure that the Oracle database is running before compiling and running the sample.
  

  # Compile the Java program
  javac -classpath ./test/ojdbc8.jar:./test/ucp.jar CreateUser.java
  # Run the Java program
  java -classpath ./test/ojdbc8.jar:./test/ucp.jar:. CreateUser
  
  Alternately, you can use the commands below to create a new database user if you are using Docker.
  
  

  # These are instructions to create a new database user  
  #Step 1: Make sure docker is running before running the below docker command
  #Step 2: Enter the admin password for your database on the console
  #Step 3: Provide the new database user and password to be created
  
  # Create a session within the container with Oracle as user 
  docker exec -it --user oracle \
     -e 'ORACLE_HOME=/opt/oracle/product/18c/dbhomeXE' \
     $(docker ps --format '{{.ID}}') \
     /bin/bash -c  'exec ${ORACLE_HOME}/bin/sqlplus "sys@xepdb1 as sysdba"'
  
  # Create a new database user and grant required privileges. 
  # Replace "{newdbuser}"  and "{newdbpassword}" with the new DB user and password that you want to create
  grant CREATE SESSION, CREATE VIEW, CREATE SEQUENCE,CREATE PROCEDURE, CREATE TABLE, 
  CREATE TRIGGER, CREATE TYPE, CREATE MATERIALIZED VIEW to {newdbuser} identified by {newdbpassword};
  
  
  

• 4. Download a sample program from Github
  • Download QuickStart.java from Github. This sample application creates a table 'todoitem' that contains tasks and task completion status, inserts few rows, and displays the contents of the table.

  • Edit QuickStart.java to include your database connection information:
    

    • DB_USER: Use the database user from step 3.
    • DB_PASSWORD: Use the database password from step 3.
    • DB_URL: Enter the connection string of the Oracle Database.

    
    

    Example: DB_URL = "jdbc:oracle:thin:@//localhost:152/FREEPDB1"

  • Save changes to QuickStart.java

Maven

• 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.
    
    

    <dependencies>
    <dependency>
    <groupId>com.oracle.database.jdbc</groupId>
    <artifactId>ojdbc8-production</artifactId>
    <version>23.26.2.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.QuickStart"

  • Sample Output:

    You will see the queried rows returned from the new table 'todoitem' and a message Congratulations! You have successfully used Oracle Database.

Gradle Project

• 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 and 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 QuickStart.java to src directory : Make sure to copy QuickStart.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 downloads Oracle JDBC driver (ojdbc8.jar) along with UCP as a client side connection pool (ucp.jar). Refer to Maven Central Guide for more details.
    • Update the 'mainClassName' to QuickStart.
      

      repositories { 
        // Maven Central
         mavenCentral()
       } 
      
      dependencies { 
        // Get the 23.26.2.0.0 Oracle JDBC driver along with other companion jars
        implementation("com.oracle.database.jdbc:ojdbc8-production:19.9.0.0")
       }
      application { 
        // Define the main class for the application
        mainClassName ='{your_project_directory}.QuickStart' 
      }

• 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 new table 'todoitem' and a message Congratulations! You have successfully used Oracle Database

Eclipse

• 1. Setup a Maven project

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

  • Create a Maven project:

    • File -->New --> Project --> 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: JDBCquickstart
      Version: Leave it as 0.0.1-SNAPSHOT
      

  • Create QuickStart.java: Right click on src/main/java. and click on, New -> Class. Enter the following values.
    Package: com.oracle.jdbctest
    Name: QuickStart and Click 'Finish'.
    Make sure to copy contents of QuickStart.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 required jar for using UCP as a client side connection pool). Refer to Maven Central Guide for more details.
    
    
    <dependencies>
    <dependency>
    <groupId>com.oracle.database.jdbc</groupId>
    <artifactId>ojdbc8-production</artifactId>
    <version>23.26.2.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 in Eclipse. Also, make sure that Oracle Database is running on Docker.

  • Run the sample Java program: Right Click on QuickStart.java --> Run As --> Java Application.
    

  • Sample Output:

    You will see the queried rows returned from the new table 'todoitem' and a message Congratulations! You have successfully used Oracle Database.

IntelliJ

• 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'. You can use any maven archetype or add your own. Click Next.
    • Give 'Name' as Quickstart

    
    

  • Create QuickStart.java: Right click on src /main/java. Click on New --> Java Class. Enter com.oracle.jdbctest.QuickStart.java This will create the required package structure as well. Make sure to copy contents of QuickStart.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 ucp.jar (It is a jar required for using UCP as a client side connection pool). Refer to Maven Central Guide for more details.
    
    
    <dependencies>
    <dependency>
    <groupId>com.oracle.database.jdbc</groupId>
    <artifactId>ojdbc8-production</artifactId>
    <version>23.26.2.0.0</version>
    <type>pom</type>
    </dependency>
    </dependencies>

    
    

• 2. Build and Run QuickStart

  • Compile the Java code: Right click on QuickStart.java --> Build Module 'QuickStart'. Make sure there are no compilation errors. Make sure that Oracle Database is running on Docker and accessible.

  • Run the sample Java program: Right click on QuickStart.java --> Run 'QuickStart.main()'.

  • Sample Output:

    You will see the queried rows returned from the database and a message Congratulations! You have successfully used Oracle Database

• 1. Download JDBC Driver and other Jars

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

  • Download 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) and UCP as a client side connection pool (ucp.jar)

• 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 com/oracle/jdbctest/QuickStart.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:. com.oracle.jdbctest.QuickStart
    

    Sample Output:

    You will see the queried rows returned from the new table 'todoitem' and a message Congratulations! You have successfully used Oracle Database.