Getting Started

2.1 Requirements for using UCP

UCP has the following design-time and run-time requirements:

JRE 1.5 or higher
A JDBC diver or a connection factory class capable of returning a java.sql.Connection and javax.sql.XAConnection object

Note:

Oracle drivers from releases 10.1 or higher are supported. Advanced Oracle Database features, such as Oracle RAC and Fast Connection Failover, require the Oracle Notification Service library (ons.jar) that is included with the Oracle Client software.
The ucp.jar library included in the classpath of the application
The ojdbc8.jar library included in the classpath of the application

Note:

Even if you use UCP with a third-party database and driver, you must use the Oracle ojdbc8.jar library because UCP has dependencies on this library.
A database that supports SQL. Advanced features, such as Oracle RAC and Fast Connection Failover, require an Oracle Database.

2.2 Basic Connection Steps in UCP

UCP provides a pool-enabled data source that is used by applications to borrow connections from a UCP JDBC connection pool. A connection pool is not explicitly defined for the most basic use case. Instead, a default connection pool is implicitly created when the connection is borrowed.

The following steps describe how to get a connection from a UCP pool-enabled data source in order to access a database. The complete example is provided in Example 2-1:

Use the UCP data source factory (oracle.ucp.jdbc.PoolDataSourceFactory) to get an instance of a pool-enabled data source using the getPoolDataSource method. The data source instance must be of the type PoolDataSource. For example:
```
PoolDataSource  pds = PoolDataSourceFactory.getPoolDataSource();
```
Set the connection properties that are required to get a physical connection to a database. These properties are set on the data source instance and include: the URL, the user name, and password to connect to the database and the connection factory used to get the physical connection. These properties are specific to a JDBC driver and database. For example:
```
pds.setConnectionFactoryClassName("oracle.jdbc.pool.OracleDataSource");
pds.setURL("jdbc:oracle:thin:@//localhost:1521/XE");
pds.setUser("<user>");
pds.setPassword("<password>");
```
Set any pool properties in order to override the connection pool's default behavior. the pool properties are set on the data source instance. For example:
```
pds.setInitialPoolSize(5);
```
Get a connection using the data source instance. The returned connection is a logical handle to a physical connection in the data source's connection pool. For example:
```
Connection conn = pds.getConnection();
```

Use the connection to perform some work on the database:

Statement stmt = conn.createStatement ();
stmt.execute("SELECT * FROM foo");

Close the connection and return it to the pool.
```
conn.close();
```

2.2.1 Authentication in UCP

UCP provides transparent authentication, that is, the PoolDataSource behaves in the same way as the OracleDataSource while authenticating a connection. UCP supports all the following authentication methods that the JDBC thin or the JDBC ICY driver suggests, and delegates any authentication action to the underlying driver:

Authentication through passwords stored in Oracle Wallets
Authentication using Kerberos
Authentication through SSL certificates
Authentication using Lightweight Directory Access Protocol (LDAP)

2.3 UCP API Overview

The following section provides a quick overview of the most commonly used packages of the UCP API.

2.4 Basic Connection Example Using UCP

The following example is a program that connects to a database to do some work and then exits. The example is simple and in some cases not very practical; however, it does demonstrate the basic steps required to get a connection from a UCP pooled-enabled data source in order to access a database.

Example 2-1 Basic Connection Example

import java.sql.Connection;
import java.sql.SQLException;
import java.sql.Statement;
import oracle.ucp.jdbc.PoolDataSourceFactory;
import oracle.ucp.jdbc.PoolDataSource;

public class BasicConnectionExample {
   public static void main(String args[]) throws SQLException {
      try 
      {
         //Create pool-enabled data source instance.
         
         PoolDataSource  pds = PoolDataSourceFactory.getPoolDataSource();
         
         //set the connection properties on the data source.
         
         pds.setConnectionFactoryClassName("oracle.jdbc.pool.OracleDataSource");
         pds.setURL("jdbc:oracle:thin:@//localhost:1521/XE");
         pds.setUser("<user>");
         pds.setPassword("<password>");     
         
         //Override any pool properties.
         
         pds.setInitialPoolSize(5);
         
         //Get a database connection from the datasource.
         
         Connection conn = pds.getConnection();
         
         System.out.println("\nConnection obtained from " +
          "UniversalConnectionPool\n");
         
         //do some work with the connection.
         Statement stmt = conn.createStatement();
         stmt.execute("select * from foo");
         
         //Close the Connection.
         
         conn.close();
         conn=null;
         
         System.out.println("Connection returned to the " +
          "UniversalConnectionPool\n");
         
      }
      catch(SQLException e)
      {
         System.out.println("BasicConnectionExample - " +
          "main()-SQLException occurred : "
              + e.getMessage());
      }
   }
}