JDBC System Modules
When you create a JDBC resource (data source) using the WebLogic
Server Administration Console or using the WebLogic Scripting Tool (WLST),
WebLogic Server creates a JDBC module in the
subdirectory of the domain directory and adds a reference to the module in
The JDBC module conforms to the
JDBC data sources that you configure this way are known as system modules.
Administrator owns the system modules and can delete, modify, or
add similar resources at any time. System modules are globally
available for targeting 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
Generic Data Source Modules
Generic data source system modules are included in the
config.xml file as a
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-1 shows an example of a data source listing in a
config.xml file and the module that it maps to.
Generic is the term used to distinguish a simple data source from a Multi Data Source or Active GridLink data source.
Figure 2-1 Reference from config.xml to a Data Source System Module
Description of "Figure 2-1 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-jdbc.xml module in the
Active GridLink Data Source System Modules
Active GridLink data source system modules are included
in the domain's
config.xml file as a
JDBCSystemResource element, similar to Generic data source system modules. Active GridLink data sources include a
jdbc-oracle-params section that
For more information about Active GridLink data sources, see Using Active GridLink Data Sources.
Multi Data Source System Modules
Similarly, Multi Data Source (MDS) system modules are included in the domain's
file as a
jdbc-system-resource element. The MDS module includes a
data-source-list parameter that maps to
the data source modules used by the MDS. The individual data
source modules are also included in the
config.xml. Figure 2-2 shows the relationship between elements in the
config.xml file and the system modules in the
Figure 2-2 Reference from config.xml to Multi Data Source and Data Source System Modules
Description of "Figure 2-2 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 MDS and the two Generic
data sources used by the MDS, which are also listed within
the MDS module. Your application can look up any of these
modules on the JNDI tree and request a database connection. If you look up the MDS, the MDS determines which of
the Generic 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
Members of a MDS must be Generic data sources; they cannot be MDS or Active GridLink data sources.
For more information about MDS, see Configuring JDBC Multi Data Sources.
JDBC Application Modules
In contrast to system resource modules, the developer creates, packs, and owns the JDBC modules whereas the Administrator only deploys the module.
This means that the Administrator has limited control over packaged modules. When deploying a resource module, an Administrator can change the specified resource properties in the module, but the Administrator cannot add or delete modules. (As with other Java EE modules, deployment configuration changes for a resource module are stored in a deployment plan for the module, leaving the original module untouched.)
Standard Java EE Application Modules
Java EE 7 provides the option to programmatically define
resources as application modules for a more flexible and portable method of database
connectivity. See Using DataSource Resource Definitions in Developing JDBC Applications for Oracle WebLogic Server.
Proprietary JDBC Application Modules
JDBC resources can also be managed as application modules, similar to standard Java EE modules. A proprietary JDBC application module is simply an XML file that conforms to the
jdbc-data-source.xsd schema (available at
http://www.oracle.com/webfolder/technetwork/weblogic/jdbc-data-source/index.html) and represents a 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
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 data source reconfiguration.
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 Oracle WebLogic Server.
A proprietary JDBC application module can also be deployed as a stand-alone resource using the
weblogic.Deployer utility or the WebLogic Server 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-alone modules and can be reconfigured using the WebLogic Server 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 data source configuration between domains, such as between the development domain and the staging domain.
When deploying proprietary JDBC modules as standalone modules, a Multi Data Source needs to have a deployment order that is greater than the deployment orders of its member Generic data sources.
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, and WLDF Application Modules in Deploying Applications to Oracle WebLogic Server.
Including Drivers in EAR/WAR Files
In WebLogic Server 10.3.6 and higher releases, you can include a database driver in the
APP-INF/lib directory of the EAR/WAR file that contains a packaged data source. This allows you to deploy a self-contained EAR/WAR file that has both the data source and driver required for an application.
You do not need to update the
classpath of the manifest file to
include the driver location.
An EAR has its own classloader and it is shared across all of the nested applications
so any of them can use it. You can deploy multiple EAR/WAR files, each with a different
driver version. However, if there are other versions of the driver in the system
weblogic.xml file to ensure that the application uses the driver
classes that it was packaged with which it was packaged.
When using the Oracle driver embedded in an EAR or WAR with
ojdbc7.jar, there is a known problem related to cleaning up the associated classloader. To resolve this problem, call
oracle.jdbc.OracleDriver.deregisterHack() from the
contextDestroyed() method of a
You can also use the
WEB-INF/lib directory to hold driver JAR files. The following example shows the location of the various directories in WAR and EAR files.
Application (ear) Web module (war) WEB-INF/lib EJB module META-INF APP-INF/lib
However, you cannot have two versions of the same JAR in both
DOMAIN_HOME/lib (see Using a Third-Party JAR File in DOMAIN_HOME/lib or the system classpath and
prefer-application-packages set. That is, you should do only one of
classpathto get the driver into all applications in the domain.
Use the driver embedded in the application.
Note:If you do not adhere to this restriction, it is possible (depending on the JAR, the version changes, and the order in which the JARs are referenced) that a
ClassCastExceptionwill occur in the application.
If the JAR files are present in multiple locations, the following rules apply:
weblogic.xmlis false, the precedence is:
weblogic.xmlis true, the classes in
WEB-INF/libwill take precedence over all other locations.
JDBC Module File Naming Requirements
All WebLogic JDBC module files must end with the
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
JDBC Modules in Versioned Applications
WebLogic Server identifies the data source defined in the JDBC module with a specific name.
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:
This name is used for data source run-time 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 and Using Production Redeployment to Update Applications in Deploying Applications to Oracle WebLogic Server.
In support of the modular deployment model for JDBC resources in WebLogic Server,
Oracle provides a schema for WebLogic JDBC objects:
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
The scope in the
jdbc-data-source-params element of the schema may only be set to
Application for packaged data sources. The value
Application is not valid for:
System resources in
config/jdbc, including Generic, Multi Data Sources, and Active GridLink data sources.
Stand-alone data sources that are deployed dynamically or statically using the
<app-deployment>element in the
For these data source types, there is no application to scope the data source and no
associated module. WebLogic Server does not generate a scope of
Application. This omission was not flagged as an error in
releases prior to WebLogic Server 10.3.6.0 and is displayed in the console with an
invalid name similar to
ds0@null@ds0. For WebLogic Server 10.3.6.0
and higher, an
Error message is logged for this configuration error
and the system attempts to set the scope to
Global and display the
data source name as
ds0. In future releases, this error may be
treated as fatal.
JDBC Data Source Type
Data sources should have a
datasource-type set in the descriptor.
This functionality was added in WebLogic Server 12.2.1 and is optional for backward
The valid values are:
Generic—Generic data source
MDS—Multi Data Source
AGL—Active GridLink data source
UCP—Universal Connection Pool data source
datasource-type is not set to
UCP the following validations are
datasource-typeis set to
AGL, it is treated as an Active GridLink data source even if
ONSlist is configured, and the Active GridLink flag is
datasource-typeis not set to
AGL, it is an error even if
FANenabled is true or an
ONSlist is configured or the Active GridLink flag is
If no data source list exists (it does not have Multi Data Source members) and
datasource-typeis set to anything other than
AGL, it is an error.
If the data source list exists (it has Multi Data Source members) and the
datasource-typeis set to anything other than
MDS, it is an error.
JMX and WLST Access for JDBC Resources
This section describes how to access WebLogic Server MBeans using JMX client or the WebLogic Scripting Tool (WLST).
JDBC MBeans for System Resources
Figure 2-3 shows the hierarchy of the MBeans for JDBC objects in a WebLogic domain.
Figure 2-3 JDBC Bean Tree
Description of "Figure 2-3 JDBC Bean Tree"
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 Java EE Management Model (JSR-77 Support)
The WebLogic Server JDBC subsystem supports JSR-77, which defines the Java EE Management Model. The Java EE Management Model is used for monitoring the run-time state of a Java EE Web application server and its resources. You can access the Java EE Management Model to monitor resources, including the WebLogic JDBC subsystem as a whole, JDBC drivers loaded into memory, and JDBC data sources.
To comply with the specification, Oracle added the following run-time MBean types for the WebLogic JDBC subsystem:
JDBCServiceRuntimeMBean—Which represents the JDBC subsystem and provides methods to access the list of
JDBCDataSourceRuntimeMBeanscurrently available in the system.
JDBCMultiDataSourceRuntimeMBean—Which represents a JDBC Multi Data Source deployed on a server or cluster.
JDBCDriverRuntimeMBean—Which represents a JDBC driver that the server loaded into memory.
JDBCDataSourceRuntimeMBeans—Which represents a JDBC Generic or Active GridLink data source deployed on a server or cluster.
WebLogic JDBC run-time MBeans do not implement the optional Statistics Provider interfaces specified by JSR-77.
For more information about using the Java EE management model with WebLogic Server, see Developing Java EE Management Applications for Oracle WebLogic Server.
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, data sources, Multi Data Sources, and JDBC drivers.
Target your JDBC system module.
Example 2-1 WLST Script to Create JDBC Resources
#---------------------------------------------------------------------- # Create JDBC Resources #---------------------------------------------------------------------- import sys from java.lang import System print "@@@ Starting the script ..." global props url = sys.argv usr = sys.argv password = sys.argv 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 resources 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"))) 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 run-time objects using get methods.
See Navigating MBeans (WLST Online) in Understanding the WebLogic Scripting Tool.
Best Practices when Using WLST to Configure JDBC Resources
Trap for Null MBean objects (such as pools, data sources, and drivers) before trying to manipulate the MBean object.
When using WLST offline, the following characters are not valid in names of management objects: period (.), forward slash (/), or backward slash (\). See Syntax for WLST Commands in Understanding the WebLogic Scripting Tool.
Creating High-Availability JDBC Resources
To improve the availability of your JDBC resource and load balance communication between resources you can target or deploy a JDBC data source to the members of a cluster using the WebLogic Server Administration Console.
However, connections do not failover in the event that a cluster member becomes unavailable for any reason. New connections are created as needed on available cluster members. See Deploying Data Sources on Servers and Clusters.
A Multi Data Source can only use Generic data sources that are deployed on the same cluster member (in the same JVM).