Oracle UCP FAQ

This document contains answers to the most frequently asked questions about Oracle's Universal Connection Pool(UCP). Note that these address specific technical questions only and are used to document solutions to frequent customer questions as well as any known problems. The server docs (including JDBC doc) are also available online. 

• Whats New?
• UCP in general
  • What is UCP?
  • How to use UCP?
  • Where can I get the UCP jar files
  • Where can I learn more about UCP?
  • What application containers should be used with UCP ?
  • Does UCP work with Weblogic?
• Release Specific Questions
  • What are the supported versions of UCP?
  • Can ucp.jar version differ from JDBC driver version?
  • Does ucp.jar version dependent on any database version?
• Connection Specific Questions
  • How to create a database connection using UCP?
• UCP Properties
  • What are the UCP properties?
  • What happens when setInitialPoolSize(5) is invoked?
• Optimizing UCP Properties
  • What are the UCP properties?
  • What happens when setInitialPoolSize(5) is invoked?
• UCP with Tomcat Application Server
  • How to set UCP properties in Tomcat?
• Advanced Features with UCP
  • Oracle Notification Service(ONS)
    • What is ONS ?
    • How to use ONS?
    • How to configure ONS?
    • What are the standard ports that ONS will listen to?
    • How to change the ONS ports?
    • How to monitor if ONS is running?
  • UCP - Fast Connection Failover(FCF)
    • What is Fast Application Notification(FAN)?
    • How to enable FAN in UCP ?
  • UCP - Work Load Balancing
    • What is Work Load Balancing?
    • What are Load Balancing Advisories ?
    • What is Connection time load balancing ?
    • What is Run time load balancing ?
    • How do I enable Run time load balancing ?
    • What are the scenarios where it is difficult to expect fair run time load balancing ?

Whats New?

UCP FAQ page is totally a new page aimed at answering all the questions related to UCP.  The purpose is to make using UCP easier and describe its strong capabilities.

UCP in General

What is UCP?

UCP is the Universal Connection Pool. It is a single connection pool that handles all kinds of connections, JDBC, JCA, LDAP, and others. It supports non-Oracle JDBC drivers and JDBC connections to non-Oracle databases. When used for Oracle JDBC connections to Oracle databases it provides all the features of the old JDBC Implicit Connection Cache, and more. UCP is widely used in Oracle products. We recommend using UCP for its capabilities to handle fail-over gracefully, managing connections, resources and many other reasons.

How do I use UCP?

UCP is a standalone jar file.  It is named as ucp.jar.  It is not included in the JDBC jar file.

Where can I get the UCP jar files?

Please download the required version of UCP jar files from the Oracle Technology Network JDBC, UCP & SQLJ Download Page.

Where can I learn more about UCP?

Please refer to the UCP Reference Guide for more details.

What application containers should be used with UCP ?

UCP can be used with any application containers such as Apache Tomcat, IBM Websphere, JBOSS, Weblogic etc.,

Does UCP work with Weblogic?

UCP does work with Weblogic. However, you should be using "Active Grid Link" which is from oracle and has all similar functionalities

Release Specific Questions

What are the supported versions of UCP?

Current supported versions of ucp.jar file are 12.2, 12.1, 11.1, and 11.2

Can ucp.jar version differ from JDBC driver version?

Prior to 12c (i.e., 12.1.0.1.0), UCP could work with any version of Oracle JDBC driver. With the new pool, UCP 12.1.0.2, it is dependent on Oracle JDBC driver 12.1.0.2. Example: 12.2.0.1 ucp.jar requires ojdbc8.jar from 12.2.0.1.  Our recommendation is to keep both ucp.jar and JDBC drivers from the same version. 

Does ucp.jar version dependent on any database version?

Database version compatibility comes from the JDBC driver version, but not UCP version. UCP jar file should be compatible with the JDBC driver version.

Connection Specific Questions

How to create a database connection using UCP?

UCP for JDBC provides a pool-enabled data source that is used by applications to borrow connections from a UCP JDBC connection pool. Below are the steps involved. 

(1) Get an instance of Poll enabled datasource

PoolDataSource pds = PoolDataSourceFactory.getPoolDataSource();

(2) Set the connection properties that are required to get a physical connection to a database.
pds.setConnectionFactoryClassName("oracle.jdbc.pool.OracleDataSource");
pds.setURL("jdbc:oracle:thin:@//localhost:1521/XE");
pds.setUser("<user>"); pds.setPassword("<password>"); 

(3) Set any pool properties in order to override the connection pool's default behavior. 

Oracle Notification Service(ONS)

What is ONS ?

Oracle Notification Server (ONS) uses a simple publish/subscribe method to produce and deliver event messages for both local and remote consumption. ONS daemons run locally sending messages to and receiving messages from a configured list of nodes (where other ONS daemons are active).  Advanced Oracle Database features, such as Oracle Real Application Clusters(RAC) and Fast Connection Failover(FCF) require ons.jar that is included in the Oracle Client software.

How to use ONS ?

ONS is a jar file called as ons.jar. Please include this in the classpath and wherever the JDBC & UCP jar files are located

How to configure ONS?

ONS configuration is controlled by a configuration file (ons.config) located at ORACLE_HOME/opmn/conf/ons.config. Configuration information within ons.config is defined through name/value pairs. It should contain 

localport: the port that ONS binds to on the localhost interface to talk to local clients. 

remoteport:the port that ONS binds to on all interfaces for talking to other remote ONS daemons

nodes:a list of other ONS daemons to talk to specified as either hostnames or IP addresses plus ports

 
 
 # First three values are required

  localport=4100

  remoteport=4200

  nodes=racnode1:4200, racnode2:4200, racnode3:4200
 

What are the standard ports that ONS will listen to?

ONS only distinguishes between "local" and "remote" ports i.e., "localport=" and "remoteport=" in the ONS config. Usually, it will be 6100 and 6200. However, these do not have to be 6100 and 6200. Customer can configure these to be any port number, as long as they are consistently set up on both the ONS client and server hosts.

How to change the ONS ports?

ONS ports need to be changed at client and server side. 

Client side: Change the localport, remoteport present in the ons.config file. 

Server side: User SRVCTL command to Modify the ports used by the Oracle Notification Service daemon that is registered with Oracle Restart. 

srvctl modify ons [-l ons_local_port] [-r ons_remote_port] [-t host[:port][,host[:port]][...]] [-v]

How to monitor if ONS is running?

Use the below commands to monitor if ONS is running. 

$srvctl status nodeapps |grep ONS 

ONS is enabled 

ONS daemon is running on node: 

ONS daemon is running on node: 

ONS daemon is not running on node: 

$srvctl config nodeapps | grep ONS 

ONS exists: Local port 6100, remote port 6200, EM port 0, Uses SSL false 

ONS is enabled 

ONS is explicitly enabled on nodes: 

ONS is explicitly disabled on nodes: 

$onsctl debug or onsctl ping

UCP - Work Load Balancing

What is Work Load Balancing?

Work load balancing is distribution of work load to provide optimal performance for users and applications. In RAC aware applications, when a new node/instance is added/removed from a service, the work load should get balanced in both situations without any manual intervention. Number of database connections should get distributed between the available instances all the time.

What are Load Balancing Advisories?

RAC, GDS emit load balancing advisories showing the CPU utilization of each of the active instances.