Configuring and Managing WebLogic JDBC
When you package your enterprise application, you can include JDBC resources in the application by packaging JDBC modules in the archive and adding references to the JDBC modules in all applicable descriptor files. When you deploy the application, the JDBC resources are deployed, too. Depending on how you configure the JDBC modules, the JDBC data sources deployed with the application will either be restricted for use only by the containing application (application-scoped modules) or will be available to all applications and clients (globally-scoped modules).
You can create JDBC application modules using any development tool that supports creating an XML descriptor file. You then deploy and manage JDBC modules using JSR 88-based tools, such as the
weblogic.Deployer utility, or the Administration Console.
Note: You can create a JDBC data source using the Administration Console, then copy the module as a template for use in your applications. You must change the
jndi-name elements of the module before deploying it with your application to avoid a naming conflict in the namespace.
Each JDBC module represents a data source or a multi data source. Modules that represent a data source include all of the configuration parameters for the data source. Modules that represent a multi data source include configuration parameters for the multi data source, including a list of data source modules used by the multi data source.
config/jdbcsubdirectory of the domain directory.
data-source-name.xmlfile to a subdirectory within your application and rename the copy to include -jdbc as a suffix, such as
nameto a name that is unique within the domain.
jndi-nameto a name that you want the enterprise application to use to lookup the data source in the local application context.
scope—optionally, to limit access to the data source to only the containing application, add a
scopeelement to the
jdbc-data-source-paramssection of the module. For example,
<scope>Application</scope>. See Application Scoping for a Packaged JDBC Module.
weblogic-jdbc.xsdschema. The schema is available at http://www.bea.com/ns/weblogic/90/weblogic-jdbc.xsd.
nameelement that is unique within the WebLogic domain.
properties, including any properties required by the JDBC driver to create database connections, such as a user name and password.
data-source-list,which is a list of data source modules, separated by commas, that the multi data source uses to satisfy database connection requests from applications.
All other configuration parameters are optional or have a default value that WebLogic Server uses if a value is not specified. However, to create a useful JDBC module, you will likely need to specify additional configuration options as required by your applications and your environment.
jdbc-driver-params—includes entries for the JDBC driver used to create database connections, including
driver-name, and individual driver
propertyentries. See the
weblogic-jdbc.xsdschema for more valid entries. For an explanation of each element, see "JDBCDriverParamsBean" in the WebLogic Server MBean Reference.
jdbc-connection-pool-params—includes entries for connection pool configuration, including connection testing options, statement cache options, and so forth. This element also inherits
max-capacity, and other options common to pooled resources. For more information, see the following:
jdbc-data-source-params—includes entries for data source behavior options and transaction processing options, such as
global-transactions-protocol. See the
weblogic-jdbc.xsdschema for more valid entries. For an explanation of each element, see "JDBCDataSourceParamsBean" in the WebLogic Server MBean Reference.
jdbc-xa-params—includes entries for XA database connection handling options, such as
xa-transaction-timeout. For an explanation of each element, see "JDBCXAParamsBean" in the WebLogic Server MBean Reference.
Listing A-1 shows an example of a JDBC module for a data source with some typical configuration options.
A JDBC multi data source module is much simpler than a data source module. Only one main section is required:
jdbc-data-source-params element in a multi data source differs in that it contains options for multi data source behavior options instead of data source behavior options. Only the following parameters in the
jdbc-data-source-params are valid for multi data sources:
For an explanation of each element, see "JDBCDataSourceParamsBean" in the WebLogic Server MBean Reference.
Listing A-2 shows an example of a JDBC module for a data source with some typical configuration options.
BEA recommends that you encrypt database passwords in a JDBC module to keep your data secure. To encrypt a database password, you process the password with the WebLogic Server
encrypt utility, which returns an encrypted equivalent of the password that you include in the JDBC module as the
password-encrypted element. For more details about using the WebLogic Server encrypt utility, see "encrypt" in the WebLogic Server Command Reference.
By default, when you package a JDBC module with an application, the JDBC resource is globally scoped—that is, the resource is bound to the global JNDI namespace and is available to all applications and clients. To reserve the resource for use only by the enclosing application, you must include the
<scope>Application</scope> parameter in the
jdbc-data-source-params element in the JDBC module, which binds the resource to the local application namespace. For example:
Figure A-1 shows the relationship between entries in various descriptor files for an EJB application and how they refer to a JDBC module packaged with the application.
When including JDBC modules in an enterprise application, you must list each JDBC module as a
module element of type
JDBC in the
weblogic-application.xml descriptor file packaged with the application. For example:
For other application modules in your enterprise application to use the JDBC modules packaged with your application, you must add the following entries in the descriptor files packaged with application modules:
ejb-jar.xmlfor an EJB, you must add
resource-ref-namereferences to specify the JNDI name of the data source as used in the application. For example:
resource-ref-namereference to the
jndi-nameelement of a data source. For example:
Figure A-1 shows the mapping of the of the data source name as used in the application module to the JNDI name of the JDBC data source in the JDBC module.
You package an application with a JDBC module as you would any other enterprise application. See "Packaging Applications Using wlpackage" in Developing Applications with WebLogic Server.
You deploy an application with a JDBC module as you would any other enterprise application. See "Deploying Applications Using wldeploy" in Developing Applications with WebLogic Server.
Caution: When deploying an application in production with application-scoped JDBC resources, if the resource uses EmulateTwoPhaseCommit for the global-transactions-protocol, you cannot deploy multiple versions of the application at the same time.
To get a connection from JDBC module packaged with an enterprise application, you look up the data source or multi data source defined in the JDBC module in the local environment (
java:comp/env) or on the JNDI tree and then request a connection from the data source or multi data source. For example: