X

Proactive insights, news and tips from Oracle WebLogic Server Support. Learn Oracle from Oracle.

WLS UCP Datasource

Stephen Felts
Manager

WebLogic Server UCP Data Source Type

WebLogic Server (WLS) 12.2.1 introduced a new datasource type that uses the Oracle Universal Connection Pool (UCP) as an alternative connection pool.  The UCP datasource allows for configuration, deployment, and monitoring of the UCP connection pool as part of the WLS domain.  It is certified with the Oracle Thin driver (simple, XA, and replay drivers). 

The product documentation is at https://docs.oracle.com/en/middleware/fusion-middleware/weblogic-server/12.2.1.4/jdbca/ucp_datasources.html .  The goal of this article  is not to reproduce that information but to summarize the feature and provide some additional information and screen shots for configuring the datasource.

A UCP data source is defined using a jdbc-data-source descriptor as a system resource. The configuration  for a UCP data source is pretty simple with the standard datasource parameters.  You can  name it, give it a URL, user, password and JNDI name.  Most of the detailed configuration and tuning comes in the form of UCP connection properties.  The administrator can configure values for any setters supported by oracle.ucp.jdbc.PoolDataSourceImpl except LogWriter  (see
oracle.ucp.jdbc.PoolDataSourceImpl) by just removing the "set" from the attribute name (the names are case insensitive).  For example,

ConnectionHarvestMaxCount=3

Table 8-2 in the documentation lists more UCP attributes.

There is some built-in validation of the (common sense) combinations of driver and connection factory:

Driver

Factory (ConnectionFactoryClassName)

oracle.ucp.jdbc.PoolDataSourceImpl (default)

oracle.jdbc.pool.OracleDataSource

oracle.ucp.jdbc.PoolXADataSourceImpl

oracle.jdbc.xa.client.OracleXADataSource

oracle.ucp.jdbc.PoolDataSourceImpl

oracle.jdbc.replay.OracleDataSourceImpl

 

To simplify the configuration, if the "driver-name" is not specified, it will default to oracle.ucp.jdbc.PoolDataSourceImpl and the ConnectionFactoryClassName connection property defaults to the corresponding entry from the above table.

Example 8.1 in the product documentation gives a complete example of creating a UCP data source using WLST.   WLST usage is very common for application configuration these days.

Monitoring is available via the weblogic.management.runtime.JDBCUCPDataSourceRuntimeMBean.  This MBean extends JDBCDataSourceRuntimeMBean so that it can be returned with the list of other JDBC MBeans from the JDBC service for tools like the administration console or your WLST script.  For a UCP data source, the state and the following attributes are set: CurrCapacity, ActiveConnectionsCurrentCount, NumAvailable, ReserveRequestCount, ActiveConnectionsAverageCount, CurrCapacityHighCount, ConnectionsTotalCount, NumUnavailable, and WaitingForConnectionSuccessTotal.

Creating a WLS UCP Data Source Using the Administration Console

The WLS administration console makes it easy to create, update, and monitor UCP datasources.

The following images are from the administration console. For the creation path, there is a drop-down that lists the data source types; UCP is one of the choices.  The resulting data source descriptor datasource-type set to "UCP". 

http://aseng-wiki.us.oracle.com/asengwiki/download/attachments/643530931/ucp1.jpg?version=3&modificationDate=1443495917000&api=v2

The first step is to specify the JDBC Data Source Properties that determine the identity of the data source. They include the datasource names, the scope (stick with Global) and the JNDI names. 

http://aseng-wiki.us.oracle.com/asengwiki/download/attachments/643530931/ucp2.jpg?version=3&modificationDate=1443495999000&api=v2

The next page handles the user name and password, URL, and additional connection properties. Additional connection properties are used to configure the UCP connection pool. There are two ways to provide the connection properties for a UCP data source in the console. On the Connection Properties page, all of the available connection properties for the UCP driver are displayed so that you only need to enter the property value.  On the next page for Test Database Connection, you can enter a propertyName=value directly into the Properties text box.  Any values entered on the previous Connection Properties page will already appear in the text box.  This page can be used to test the specified values including the connection properties.

http://aseng-wiki.us.oracle.com/asengwiki/download/attachments/643530931/ucp5.jpg?version=1&modificationDate=1443496172000&api=v2

The Test Database Connection page allows you to enter free-form values for properties and test a database connection before the data source configuration is finalized. If necessary, you can provide additional configuration information using the Properties, System Properties, and Encrypted Properties attributes.

http://aseng-wiki.us.oracle.com/asengwiki/download/attachments/643530931/ucp3.jpg?version=1&modificationDate=1404361954000&api=v2

When using the Oracle 18c or later, the recommended URL should include CONNECT_TIMEOUT, RETRY_COUNT, RETRY_DELAY, and TRANSPORT_CONNECT_TIMEOUT, as in the following example (white space is for readability only):

alias =(DESCRIPTION =
   (CONNECT_TIMEOUT=90)  (RETRY_COUNT=20)(RETRY_DELAY=3) (TRANSPORT_CONNECT_TIMEOUT=3) 
     (ADDRESS_LIST =
         (LOAD_BALANCE=on)
         ( ADDRESS = (PROTOCOL = TCP)(HOST=primary-scan)(PORT=1521)))
      (ADDRESS_LIST =
         (LOAD_BALANCE=on)
         ( ADDRESS = (PROTOCOL = TCP)(HOST=secondary-scan)(PORT=1521)))       
    (CONNECT_DATA=(SERVICE_NAME = myservice)))

This URL has two RAC clusters that each have a SCAN address (connected via Active Data Guard or GoldenGate).  For a single RAC cluster, it would only have a single ADDRESS_LIST.

