X

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

  • November 13, 2015

WLS UCP Datasource

Stephen Felts
Manager

WebLogic Server (WLS) 12.2.1 introduces 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 http://docs.oracle.com/middleware/1221/wls/JDBCA/ucp_datasources.htm#JDBCA746 .  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.  With respect to multi-tenancy, these system resources can be defined at the domain, partition, resource group template, or resource group level. 

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.PoolDaaSourceImpl) 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 all of the UCP attributes that are currently supported, based on the 12.1.0.2 UCP jar that ships with WLS 12.2.1.

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.

The administration console and FMWC make 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 (Global or Multi Tenant Partition, Resource Group, or Resource Group Template) 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

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

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.

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 overview https://docs.oracle.com/database/121/JJUCP/intro.htm#JJUCP8109 .  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 or one of the GUIs.  Pick up the example with getting the connection as above.




Join the discussion

Comments ( 3 )
  • 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!


Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha