|Oracle® Fusion Middleware Configuring and Managing JDBC for Oracle WebLogic Server
11g Release 1 (10.3.1)
Part Number E13737-01
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).
The following sections describe the details of packaged JDBC modules:
The main steps for creating, packaging, and deploying a JDBC module with an enterprise application are as follows:
Create the module. See Creating Packaged JDBC Modules.
Add references to the module in all applicable descriptor files. See Referencing a JDBC Module in Java EE Descriptor Files.
Package all application modules in an EAR. See Packaging an Enterprise Application with a JDBC Module.
Deploy the application. See Deploying an Enterprise Application with a JDBC Module.
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 name and 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.
To create a data source module in the Administration Console that you can re-use as an application module, follow these steps.
Create a data source as described in Creating a JDBC Data Source. The data source module is created in the
config/jdbc subdirectory of the domain directory.
data-source-name.xml file to a subdirectory within your application and rename the copy to include -jdbc as a suffix, such as
Open the file in an editor and change the following elements:
name to a name that is unique within the domain.
jndi-name to 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
scope element to the
jdbc-data-source-params section of the module. For example,
<scope>Application</scope>. See Application Scoping for a Packaged JDBC Module.
Continue with adding references to the descriptor files in the enterprise application. See Referencing a JDBC Module in Java EE Descriptor Files.
A JDBC module must meet the following criteria:
Conforms to the
jdbc-data-source.xsd schema. The schema is available at http://xmlns.oracle.com/weblogic/jdbc-data-source/1.0/jdbc-data-source.xsd.
Uses a file name that ends in
name element that is unique within the WebLogic domain.
Data source modules must also include the following JDBC driver parameters:
properties, including any properties required by the JDBC driver to create database connections, such as a user name and password.
Multi data source modules must also include the following data source parameters:
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.
Note:All data sources listed in the data-source-list must have the same XA and transaction protocol settings.
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.
Note the following limitations for JDBC application modules:
The LoggingLastResource global-transactions-protocol is not permitted for use in JDBC application modules.
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.
The main sections within a JDBC data source module are:
jdbc-driver-params—includes entries for the JDBC driver used to create database connections, including
driver-name, and individual driver
property entries. See the
jdbc-data-source.xsd schema for more valid entries. For an explanation of each element, see "JDBCDriverParamsBean" in the Oracle Fusion Middleware Oracle 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
connection-pool-params from the
weblogic-javaee.xsd schema, including
max-capacity, and other options common to pooled resources. For more information, see the following:
"JDBCConnectionPoolParamsBean" in the Oracle Fusion Middleware Oracle WebLogic Server MBean Reference
jdbc-data-source-params—includes entries for data source behavior options and transaction processing options, such as
global-transactions-protocol. See the
jdbc-data-source.xsd schema for more valid entries. For an explanation of each element, see "JDBCDataSourceParamsBean" in the Oracle Fusion Middleware Oracle 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 Oracle Fusion Middleware Oracle WebLogic Server MBean Reference.
Example A-1 shows an example of a JDBC module for a data source with some typical configuration options.
Example A-1 Sample JDBC Data Source Module
<jdbc-data-source xmlns="http://xmlns.oracle.com/weblogic/jdbc-data-source "> <name>examples-demoXA-2</name> <jdbc-driver-params> <url>jdbc:pointbase:server://localhost:9092/demo</url> <driver-name>com.pointbase.xa.xaDataSource</driver-name> <properties> <property> <name>user</name> <value>examples</value> </property> <property> <name>databaseName</name> <value>jdbc:pointbase:server://localhost:9092/demo</value> </property> </properties> <password-encrypted>eNEVN9dk4dEDUEVqL1</password-encrypted> </jdbc-driver-params> <jdbc-connection-pool-params> <initial-capacity>3</initial-capacity> <max-capacity>10</max-capacity> <test-connections-on-reserve>true</test-connections-on-reserve> <test-table-name>SQL SELECT COUNT(*) FROM SYSTABLES</test-table-name> </jdbc-connection-pool-params> <jdbc-data-source-params> <global-transactions-protocol>TwoPhaseCommit</global-transactions-protocol> <jndi-name>examples-demoXA-2</jndi-name> <scope>Application</scope> </jdbc-data-source-params> </jdbc-data-source>
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 Oracle Fusion Middleware Oracle WebLogic Server MBean Reference.
Example A-2 shows an example of a JDBC module for a data source with some typical configuration options.
Example A-2 Sample JDBC Multi Data Source Module
<jdbc-data-source xmlns="http://xmlns.oracle.com/weblogic/jdbc-data-source"> <name>examples-demoXA-multi-data-source</name> <jdbc-data-source-params> <jndi-name>examples-demoXA -multi-data-source</jndi-name> <algorithm-type>Load-Balancing</algorithm-type> <data-source-list>examples-demoXA,examples-demoXA-2</data-source-list> </jdbc-data-source-params> </jdbc-data-source>
Oracle 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 Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
It it common practice for JDBC modules to be moved from one domain to another, such as moving an application from development to production. However, the encryption key generated by the WebLogic Server encrypt utility is not transferable to a new domain. When moving a JDBC module with an encrypted database password, you must do one of the following:
Override the old encrypted password within a deployment plan that includes a password that was encrypted specifically for the new domain. See "Update a deployment plan" in Oracle Fusion Middleware Oracle WebLogic Server Administration Console Help.
Re-encrypt the passwords for your new domain. See Encrypting Database Passwords in a JDBC Module.
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:
<jdbc-data-source-params> <jndi-name>examples-demoXA-2</jndi-name> <scope>Application</scope> </jdbc-data-source-params>
All data sources in a multi data source for an application-scoped JDBC module must also be application scoped.
When you package a JDBC module with an enterprise application, you must reference the module in all applicable descriptor files, including among others:
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.
Figure A-1 Relationship Between JDBC Modules and Descriptors in an Enterprise 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:
<module> <name>data-source-1</name> <type>JDBC</type> <path>datasources/data-source-1-jdbc.xml</path> </module>
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:
In the standard Java EE descriptor files packaged with your application modules, such as
ejb-jar.xml for an EJB, you must add
resource-ref-name references to specify the JNDI name of the data source as used in the application. For example:
<resource-ref> <res-ref-name>my-data-source</res-ref-name> <res-type>javax.sql.DataSource</res-type> <res-auth>Container</res-auth> </resource-ref>
In this example,
my-data-source is the data source name as used in the application module. Your application would look up the data source with the following code:
javax.sql.DataSource ds = (javax.sql.DataSource) ctx.lookup("java:comp/env/my-data-source");
In the WebLogic-specific descriptor files, such as weblogic-ejb-jar.xml for an EJB, you must map each
resource-ref-name reference to the
jndi-name element of a data source. For example:
<resource-description> <res-ref-name>my-data-source</res-ref-name> <jndi-name>qa-database-1</jndi-name> </resource-description>
In this example, the resource name (
<res-ref-name>my-data-source</res-ref-name>) from the standard descriptor is mapped to the JNDI name (
<jndi-name>qa-database-1</jndi-name>) of the data source in the JDBC module.
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.
Note:For application-scoped data sources, if you do not add these entries to the descriptor files, your application will be unable to look up the data source to get a database connection.
You package an application with a JDBC module as you would any other enterprise application. See "Packaging Applications Using wlpackage" in Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server.
You deploy an application with a JDBC module as you would any other enterprise application. See "Deploying Applications Using wldeploy" in Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server.
Note: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:
javax.sql.DataSource ds = (javax.sql.DataSource) ctx.lookup("java:comp/env/my-data-source"); java.sql.Connection conn = ds.getConnection();
When you are finished using the connection, make sure you close the connection to return it to the connection pool in the data source: