Configuring and Managing WebLogic JDBC

Configuring WebLogic JDBC Resources

The following sections describe WebLogic JDBC resources, how they are configured, and how those resources apply to a WebLogic domain:

Understanding JDBC Resources in WebLogic Server

In WebLogic Server, you can configure database connectivity by configuring JDBC data sources and multi data sources and then targeting or deploying the JDBC resources to servers or clusters in your WebLogic domain.

Each data source that you configure contains a pool of database connections that are created when the data source instance is created—when it is deployed or targeted, or at server startup. Applications lookup a data source on the JNDI tree or in the local application context (java:comp/env), depending on how you configure and deploy the object, and then request a database connection. When finished with the connection, the application calls connection.close(), which returns the connection to the connection pool in the data source.

Figure 2-1 shows a data source and a multi data source targeted to a WebLogic Server instance.

Figure 2-1 JDBC Data Source Architecture

JDBC Data Source Architecture

For more information about data sources in WebLogic Server, see Configuring JDBC Data Sources.

A multi data source is an abstraction around a data sources that provides load balancing or failover processing between the data sources associated with the multi data source. Multi data sources are bound to the JNDI tree or local application context just like data sources are bound to the JNDI tree. Applications lookup a multi data source on the JNDI tree or in the local application context (java:comp/env) just like they do for data sources, and then request a database connection. The multi data source determines which data source to use to satisfy the request depending on the algorithm selected in the multi data source configuration: load balancing or failover. For more information about multi data sources, see Configuring JDBC Multi Data Sources.

Ownership of Configured JDBC Resources

A key to understanding WebLogic JDBC configuration and management is that who creates a JDBC resource or how a JDBC resource is created determines how a resource is deployed and modified. Both WebLogic Administrators and programmers can create JDBC resources:

WebLogic Administrators typically use the Administration Console or the WebLogic Scripting Tool (WLST) to create and deploy (target) JDBC modules. These JDBC modules are considered system modules. See JDBC System Modules for more details.
Programmers create modules in a development tool that supports creating an XML descriptor file, then package the JDBC modules with an application and pass the application to a WebLogic Administrator to deploy. These JDBC modules are considered application modules. See JDBC Application Modules for more details.

Table 2-1 lists the JDBC module types and how they can be configured and modified.

Table 2-1 JDBC Module Types and Configuration and Management Options

Module Type	Created with	Add/Remove Modules with Administration Console	Modify with JMX (remotely)	Modify with JSR-88 (non-remotely)	Modify with Administration Console
System	Administration Console or WLST	Yes	Yes	No	Yes—via JMX
Application	WebLogic Workshop, another IDE, or an XML editor	No	No	Yes—via a deployment plan	Yes—via a deployment plan

JDBC Configuration Files

