1. Administering JDBC Data Sources for Oracle WebLogic Server
  2. JDBC Data Sources Types
  3. Using Proxy Data Sources

Using Proxy Data Sources

Proxy data sources provide the ability to switch between databases in a WebLogic Server Multitenant environment.

Note:

WebLogic Server Multitenant domain partitions are deprecated in WebLogic Server 12.2.1.4.0 and will be removed in the next release. Oracle recommends that customers using domain partitions as a container dedicated to specific applications and resources consider the use of alternative container-based architectures, including the deployment of WebLogic applications and services in Docker containers running in Kubernetes clusters.

  • What is Proxy Data Source
    Applications often need a quick access to data sources by name without knowing the naming conventions, context names (partitions or tenants), and so on. Proxy data sources provide applications the access to such underlying data sources.
  • Configuring Proxy Data Source
    To create and configure Proxy data sources in your WebLogic domain, you can use the WebLogic Server Administration Console, WLST, or Fusion Middleware Control.
  • Monitoring Proxy Data Source JDBC Resources
    Monitor a Proxy data source using runtime statistics. You can view runtime statistics via the WebLogic Server Administration Console or through the JDBCProxyDataSourceRuntime MBean.

Parent topic: JDBC Data Sources Types

What is Proxy Data Source

Applications often need a quick access to data sources by name without knowing the naming conventions, context names (partitions or tenants), and so on. Proxy data sources provide applications the access to such underlying data sources.

The Proxy data source simplifies the administration of multiple data sources by providing a light-weight mechanism for accessing a data source associated with a partition or tenant. All of the significant processing happens in the data sources to which it points. That is, the underlying data sources actually handle deployment, management, security, and so on.

Proxy data source provides for WebLogic Server data source access with:

  • Minimal configuration.

  • Minimal performance overhead including no double connection pooling (for example, no pooling of connections in both the proxy and the underlying connection pool).

  • The ability to switch between replicated data sources in the WebLogic Server Multitenant environment.

  • JNDI access to a data source object.

  • A data source object that implements javax.sql.DataSource.

  • A callback interface that can be implemented to do the data source switching based on the context in the environment (for example, partition, tenant, and so on)

  • Switching configuration by the application both at the context-level used for switching (such as tenant, partition, other information in the thread) and to which data sources the switch is done.

  • Direct access to all the data sources to which it may want to switch.

Parent topic: Using Proxy Data Sources

Configuring Proxy Data Source

To create and configure Proxy data sources in your WebLogic domain, you can use the WebLogic Server Administration Console, WLST, or Fusion Middleware Control.

Procedures for creating a Proxy data source using Fusion Middleware Control are described in Create JDBC Proxy data sources in Administering Oracle WebLogic Server with Fusion Middleware Control.

When creating a Proxy data source, note the following:

  • The Proxy data source does not validate the values in the switching properties to confirm that they match the context names or data sources. If an invalid data source is specified, getting a connection will fail. However, the data sources to which the proxy points do not have to be available when configured or deployed.

  • There are no rules for the data sources to which the proxy points. In general, however, the members should basically provide the same functionality. They can be from different vendor drivers but should have the same schemas, transaction properties, and general functionality. Oracle does not assume that the underlying data sources are configured to use Oracle Container Database/Pluggable Database technology or that the data sources use an Oracle driver.

  • The proxy data source provides a javax.sql.DataSource interface. The XADataSource equivalent is not provided or necessary. The additional methods on XADataSource are necessary only for handling transaction enlistment. Transaction processing is handled at the member/real data source level instead of at the proxy level; doing it at two levels would cause problems.

  • Proxy data sources are not supported in an application-scoped environment, nor should they reference application-scoped data sources. They must be defined as system resources and targeted to server(s) and/or cluster(s) (WebLogic Server does not support targeting to a domain).

The Administration Console and WLST methods are described in the following topics:

Parent topic: Using Proxy Data Sources

Configuring a Proxy Data Source in the WebLogic Server Administration Console

The procedure for creating a Proxy data source in the WebLogic Server Administration Console is provided in Create Proxy data sources in the Oracle WebLogic Server Administration Console Online Help. This procedure includes instructions for accessing the data source configuration wizard.

The following sections provide an overview of the basics steps used in the data source configuration wizard to create a data source using the WebLogic Server Administration Console:

Set Proxy Data Source Properties

The Proxy Data Source Properties section includes options that determine the identity of the data source and the way the data is handled on a database connection. Guidelines for configuring these properties are described as follows:

  • Data Source Names— JDBC data source names are used to identify the data source within the WebLogic domain. For system resource data sources, names must be unique among all other JDBC system resources, including data sources. To avoid naming conflicts, data source names should also be unique among other configuration object names, such as servers, applications, clusters, and JMS queues, topics, and servers.

  • Scope—You cannot set the scope for Proxy data sources.

  • JNDI Names— You can configure a data source so that it binds to the JNDI tree with a single name or multiple names. You can use a multi-JNDI-named data source in place of legacy configurations that included multiple data sources that pointed to a single JDBC connection pool. For more information, see Developing JNDI Applications for Oracle WebLogic Server.

  • Switching Properties—Enter the switching properties to be passed to the switching callback method for the Proxy data source. This value is dependent on the requirements of the switching callback. For the default switching callback, the format of the proxy switching properties is partition1=datasource1;partition2=datasource2;...;default=datasourcen. It is passed to the second argument of getDataSource() in the switching callback.

    The default WebLogic Server implementation uses the current partition to look up the data source in the switching properties. If it is not in a partition, the partition value is DOMAIN. If no match is found or it is not in a partition, the data source associated with default is used. If a default value is not appropriate, then do not provide a default value and a null is returned. The default callback can only be used within the WebLogic Server.

  • Switching Callback—Enter the name of the proxy switching callback class. To use the default callback, leave this value empty. If you specify a callback class, it must implement the weblogic.jdbc.extensions.DataSourceSwitchingCallback interface. This interface has one method that takes two parameters. The format of the two parameters depends on the implementation. The first parameter, which is a comma-separated list of JNDI names for the proxy data source, is not used in the default callback. The second parameter is described above in the Switching Properties.

Select Target

You can select one or more targets to which to deploy your new Proxy 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.

Parent topic: Configuring Proxy Data Source

Configuring a Proxy Data Source Using WLST

You can create a Proxy data source using WLST in the same way that you create other data source types. However, Proxy data sources require less attributes.

The configuration elements for a Proxy data source are as follows.

  • name

  • datasource-type=PROXY

  • jdbc-data-source-params proxy-switching-properties—A string that defines how the switching is done. This value is optional and is null if not specified. This value is configurable and dynamic.

  • jdbc-data-source-params proxy-switching-callback—A string that defines the name of a class that implements weblogic.jdbc.extensions.DataSourceSwitchingCallback. This value is optional and a default callback class will be used for WebLogic Server. This value is configurable and dynamic.

  • jdbc-data-source-params jndi-name—An array of String names at which the data source is mapped into the WebLogic Server (Java EE) JNDI. In addition to other naming conventions regarding JNDI names, JNDI name(s) for the proxy data source must not contain a comma (,).

No other elements from the WebLogic Server data source descriptor are recognized. If other elements are specified, they are ignored.

A sample WLST script for creating a Proxy data source is provided in Example 4-3

Example 4-3 Sample WLST Script to Create a Proxy Data Source

import sys, socket
import os
hostname = socket.gethostname()
connect("username","password","t3://"+hostname+":7001")
edit()
startEdit()
serverName="AdminServer"
serverBean = getMBean('/Servers/'+serverName)
host='%s.us.example.com' %hostname
print 'Creating Proxy datasource'
domain = getMBean("/")
startEdit()
resourceName='proxyDS'
print "Creating data source in domain"
systemResource=domain.createJDBCSystemResource(resourceName)
systemResource.setName(resourceName)
jdbcResource=systemResource.getJDBCResource()
jdbcResource.setName(resourceName)
jdbcResource.setDatasourceType('PROXY')
jdbcDataSourceParams=jdbcResource.getJDBCDataSourceParams()
jdbcDataSourceParams.addJNDIName(resourceName)
jdbcDataSourceParams.setProxySwitchingProperties('partition1=partition1:ds;default=domain:ds')
cd('/SystemResources/' + resourceName )
set('Targets',jarray.array([ObjectName('com.bea:Name=' + serverName + ',Type=Server')], ObjectName))
save()
activate()

Note:

You can also use the sample WLST script for creating a Generic data source that is provided with WebLogic Server as the basis for your Proxy data source:
EXAMPLES_HOME\wl_server\examples\src\examples\wlst\online\jdbc_data_source_creation.py

where EXAMPLES_HOME represents the directory in which the WebLogic Server code examples are configured. See WLST Online Sample Scripts in Understanding the WebLogic Scripting Tool.

Parent topic: Configuring Proxy Data Source

Monitoring Proxy Data Source JDBC Resources

Monitor a Proxy data source using runtime statistics. You can view runtime statistics via the WebLogic Server Administration Console or through the JDBCProxyDataSourceRuntime MBean.

The JDBCProxyDataSourceRuntimeMBean extends the JDBCDataSourceRuntimeMBean so that it can be returned with the list of other JDBC MBeans from the JDBC service for tools such as the WebLogic Server Administration Console. For a PROXY data source, it sets the state. All runtime statistics such as active connections and so on are not set (they will be set to -1).

In addition to runtime statistics, the testPool() operation returns null if the test is a success. Otherwise it returns an error string (similar to other data source types). The rest of the operations take no action.

See JDBCProxyDataSourceRuntimeMBean in the MBean Reference for Oracle WebLogic Server.

For JDBC monitoring, see Monitoring WebLogic JDBC Resources.

Parent topic: Using Proxy Data Sources