Configuring and Managing WebLogic JDBC

Configuring JDBC Application Modules for Deployment

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:

Packaging a JDBC Module with an Enterprise Application: Main Steps

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 J2EE 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.

Creating Packaged JDBC 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 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.

Creating a JDBC Data Source Module Using the Administration Console

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.
Copy the data-source-name.xml file to a subdirectory within your application and rename the copy to include -jdbc as a suffix, such as new-data-source-name-jdbc.xml.
Open the file in an editor and change the following elements:

name—change the name to a name that is unique within the domain.
jndi-name—change the 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 J2EE Descriptor Files.

JDBC Packaged Module Requirements

A JDBC module must meet the following criteria:

Conforms to the weblogic-jdbc.xsd schema. The schema is available at http://www.bea.com/ns/weblogic/920/weblogic-jdbc.xsd.
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 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.

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.

Creating a JDBC 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, including url, driver-name, and individual driver property entries. See the weblogic-jdbc.xsd schema 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 connection-pool-params from the weblogic-j2ee.xsd schema, including initial-capacity, max-capacity, and other options common to pooled resources. For more information, see the following:

“ JDBCConnectionPoolParamsBean” in the WebLogic Server MBean Reference
weblogic-jdbc.xsd schema

jdbc-data-source-params—includes entries for data source behavior options and transaction processing options, such as jndi-name, row-prefetch-size, and global-transactions-protocol. See the weblogic-jdbc.xsd schema 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 keep-xa-conn-till-tx-complete, and 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.

Listing A-1 Sample JDBC Data Source Module

<jdbc-data-source xmlns="http://www.bea.com/ns/weblogic/91">
  <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>

Creating a JDBC Multi Data Source Module

A JDBC multi data source module is much simpler than a 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 WebLogic Server MBean Reference.

Listing A-2 shows an example of a JDBC module for a data source with some typical configuration options.

Listing A-2 Sample JDBC Multi Data Source Module

<jdbc-data-source xmlns="http://www.bea.com/ns/weblogic/91">
  <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>

Encrypting Database Passwords in a JDBC Module

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.

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 Administration Console Online Help.
Re-encrypt the passwords for your new domain. See 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 data sources in a multi data source for an application-scoped JDBC module must also be application scoped.

Referencing a JDBC Module in J2EE 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

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>

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 J2EE 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.

Packaging an Enterprise Application with a 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.

Deploying an Enterprise Application with a JDBC Module

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.

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 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:

conn.close();