The final step is to target the data source. You can select one or more targets to which to deploy your new UCP data source. If you don't select a target, the data source will be created but not deployed. You will need to deploy the data source at a later time before you can get a connection in the application.

For editing the data source, minimal tabs and attributes are exposed to configure, target, and monitor this data source type. 

http://aseng-wiki.us.oracle.com/asengwiki/download/attachments/643530931/ucp4.jpg?version=1&modificationDate=1404361954000&api=v2

Creating a WLS UCP Data Source Using the FMW Console

The capabilities in FMWC are similar to the administrative console but with a different look and feel.

If you select JDBC Data Sources from the WebLogic Domain drop-down, you will see a list of existing data sources with their associated data source type, scope, and if applicable RG, RGT and Partition.

http://aseng-wiki.us.oracle.com/asengwiki/download/attachments/643530931/ucp2fmwc.jpg?version=1&modificationDate=1443495602000&api=v2

Selecting an existing DS name brings up a page to edit the DS.

Selecting a resource group name (if it exists) brings up a page to edit the RG.

Selecting a partition name of an existing data source brings up a page to edit the Partition attributes.

Selecting Create displays a data source type drop-down where you can select UCP Data Source.

The first page of the UCP creation requires the data source name, scope, JNDI names(s), and selecting a driver class name.

http://aseng-wiki.us.oracle.com/asengwiki/download/attachments/643530931/ucp3fmwc.jpg?version=1&modificationDate=1443495682000&api=v2

Connection properties are input on the next page.  Unlike the administration console, the UCP connection properties are not listed.  You must add a new entry by selecting "+", type in the property name, and then enter the value.  This page is also used to test the database connection.

The final page in the creation sequence allows for targeting the data source and creating the new object.

Application Development with a UCP Data Source

Once you have your datasource configured and deployed, you access it using a JNDI lookup in your application, as with other WLS datasource types.

import javax.naming.Context;
import javax.naming.InitialContext;
import java.sql.Connection;
import oracle.ucp.jdbc.PoolDataSource;

Context ctx = new InitialContext();
PoolDataSource pds = (PoolDataSource) ctx.lookup("ucpDS");
Connection conn = pds.getConnection();.

While the usage in the application looks similar to other WLS datasources, you don't have all of the features of a WLS datasource but you get additional features that the UCP connection pool supports.  Note that there is no integration of the UCP datasource with WLS security or JTA transactions.  UCP has it's own JMX management.    Start at this link for the UCP Introduction .  When you see examples that execute PoolDataSourceFactory.getPoolDataSource() and then call several setters on the datasource, this is replaced with configuring the UCP datasource in WLST, REST, or the administration console.  Pick up the example with getting the connection as above.

Using a WLS UCP Data Source vs UCP Directly

It's possible to write an application using the UCP API's directly within a WLS application.  There are several advantages to using the WLS UCP data source within a WLS application and framework.

1. Configuration is done using the mechanism that is used for all WLS datasources. 

2. It takes the configuration, and deployment (creation) out of the java code.  Further, the deploy and undeploy can be controlled using the WLS administration mechanisms (administration console, WLST, REST).

3. It provides for monitoring using the WLS monitoring mechanisms (administration console, WLST, REST).

All of the features in UCP are available including advanced features such as Sharding, draining, and Transparent Application Continuity (TAC).. 

Using the example above, sharding can be introduced easily as follows.

// Create a key corresponding to sharding key columns, to access the correct shard
OracleShardingKey key = pds.createShardingKeyBuilder().subkey(100, JDBCType.NUMERIC).build();
// Fetch a connection to the shard corresponding to the key
Connection conn = pds.createconnectionBuilder().shardingKey(key).build(); 

Draining and TAC are transparent to the application.

Using a WLS UCP Data Source vs Active GridLink Data Source

UCP and Active GridLink (AGL) both are well integrated with support of Oracle RAC databases.  That is, they can handle Fast Application Notification (FAN) events and use connections on the active nodes, support planned and unplanned database outages, handle Transparent Application Continuity (TAC), etc.

AGL has the advantage that it is tightly integrated with WLS.  If you want to do XA transactions, you need to use AGL.  AGL supports WLS Transaction Management (one-phase, LLR, JTS, JDBC TLog, determiner resource, and so on), additional life cycle operations (suspend, resume, shutdown, forced shutdown, start, and so on), WLS security options and integration,  and WLS data operations such as JMS, Leasing, EJB, and so on.

Using AGL requires an Oracle WebLogic Server Suite license.

 

Join the discussion

Comments ( 5 )
  • Alex Friday, November 13, 2015

    What are the benefits compared to other DS types?


  • Steve Felts Friday, November 13, 2015

    That's a tricky question (and I would tend to be biased to the WLS pool).

    It's likely that UCP has less overhead because it has less integration. It used to be that the WLS pool scaled much better but I don't know of any recent comparisons.

    Here's a concrete example from a recent customer interaction. The customer is running with the database 12.2 beta. They prefixed the WLS classpath with the ojdbc8 and ucp jars from 12.2. When using the UCP datasource, they can use sharding. The WLS datasource doesn't support sharding yet.


  • Jean de Lavarene Friday, November 13, 2015

    Very nice article and great feature Steve! Thanks!


  • Nagashree Thursday, December 12, 2019
    I have an issue with the UCP Datasource .In one of the service , i could see that connection pool are all in use for UCP .But i don't see any UCP type of datasources in the domain .Please assist how exactly can i recognize the UCP datasource ?
  • Stephen Felts Tuesday, October 27, 2020
    In the WebLogic Server administration console, UCP datasources are tagged with "UCP", as seen in the figures above.
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.