Build a Java Application

To build a Java application that accesses a JSON database, you start by configuring your development system to support database access that can take advantage of the high performance features of Autonomous JSON Database. Then, in your application you code database connections and SQL statements to take advantage of these features.

Topics

Parent topic: Build an Application

Configure Your Java Development System

To configure your development system so that your Java application can take advantage of the high performance features of a JSON database, perform these steps.

Download and install the Java Development Kit (JDK).
Download the client credentials for your Autonomous Database.
Get the Oracle Java Database Connectivity (JDBC) drivers.

Download and Install the JDK

Go to the Java SE Downloads page. Then, download and install JDK 8u221 or later by following the instructions on the page.

Download the Client Credentials for Your Autonomous Database

Download the zip file containing client credentials for your database to a secure directory on your computer.

This zip file is available for download from the database's Details page in the Oracle Cloud console. If you have an Oracle Cloud user account that permits you to access this page, download the credentials as follows. If you don't have such an account, you need to get the zip file from the administrator of the database, together with the password that was used to protect the zip file.
1. In your web browser, sign in to Oracle Cloud and navigate to the Details page for the JSON database.
2. Click DB Connection.
3. On the Database Connection page click Download.
4. In the Download Wallet dialog, enter a password in the Password field and confirm the password in the Confirm Password field.
  
  The password must be at least 8 characters long and must include at least 1 letter and either 1 numeric character or 1 special character.
5. Click Download and unzip, to save the client credentials zip file to a secure directory.

Get the Oracle JDBC Drivers

Get the Oracle JDBC drivers, version 19.6.0.0 or later, from either Maven Central or the JDBC Downloads page at Oracle Technical Resources. (See the Oracle Technologies JDBC Home page for related videos and other resources.)

To get the JDBC drivers from Maven Central, follow these steps.

Get the Oracle JDBC drivers from Central Maven Repository. Choose version 19.6.0.0 or later.

Provide the driver Maven dependency GAV (GroupID, ArtifactID, VersionID), to pull ojdbc8.jar, along with other jars such as oraclepki.jar, osdt_core.jar, and osdt_cert.jar. See Maven Central Guide.

For ojdbc8.jar version 19.6.0.0, provide this GAV:
```
<groupId>com.oracle.database.jdbc</groupId>
<artifactId>ojdbc8</artifactId>
<version>19.7.0.0</version>
```
For ojdbc8.jar version 19.7.0.0, provide this GAV:
```
<groupId>com.oracle.database.jdbc</groupId>
<artifactId>ojdbc8-production</artifactId>
<version>19.7.0.0</version>
<type>POM</type>
```

To get the JDBC drivers from Oracle Technical Resources, follow these steps.

Go to the Oracle JDBC Downloads page. Choose the link for version 19.6.0.0 or later, to go to its download page.
Download and unzip this archive to the directory where you want to place the JDBC driver: ojdbc8-full.tar.gz.
Point the connection URL to your Autonomous JSON Database.

Append TNS_ADMIN to the connection URL, setting its value to the full path of the directory where you unzipped the client credentials. For example:
```
// Use TNS alias name plus TNS_ADMIN with JDBC driver 18.3 or higher
DB_URL="jdbc:oracle:thin:@wallet_dbname?
TNS_ADMIN=/Users/test/wallet_dbname";

// For Microsoft Windows, use this for TNS_ADMIN:
// TNS_ADMIN=C:\\Users\\test\\wallet_dbname”;
```
Add the paths to the following unzipped JAR files to the CLASSPATH environment variable you use when you compile and run Java programs.

Use DataSourceSample.java or UCPSample.java to verify the connection to your Autonomous JSON Database.
- ojdbc8.jar: the core JDBC driver
- oraclepki.jar, osdt_core.jar, and osdt_cert.jar: for an Autonomous JSON Database that uses wallet-based authentication
- ucp.jar: for Universal Connection Pooling (UCP)

Download, Install, and Configure SODA for Java

Follow these steps to download, install, and configure SODA for Java.

Go to the SODA for Java downloads page on GitHub: https://github.com/oracle/soda-for-java/releases.
Choose the latest release of SODA for Java, and download the following:
- Jar file orajsoda-<relno>.jar, where <relno> is the release number
- The zip or tar.gz source-code archive
Note:

The SODA for Java driver is also available on Central Maven Repository.
Extract the source-code archive to the directory where you want to install SODA for Java.
Consult the documentation in file README.md and the files in folder doc, for instructions about building the source code and getting started.

Note:

Autonomous Database does not support Metadata builder. To customize collection metadata for a given collection, pass collection metadata strings directly to method createCollection. See SODA Collection Metadata on Autonomous Database for more information.

Set JVM Networking Properties
Autonomous Database uses DNS names that map to multiple IP addresses (multiple load balancers) for better availability and performance. Depending on your application, you may want to configure certain JVM networking properties.

Parent topic: Build a Java Application

Set JVM Networking Properties

Autonomous Database uses DNS names that map to multiple IP addresses (multiple load balancers) for better availability and performance. Depending on your application, you may want to configure certain JVM networking properties.

For the Java Virtual Machine (JVM) address cache, any address resolution attempt caches the result whether it was successful or not, so that subsequent identical requests do not have to access the naming service. The address cache properties allow you to tune how the cache operates. In particular, the networkaddress.cache.ttl value specifies the number of seconds a successful name lookup is kept in the cache. A value of -1, the default value, indicates a “cache forever” policy, while a value of 0 (zero) means no caching.

If your Java Virtual Machine (JVM) is configured to cache DNS address lookups, your application may be using only one IP address to connect to your Autonomous Database, resulting in lower throughput. To prevent this you can change your JVM's networkaddress.cache.ttl value to 0, so that every connection request does a new DNS lookup. This ensures that different threads in your application are distributed over multiple load balancers.

To change the networkaddress.cache.ttl value for all applications, or in your application, do one of the following:

Configure the security policy to set the value for all applications:
Set networkaddress.cache.ttl=0 in the file $JAVA_HOME/jre/lib/security/java.security

Set the following property in your application code:

java.security.Security.setProperty("networkaddress.cache.ttl" , "0");

Parent topic: Configure Your Java Development System

Code Database Connections and SQL Statements

Follow these guidelines to achieve high performance of your application's connections to the database:

Use connection pools.
Use the predefined database service that best matches the operations you will be performing. For most purposes working with JSON data, this is service tp, the typical application connection service for transaction processing operations. For information about the available predefined database services see Database Service Names for Autonomous Transaction Processing and Autonomous JSON Database in Using Oracle Autonomous Database Serverless.

For example:

import java.sql.Connection;
import javax.sql.PooledConnection;
import oracle.jdbc.OracleConnection;
import oracle.jdbc.replay.OracleDataSourceFactory;
import oracle.jdbc.replay.OracleDataSource;
import oracle.jdbc.replay.OracleConnectionPoolDataSource;
...
  PoolDataSource pds = PoolDataSourceFactory.getPoolDataSource();
  // Set the connection factory first before all other properties
  pds.setConnectionFactoryClassName("oracle.jdbc.replay.OracleConnectionPoolDataSourceImpl");
  pds.setURL("jdbc:oracle:thin:@tp?TNS_ADMIN=/users/jdoe/adbcredentials");
  pds.setUser("appuser");
  pds.setPassword("<password>");
  pds.setConnectionPoolName("JDBC_UCP_POOL");

  Connection conn = pds.getConnection();

  // Create an OracleRDBMSClient instance.
  // This is the starting point of the SODA for Java application.
  OracleRDBMSClient cl = new OracleRDBMSClient();

  // Get a database.
  OracleDatabase db = cl.getDatabase(conn);

  // Create a collection with the name "MyJSONCollection".
  OracleCollection col =
    db.admin().createCollection("MyJSONCollection");

Additional Resources

For information about SODA for Java, see Oracle Database SODA for Java Developer's Guide

For detailed information about the Oracle Database JDBC Driver, see Oracle Database JDBC Developer's Guide and Oracle Database JDBC Java API Reference.

For detailed information about the Universal Connection Pool, see Oracle Universal Connection Pool Developer's Guide and Oracle Universal Connection Pool API Reference.

Parent topic: Build a Java Application