Configuring and Managing WebLogic JDBC

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

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:

  1. Create the module. See Creating Packaged JDBC Modules.
  2. Add references to the module in all applicable descriptor files. See Referencing a JDBC Module in Java EE Descriptor Files.
  3. Package all application modules in an EAR. See Packaging an Enterprise Application with a JDBC Module.
  4. 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.

  1. 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.
  2. 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.
  3. 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.
  4. Continue with adding references to the descriptor files in the enterprise application. See Referencing a JDBC Module in Java EE Descriptor Files.

JDBC Packaged Module Requirements

A JDBC module must meet the following criteria:

Data source modules must also include the following JDBC driver parameters:

Multi data source modules must also include the following data source parameters:

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:

Creating a JDBC Data Source Module

The main sections within a JDBC data source module are:

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:

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

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

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

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

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:

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();

  Back to Top       Previous  Next