A Configuring JDBC Application Modules for Deployment
Note:
To learn more about the proprietary mechanism provided by WebLogic Server prior to the DatasourceDefinition feature introduced in Java EE 6, see Using Java EE DataSources Resource Definitions in Developing JDBC Applications for Oracle WebLogic Server.
- Packaging a JDBC Module with an Enterprise Application: Main Steps
Learn about the steps for creating, packaging, and deploying a JDBC module with an enterprise application. - Creating Packaged JDBC Modules
You can create JDBC application modules using any development tool that supports creating an XML descriptor file. - Referencing a JDBC Module in Java EE Descriptor Files
Learn about referencing a JDBC Module in Java EE Descriptor Files. - Packaging an Enterprise Application with a JDBC Module
Learn about packaging an application with a JDBC module. - Deploying an Enterprise Application with a JDBC Module
Learn about deploying an enterprise application with a JDBC module. - Getting a Database Connection from a Packaged JDBC Module
To get a connection from JDBC module packaged with an enterprise application, you look up the 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.
Packaging a JDBC Module with an Enterprise Application: Main Steps
Learn about the steps for creating, packaging, and deploying a JDBC module with an enterprise application.
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.
Parent topic: Configuring JDBC Application Modules for Deployment
Creating Packaged JDBC Modules
You then deploy and manage JDBC modules using JSR 88-based tools, such as the weblogic.Deployer
utility, or the WebLogic Server Administration Console.
Note:
You can create a JDBC data source using the WebLogic Server 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. Modules that represent a generic or Active GridLink data source include all of the configuration parameters for the Generic or Active GridLink data source. Modules that represent a Multi Data Source include configuration parameters for the Multi Data Source, including a list of Generic data source modules used by the Multi Data Source.
- Creating a JDBC Data Source Module Using the Administration Console
- JDBC Packaged Module Requirements
- JDBC Application Module Limitations
- Creating a Generic Data Source Module
- Creating an Active GridLink Data Source Module
- Creating a Multi Data Source Module
- Encrypting Database Passwords in a JDBC Module
- Application Scoping for a Packaged JDBC Module
Parent topic: Configuring JDBC Application Modules for Deployment
Creating a JDBC Data Source Module Using the Administration Console
To create a data source module in the WebLogic Server Administration Console that you can re-use as an application module, follow these steps.
Parent topic: Creating Packaged JDBC Modules
JDBC Packaged Module Requirements
A JDBC module must meet the following criteria:
-
Conforms to the
jdbc-data-source.xsd
schema. The schema is available at http://www.oracle.com/webfolder/technetwork/weblogic/jdbc-data-source/index.html. -
Uses a file name that ends in
-jdbc.xml
. -
Includes a
name
element that is unique within the WebLogic domain.
Data source modules must also include the following JDBC driver parameters:
-
url
-
driver-name
-
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
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.
Parent topic: Creating Packaged JDBC Modules
JDBC Application Module Limitations
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.
Parent topic: Creating Packaged JDBC Modules
Creating a Generic Data Source Module
The main sections within a JDBC data source module are:
-
jdbc-driver-params
—includes entries for the JDBC driver used to create database connections, includingurl
,driver-name
, and individual driverproperty
entries. See thejdbc-data-source.xsd
schema for more valid entries. For an explanation of each element, see JDBCDriverParamsBean in the MBean Reference for Oracle WebLogic Server. -
jdbc-connection-pool-params
—includes entries for connection pool configuration, including connection testing options, statement cache options, and so forth. This element also inheritsconnection-pool-params
from theweblogic-javaee.xsd
schema, includinginitial-capacity
,min-capacity
,max-capacity
, and other options common to pooled resources. For more information, see the following:-
JDBCConnectionPoolParamsBean in the MBean Reference for Oracle WebLogic Server
-
jdbc-data-source.xsd
schema
-
-
jdbc-data-source-params
—includes entries for data source behavior options and transaction processing options, such asjndi-name
,row-prefetch-size
, andglobal-transactions-protocol
. See thejdbc-data-source.xsd
schema for more valid entries. For an explanation of each element, see JDBCDataSourceParamsBean in the MBean Reference for Oracle WebLogic Server. -
jdbc-xa-params
—includes entries for XA database connection handling options, such askeep-xa-conn-till-tx-complete
, andxa-transaction-timeout
. For an explanation of each element, see JDBCXAParamsBean in the MBean Reference for Oracle WebLogic Server.
Example A-1 shows an example of a JDBC module for a data source with some typical configuration options.
Example A-1 Sample Generic Data Source Module
<jdbc-data-source xsi:schemaLocation="http://www.bea.com/ns/weblogic/90/domain.xsd" xmlns="http://xmlns.oracle.com/weblogic/jdbc-data-source" xmlns:sec="http://www.bea.com/ns/weblogic/90/security" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wls="http://www.bea.com/ns/weblogic/90/security/wls"> <name>examples-demoXA-2</name> <jdbc-driver-params> <url>jdbc:derby://localhost:1527/examples;create=true</url> <driver-name>org.apache.derby.jdbc.ClientXADataSource</driver-name> <properties> <property> <name>user</name> <value>examples</value> </property> <property> <name>DatabaseName</name> <value>examples</value> </property> </properties> <password-encrypted>{AES}MEK6bPum8M69KRP4FANx3TG/O0iSWRYu2rZGUwnVo6U=</password-encrypted> </jdbc-driver-params> <jdbc-connection-pool-params> <max-capacity>100</max-capacity> <connection-reserve-timeout-seconds>25</connection-reserve-timeout-seconds> <test-table-name>SQL SELECT 1 FROM SYS.SYSTABLES</test-table-name> </jdbc-connection-pool-params> <jdbc-data-source-params> <global-transactions-protocol>TwoPhaseCommit</global-transactions-protocol> </jdbc-data-source-params> </jdbc-data-source>
Parent topic: Creating Packaged JDBC Modules
Creating an Active GridLink Data Source Module
Active GridLink data source modules are similar to Generic data source system modules. Active GridLink data sources include an
jdbc-oracle-params
section that includes ONS
and
FAN
.
Parent topic: Creating Packaged JDBC Modules
Creating a Multi Data Source Module
A JDBC Multi Data Source module is much simpler than a
Generic data source module. Only one main section is
required: jdbc-data-source-params
. The
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:
-
jndi-name
(required) -
data-source-list
(required) -
scope
-
algorithm-type
-
connection-pool-failover-callback-handler
-
failover-request-if-busy
For an explanation of each element, see JDBCDataSourceParamsBean in the MBean Reference for Oracle WebLogic Server.
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>
Parent topic: Creating Packaged JDBC Modules
Encrypting Database Passwords in a JDBC Module
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 WLST Command Reference for WebLogic Server.
Deploying JDBC Modules to New Domains
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 WebLogic Server Administration Console Online Help.
-
Re-encrypt the passwords for your new domain. See Encrypting Database Passwords in a JDBC Module.
-
If you use the Oracle wallet, you can simply reference the wallet and copy the wallet file to the new domain. See Creating and Managing Oracle Wallet.
Parent topic: Encrypting Database Passwords in a JDBC Module
Application Scoping for a Packaged 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 generic data sources in a multi data source for an application-scoped JDBC module must also be application scoped.
Parent topic: Creating Packaged JDBC Modules
Referencing a JDBC Module in Java EE Descriptor Files
When you package a JDBC module with an enterprise application, you must reference the module in all applicable descriptor files, including among others:
-
weblogic-application.xml
-
ejb-jar.xml
-
weblogic-ejb-jar.xml
-
web.xml
-
weblogic.xml
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
Description of "Figure A-1 Relationship Between JDBC Modules and Descriptors in an Enterprise Application"
- Packaged JDBC Module References in weblogic-application.xml
- Packaged JDBC Module References in Other Descriptors
Parent topic: Configuring JDBC Application Modules for Deployment
Packaged JDBC Module References in weblogic-application.xml
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>
Parent topic: Referencing a JDBC Module in Java EE Descriptor Files
Packaged JDBC Module References in Other Descriptors
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 addresource-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 thejndi-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.
Parent topic: Referencing a JDBC Module in Java EE Descriptor Files
Packaging an Enterprise Application with a JDBC Module
See Packaging Applications Using wlpackage in Developing Applications for Oracle WebLogic Server.
Parent topic: Configuring JDBC Application Modules for Deployment
Deploying an Enterprise Application with a JDBC Module
See Deploying Applications Using wldeploy in 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.
Parent topic: Configuring JDBC Application Modules for Deployment
Getting a Database Connection from a Packaged JDBC Module
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:
conn.close();
Parent topic: Configuring JDBC Application Modules for Deployment