WebLogic JDBC configuration is stored in XML documents that conform to the weblogic-jdbc.xsd schema (available at http://www.bea.com/ns/weblogic/91/weblogic-jdbc.xsd). You create and manage JDBC resources either as system modules or as application modules. JDBC application modules are a WebLogic-specific extension of J2EE modules and can be configured either within a J2EE application or as stand-alone modules.

Regardless of whether you are using JDBC system modules or JDBC application modules, each JDBC data source or multi data source is represented by an XML file (a module).

JDBC System Modules

When you create a JDBC resource (data source or multi data source) using the Administration Console or using the WebLogic Scripting Tool (WLST), WebLogic Server creates a JDBC module in the config/jdbc subdirectory of the domain directory, and adds a reference to the module in the domain's config.xml file. The JDBC module conforms to the weblogic-jdbc.xsd schema (available at http://www.bea.com/ns/weblogic/91/weblogic-jdbc.xsd).

JDBC resources that you configure this way are considered system modules. System modules are owned by an Administrator, who can delete, modify, or add similar resources at any time. System modules are globally available for targeting to servers and clusters configured in the domain, and therefore are available to all applications deployed on the same targets and to client applications. System modules are also accessible through JMX as JDBCSystemResourceMBeans.

Data source system modules are included in the domain's config.xml file as a JDBCSystemResource element, which includes the name of the JDBC module file and the list of target servers and clusters on which the module is deployed. Figure 2-2 shows an example of a data source listing in a config.xml file and the module that it maps to.

Figure 2-2 Reference from config.xml to a Data Source System Module

Reference from config.xml to a Data Source System Module

In this illustration, the config.xml file lists the examples-demo data source as a jdbc-system-resource element, which maps to the examples-demo.xml module in the domain\config\jdbc folder.

Similarly, multi data source system modules are included in the domain's config.xml file as a jdbc-system-resource element. The multi data source module includes a data-source-list parameter that maps to the data source modules used by the multi data source. The individual data source modules are also included in the config.xml. Figure 2-3 shows the relationship between elements in the config.xml file and the system modules in the config/jdbc directory.

Figure 2-3 Reference from config.xml to Multi Data Source and Data Source System Modules

Reference from config.xml to Multi Data Source and Data Source System Modules

In this illustration, the config.xml file lists three JDBC modules—one multi data source and the two data sources used by the multi data source, which are also listed within the multi data source module. Your application can look up any of these modules on the JNDI tree and request a database connection. If you look up the multi data source, the multi data source determines which of the other data sources to use to supply the database connection, depending on the data sources in the data-source-list parameter, the order in which the data sources are listed, and the algorithm specified in the algorithm-type parameter. For more information about multi data sources, see Configuring JDBC Multi Data Sources.

JDBC Application Modules

JDBC resources can also be managed as application modules, similar to standard J2EE modules. A JDBC application module is simply an XML file that conforms to the weblogic-jdbc.xsd schema and represents a data source or a multi data source.

JDBC modules can be included as part of an Enterprise Application as a packaged module. Packaged modules are bundled with an EAR or exploded EAR directory, and are referenced in all appropriate deployment descriptors, such as the weblogic-application.xml and ejb-jar.xml deployment descriptors. The JDBC module is deployed along with the enterprise application, and can be configured to be available only to the enclosing application or to all applications. Using packaged modules ensures that an application always has access to required resources and simplifies the process of moving the application into new environments. With packaged JDBC modules, you can migrate your application and the required JDBC configuration from environment to environment, such as from a testing environment to a production environment, without opening an EAR file and without extensive manual JDBC reconfiguration.

In contrast to system resource modules, JDBC modules that are packaged with an application are owned by the developer who created and packaged the module, rather than the Administrator who deploys the module. This means that the Administrator has more limited control over packaged modules. When deploying a resource module, an Administrator can change resource properties that were specified in the module, but the Administrator cannot add or delete modules. (As with other J2EE modules, deployment configuration changes for a resource module are stored in a deployment plan for the module, leaving the original module untouched.)

By definition, packaged JDBC modules are included in an enterprise application, and therefore are deployed when you deploy the enterprise application. For more information about deploying applications with packaged JDBC modules, see Deploying Applications to WebLogic Server.

A JDBC application module can also be deployed as a stand-alone resource using the weblogic.Deployer utility or the Administration Console, in which case the resource is typically available to the server or cluster targeted during the deployment process. JDBC resources deployed in this manner are called stand-along modules and can be reconfigured using the Administration Console or a JSR-88 compliant tool, but are unavailable through JMX or WLST.

Stand-alone JDBC modules promote sharing and portability of JDBC resources. You can create a data source configuration and distribute it to other developers. Stand-alone JDBC modules can also be used to move JDBC configuration between domains, such as between the development domain and the staging domain.

For more information about JDBC application modules, see Configuring JDBC Application Modules for Deployment.

For information about deploying stand-alone JDBC modules, see "Deploying JDBC, JMS, WLDF Application Modules."

JDBC Module File Naming Requirements

All WebLogic JDBC module files must end with the -jdbc.xml suffix, such as examples-demo-jdbc.xml. WebLogic Server checks the file name when you deploy the module. If the file does not end in -jdbc.xml, the deployment will fail and the server will not boot.

JDBC Modules in Versioned Applications

When you use production redeployment (versioning) to deploy a version of an application that includes a packaged JDBC module, WebLogic Server identifies the data source defined in the JDBC module with a name in the following format:

application_id#version_id@module_name@data_source_name

This name is used for data source runtime MBeans and for registering the data source instance with the WebLogic Server transaction manager.

If transactions in a retiring version of an application time out and the version of the application is then undeployed, you may have to manually resolve any pending or incomplete transactions on the data source in the retired version of the application. After a data source is undeployed (in this case, with the retired version of the application), the WebLogic Server transaction manager cannot recover pending or incomplete transactions.

For more information about production redeployment, see:

"Developing Applications for Production Redeployment" in Developing Applications with WebLogic Server
"Using Production Redeployment to Update Applications" in Deploying Applications to WebLogic Server

JDBC Schema

In support of the modular deployment model for JDBC resources in WebLogic Server 9.1, BEA provides a schema for WebLogic JDBC objects: weblogic-jdbc.xsd. When you create JDBC resource modules (descriptors), the modules must conform to the schema. IDEs and other tools can validate JDBC resource modules based on the schema.

The schema is available at http://www.bea.com/ns/weblogic/91/weblogic-jdbc.xsd.

JMX and WLST Access for JDBC Resources

When you create JDBC resources using the Administration Console or WLST, WebLogic Server creates MBeans (Managed Beans) for each of the resources. You can then access these MBeans using JMX or the WebLogic Scripting Tool (WLST). See Developing Custom Management Utilities with JMX and WebLogic Scripting Tool for more information.

JDBC MBeans for System Resources

Figure 2-4 shows the hierarchy of the MBeans for JDBC objects in a WebLogic domain.

Figure 2-4 JDBC Bean Tree

JDBC Bean Tree

The JDBCSystemResourceMBean is a container for the JavaBeans created from a data source module. However, all JMX access for a JDBC data source is through the JDBCSystemResourceMBean. You cannot directly access the individual JavaBeans created from the data source module.

JDBC Management Objects in the J2EE Management Model (JSR-77 Support)

WebLogic Server 9.1 JDBC supports JSR-77, which defines the J2EE Management Model. The J2EE Management Model is used for monitoring the runtime state of a J2EE Web application server and its resources. You can access the J2EE Management Model to monitor resources, including the WebLogic JDBC system as a whole, JDBC drivers loaded into memory, and JDBC data sources.

To comply with the specification, BEA added the following runtime MBean types for WebLogic JDBC:

JDBCServiceRuntimeMBean—Which represents the JDBC subsystem and provides methods to access the list of JDBCDriverRuntimeMBeans and JDBCDataSourceRuntimeMBeans currently available in the system.
JDBCDriverRuntimeMBean—Which represents a JDBC driver that the server loaded into memory.
JDBCDataSourceRuntimeMBeans—Which represents a JDBC data source deployed on a server or cluster.

Note: WebLogic JDBC runtime MBeans do not implement the optional Statistics Provider interfaces specified by JSR-77.

For more information about using the J2EE management model with WebLogic Server, see Monitoring and Managing with the J2EE Management APIs.

Using WLST to Create JDBC System Resources

Basic tasks you need to perform when creating JDBC resources with the WLST are:

Start an edit session.
Create a JDBC system module that includes JDBC system resources, such as pools, datasources, multi datasources, and JDBC drivers.
Target your JDBC system module.

Listing 2-1 WLST Script to Create JDBC Resources

#----------------------------------------------------------------------
# Create JDBC
# The prefix specifies the prefix on property names.
#  Example: for property "mypool.Name=mypool", the prefix would be "mypool."
#----------------------------------------------------------------------

import sys
from java.lang import System

print "@@@ Starting the script ..."
global props

url = sys.argv[1]
usr = sys.argv[2]
password = sys.argv[3]

connect(usr,password, url)
edit()
startEdit()

servermb=getMBean("Servers/examplesServer")
   if servermb is None:
      print '@@@ No server MBean found'
else:

   def addJDBC(prefix):

   print("")
	   print("*** Creating JDBC with property prefix " + prefix)

	# Create the Connection Pool.  The system resource will have
	# generated name of <PoolName>+"-jdbc"

	   myResourceName = props.getProperty(prefix+"PoolName")
	   print("Here is the Resource Name: " + myResourceName)

	   jdbcSystemResource = wl.create(myResourceName,"JDBCSystemResource")
   	myFile = jdbcSystemResource.getDescriptorFileName()
	   print ("HERE IS THE JDBC FILE NAME: " + myFile)
	
   	jdbcResource = jdbcSystemResource.getJDBCResource()
	   jdbcResource.setName(props.getProperty(prefix+"PoolName"))

	# Create the DataSource Params
	   dpBean = jdbcResource.getJDBCDataSourceParams()
	   myName=props.getProperty(prefix+"JNDIName")
   dpBean.setJNDINames([myName])

	# Create the Driver Params
	   drBean = jdbcResource.getJDBCDriverParams()
	   drBean.setPassword(props.getProperty(prefix+"Password"))
	   drBean.setUrl(props.getProperty(prefix+"URLName"))
	   drBean.setDriverName(props.getProperty(prefix+"DriverName"))

	   propBean = drBean.getProperties()
	   driverProps = Properties()
	   driverProps.setProperty("user",props.getProperty(prefix+"UserName"))

	   e = driverProps.propertyNames()
	   while e.hasMoreElements() :
		      propName = e.nextElement()
		      myBean = propBean.createProperty(propName)
		      myBean.setValue(driverProps.getProperty(propName))

	# Create the ConnectionPool Params
	   ppBean = jdbcResource.getJDBCConnectionPoolParams()
	   ppBean.setInitialCapacity(int(props.getProperty(prefix+"InitialCapacity")))
	   ppBean.setMaxCapacity(int(props.getProperty(prefix+"MaxCapacity")))
	   ppBean.setCapacityIncrement(int(props.getProperty(prefix+"CapacityIncrement")))

	   if not props.getProperty(prefix+"ShrinkPeriodMinutes") == None:
      ppBean.setShrinkFrequencySeconds(int(props.getProperty(prefix+"ShrinkPeriodMinutes")))
			   if not props.getProperty(prefix+"TestTableName") == None:
		      ppBean.setTestTableName(props.getProperty(prefix+"TestTableName"))

	   if not props.getProperty(prefix+"LoginDelaySeconds") == None:
      ppBean.setLoginDelaySeconds(int(props.getProperty(prefix+"LoginDelaySeconds")))

	# Adding KeepXaConnTillTxComplete to help with in-doubt transactions.
	   xaParams = jdbcResource.getJDBCXAParams()
	   xaParams.setKeepXaConnTillTxComplete(1)

	# Add Target
	   jdbcSystemResource.addTarget(wl.getMBean("/Servers/examplesServer"))
.
.
.

How to Modify and Monitor JDBC Resources

You can modify or monitor JDBC objects and attributes by using the appropriate method available from the MBean.

You can modify JDBC objects and attributes using the set, target, untarget, and delete methods.
You can monitor JDBC runtime objects using get methods.

For more information, see Navigating and Editing MBeans in the WebLogic Scripting Tool.

Best Practices when Using WLST to Configure JDBC

This section provides best practices information when using WLST to configure JDBC resources:

Trap for Null MBean objects (such as pools, datasources, drivers) before trying to manipulate the MBean object.
BEA provides sample scripts and utilities to configure WebLogic domain resources using WLST Offline and/or WLST Online. For more information, see the wlst Project Home.

Overview of Clustered JDBC

You can target or deploy JDBC resources to a cluster to improve the availability of cluster-hosted applications. For information about JDBC objects in a clustered environment, see "JDBC Connections" in Using WebLogic Server Clusters.

Multi data sources are supported for use in clusters. However, note that multi data sources can only use data sources in the same JVM. Multi data sources cannot use data sources from other cluster members.