|
|
|
|
|
|
Using the WebLogic Enterprise JDBC/XA Drivers
You can use the WebLogic Enterprise JDBC/XA drivers to make local or distributed connections to Oracle 8.0.5 or 8.1.5 databases. You can use the drivers with WebLogic Enterprise CORBA Java and WebLogic Enterprise J2EE (EJB and RMI) applications.
This topic includes the following sections:
For more information about JDBC connection pooling, see Using JDBC Connection Pooling.
For more information about using transactions with the WebLogic Enterprise JDBC/XA drivers, see Transactions and the WebLogic Enterprise JDBC/XA Driver in the WebLogic Enterprise online document Using Transactions. It includes the following topics:
Before You Begin
WebLogic Enterprise applications using the WebLogic Enterprise JDBC/XA drivers can perform local transactions as well as distributed (also called global) transactions. A local transaction involves updates to a single resource manager (RM), such as a database. A distributed transaction involves updates across multiple resource managers.
Read the following topics before you start using a WebLogic Enterprise JDBC/XA driver:
The WebLogic Enterprise JDBC/XA drivers for Oracle 8.0.5 and 8.1.5 are supported on the following platforms:
For information about any vendor patches required on each platform, and the specific required version of the Java 2 Software Development Kit (SDK), see the WebLogic Enterprise Platform Data Sheets appendix in the WebLogic Enterprise Installation Guide.
Adding the JAR Files to Your CLASSPATH
Be sure to add to your environment the WebLogic Enterprise Java ARchive (JAR) files that include the classes for the JDBC/XA drivers. You can do this by appending the following to your CLASSPATH system environment variable, where TUXDIR is the directory in which you installed the WebLogic Enterprise software:
Windows 2000 or NT
%TUXDIR%\udataobj\java\jdk\M3.jar;%TUXDIR%\udataobj\java\jdk\weblogicaux.jar;
UNIX
$TUXDIR/udataobj/java/jdk/M3.jar;$TUXDIR/udataobj/java/jdk/weblogicaux.jar;
Adding Locale to Your CLASSPATH
During development, or any time you are using BEA tools, you should also set up the location for error messages from the tools. You do this by adding the following to your CLASSPATH, where TUXDIR is the directory in which you installed the WebLogic Enterprise software:
Windows 2000 or NT
%TUXDIR%\locale\java\M3;
UNIX
$TUXDIR/locale/java/M3;
Shared Libraries and Dynamic Link Libraries
The JDBC/XA drivers call native libraries that are supplied with the drivers. The UNIX libraries (shared object files) are in the $TUXDIR/lib directory. The Windows DLL files are included in the WebLogic Enterprise software kit in the %TUXDIR%\bin directory.
The following table lists the names of the driver files included with the WebLogic Enterprise Java system.
|
Driver Filename |
Platform |
|---|---|
|
weblogicoci805.dll weblogicoci815.dll |
Microsoft Windows 2000 and NT 4.0 SP5 |
|
weblogicoci805.so weblogicoci815.so |
Compaq Tru64 UNIX 4.0F IBM AIX 4.3.3 Sun Solaris 2.6 and 7 |
|
weblogicoci805.sl weblogicoci815.sl |
HP-UX 11.0 |
For the WebLogic Enterprise JDBC/XA drivers, the driver class names are weblogic.jdbc20.oci805.Driver or weblogic.jdbc20.oci815.Driver. With the JDBC 2.0 API, unlike the API for the jdbcKona 1.22 drivers, you do not identify the driver class name in your application code. Instead, you assign data source properties, which include the driver class name. In the WebLogic Enterprise environment, this step is done by setting parameters in the WebLogic Enterprise application's UBBCONFIG file. For more information, see "Setting Data Source Properties" on page 1-6.
For the JDBC/XA drivers, you also need the Oracle-supplied 8.0.5 or 8.1.5 libraries for the database.
Requirements for Making a Connection to a DBMS
You need the following components to connect to a DBMS using a JDBC/XA driver:
In addition to the supported sample applications that are provided with the WebLogic Enterprise software, BEA provides unsupported samples and tools on its Web site. The JDBC/XA Bankapp sample code shown in this chapter are part of the unsupported samples on the Web. For a URL pointer to the JDBC/XA Bankapp sample that is shown in this chapter, see the BEA WebLogic Enterprise Release Notes.
About the JDBC API
The WebLogic Enterprise 5.1 software supports:
New methods that were added in the JDBC 2.0 API, which were not present in JDBC 1.22, are not supported in this release of WebLogic Enterprise. If a WebLogic Enterprise application calls a new JDBC 2.0 method that was not in JDBC 1.22, an SQLException will be thrown.
Setting Data Source Properties
The JDBC 2.0 Optional Package API, formerly known as the Standard Extension API, consists of the javax.sql package. This package includes the DataSource interface, which provides an alternative to the DriverManager class for making a connection to a data source. The DriverManager class is used with the jdbcKona 1.22 drivers.
Using a DataSource implementation is better for two important reasons:
In the WebLogic Enterprise environment, you set the data source properties separate from the WebLogic Enterprise application code. You set these properties in the application's UBBCONFIG configuration file. The values include the driver class name, the group in which the Java server runs, and several parameters that define the initial and run-time behavior of the JDBC connection pool.
When you create a binary TUXCONFIG version of the application's UBBCONFIG file with the tmloadcf command, these values are stored as TMIB properties. When the WebLogic Enterprise application's Java server is booted, its infrastructure will read the properties from TMIB and initialize the connection pools.
The setup process can be divided into:
The steps are described in subsequent sections of this topic. After you complete these steps, use the tmloadcf and tmboot commands to deploy the WebLogic Enterprise Java application, as described in Starting and Shutting Down Applications, an administration topic in the WebLogic Enterprise online documentation.
Administration Steps
The administration steps are as follows:
Use buildXAJS to Create an XA Version of JavaServer
From a system prompt, use the buildXAJS command to build an XA resource manager that will be used with a JavaServerXA application group.
Syntax
buildXAJS [-v] -r rmname [-o outfile]
Example
The following example builds a JavaServerXA resource manager named PayrollJavaServerXA on a Solaris system:
prompt>buildXAJS -r Oracle_XA -o PayrollJavaServerXA
Options
Note: See the BEA WebLogic Enterprise Release Notes for information about the rmname values that must be supplied for Oracle 8.0.5 and 8.1.5.
Environment Variables
Portability
The buildXAJS command is supported in UNIX and Windows 2000 or NT 4.0 systems. It is not supported on client-only WebLogic Enterprise systems.
Use buildtms to Create a Transaction Manager Server Load Module for Oracle
From a system prompt, use the buildtms command to build a transaction manager server load module for the XA resource manager (RM). Oracle 8.0.5 or 8.1.5 is the RM that you can use with a WebLogic Enterprise JDBC/XA driver. The files that result from the buildtms command need to be installed in the %TUXDIR% directory (Windows 2000 or NT 4.0) or $TUXDIR/bin (UNIX) directory.
Syntax
buildtms [ -v ] -o name -r rmname
Examples
The following examples build transaction manager server load modules for Oracle 8.0.5 or 8.1.5.
Windows 2000 or NT
prompt> buildtms -o %TUXDIR%\bin\TMS_ORA -r Oracle_XA
UNIX
prompt> buildtms -o $TUXDIR/bin/TMS_ORA -r Oracle_XA
Options
Note: See the BEA WebLogic Enterprise Release Notes for information about the rmname values that must be supplied for Oracle 8.0.5 and 8.1.5.
Portability
The buildtms command is supported in UNIX and Windows 2000 or NT systems. It is not supported on client-only WebLogic Enterprise systems.
Define the Database Open Information
In the GROUPS section of the application's UBBCONFIG file, configure the OPENINFO parameter according to the definition of the XA parameter for the Oracle 8.0.5 or 8.1.5 database. Listing 1-1 shows a sample OPENINFO parameter value. In this example, the OPENINFO values are defined for a group designated as BANK_GROUP1.
Listing 1-1 OPENINFO Setting in Sample UBBCONFIG
*GROUPS
SYS_GRP
LMID = SITE1
GRPNO = 1
BANK_GROUP1
LMID = SITE1
GRPNO = 2
OPENINFO = "ORACLE_XA:Oracle_XA+Acc=P/scott/tiger+SesTm=100+LogDir=.+DbgFl=0x7+MaxCur=15+Threads=true"
TMSNAME = TMS_ORA
TMSCOUNT = 2
In the example, note how the TMS_ORA name matches the Oracle transaction manager that was created for Oracle 8.0.5 or 8.1.5 in the previous buildtms step.
Define JavaServerXA Parameters
In the SERVERS section of the application's UBBCONFIG file, define parameters to indicate how this WebLogic Enterprise application will use JavaServerXA.
The JavaServerXA parameter is required if you are using the JDBC/XA driver. If you want the JavaServerXA to be multithreaded, specify the -M option for the CLOPT parameter. To deploy a single-threaded JavaServerXA server, do not use the -M option.
Each JavaServerXA can only host WebLogic Enterprise JDBC connection pools that connect to one resource manager. The current release supports the Oracle 8.0.5 or 8.1.5 XA resource manager only.
You must specify SRVTYPE=JAVA for the JavaServer or JavaServerXA to use JDBC connection pooling.
Note: In prior WebLogic Enterprise releases, you could also specify the name of the connection pool on the command-line options (CLOPT) of the JavaServerXA or JavaServer parameter. Although this is still allowed by the syntax parser, the new syntax is to list the connection pool's name and the application's JAR filename in the MODULES section.
Listing 1-2 shows an example of JavaServerXA configured for multithreading in a sample UBBCONFIG. Notice the association between the BANK_GROUP1 group that was defined in the previous listing; it contains the OPENINFO values.
Also notice how in the MODULES section, the bank_pool value is listed to give a handle for a JDBC connection pool.
Listing 1-2 Multithreaded Server Configuration in Sample UBBCONFIG
*SERVERS
DEFAULT:
RESTART = Y
MAXGEN = 5
.
.
.
JavaServerXA
SRVGRP = BANK_GROUP1
SRVID = 2
SRVTYPE = JAVA
CLOPT = "-A -- -M 10"
RESTART = N
.
.
.
*MODULES
BankApp
SRVGRP = BANK_GROUP1
SRVID = 2
FILE = "BankApp.jar"
ARGS = "TellerFactory_1 bank_pool"
The -M 10 parameter for the JavaServerXA enables a multithreaded JavaServer with a pool of 10 threads. The threads setting is in addition to the JDBC connection pool settings, which are defined in the next section, JDBCCONNPOOLS.
Note: The potential for a performance gain from a multithreaded JavaServer depends on the application pattern and whether the application is running on a single-processor or multiprocessor machine. For more information about enabling multithreaded JavaServers, see Creating a Configuration File, an administration topic in the WebLogic Enterprise online documentation.
Identify the Driver Class and Connection Pool Characteristics
The JDBCCONNPOOLS section of the application's UBBCONFIG file includes several parameters to set the properties of the JDBC connection pool and the driver it uses. This JDBCCONNPOOLS section was added to the WebLogic Enterprise product in version 5.1. Listing 1-3 shows a sample section.
Listing 1-3 Defining Driver and Connection Pooling Properties in a Sample UBBCONFIG
*JDBCCONNPOOLS
bank_pool
SRVGRP = BANK_GROUP1
SRVID = 2
DRIVER = "weblogic.jdbc20.oci815.Driver"
URL = "jdbc:weblogic:oracle:beq-local"
PROPS = "user=scott;password=tiger;server=Beq-Local"
ENABLEXA = Y
INITCAPACITY = 2
MAXCAPACITY = 10
CAPACITYINCR = 1
CREATEONSTARTUP = Y
The SRVGRP parameter value, BANK_GROUP1, forms the association between this bank_pool connection pool and the definition of BANK_GROUP1 in the GROUPS section of the UBBCONFIG. The definition for BANK_GROUP1 included the Oracle database OPENINFO values.
The JDBC connection pool is named bank_pool, which was also identified in the MODULES section. The use of the server ID (SRVID = 2) and the bank_pool name forms the association between the JavaServerXA that will run in BANK_GROUP1 and this connection pool.
For the WebLogic Enterprise JDBC/XA driver, set the DRIVER parameter value to either weblogic.jdbc20.oci805.Driver or weblogic.jdbc20.oci815.Driver. Also, set the ENABLEXA parameter to Y.
See Chapter 2, "Using JDBC Connection Pooling" for information about the other JDBCCONNPOOLS parameters. They include settings for the initial and run-time behavior of the named connection pool.
Programming Steps
The programming steps include the following:
After you complete these steps described in these sections, use the tmloadcf and tmboot commands to deploy the WebLogic Enterprise Java application, as described in Starting and Shutting Down Applications, an administration topic in the WebLogic Enterprise online documentation. The steps include:
Import the Required API Packages
Listing 1-4 shows the packages that a Java application imports. In particular, note that:
Listing 1-4 Importing Required Packages
import java.io.*;
import java.net.URL;
import java.sql.*;
import javax.sql.*;
import javax.naming.*;
import com.beasys.*;
import com.beasys.Tobj.*;
import com.beasys.Tobj.TP;
Initialize JavaServerXA and Get the Pool Name
In your Java application code, initialize the JavaServerXA. In the sample file BankAppServerImpl.java, when the sample BankApp JavaServerXA is initialized, it:
The two arguments are:
The JdbcConnPoolName argument is the name of the connection pool that was specified in the application's UBBCONFIG file. The JavaServerXA returns this value to the program.
For example, the following code fragment is from the sample file BankAppServerImpl.java:
public boolean initialize(String[] args)
{
try {
// get input arguments
if(args.length < 2 ) {
TP.userlog("Not enough arguments");
TP.userlog("Correct Argument list: ");
TP.userlog("TellerFactory_1 bank_pool");
return false;
}
tellerFName = new String(args[0]);
String pool_name = args[1];
// write the input arguments to ULOG file
TP.userlog("Input Arguments for Server.initialize(): ");
TP.userlog("TellerFactory_1: " + tellerFactory_1 );
TP.userlog("JDBC connection pool name: " + bank_pool);
Use a JNDI Lookup to Create a Pool of Connections
The sample program BankAppServerImpl.java uses the static variable DataSource, the connection pool object. For example:
static DataSource pool;
Using DataSource, the sample uses a JNDI lookup to create a pool of connections to the database. For example:
public void get_connpool(String bank_pool)
throws Exception
{
try {
javax.naming.Context ctx = new InitialContext();
pool = (DataSource)ctx.lookup("jdbc/" + bank_pool);
}
catch (javax.naming.NamingException ex){
TP.userlog("Couldn't obtain JDBC connection pool: " +
bank_pool);
throw ex;
}
}
Get Database Connections from the Pool
In the DataSource implementation, the Connection object that is returned by the DataSource.getConnection method is identical to a Connection object returned by the jdbcKona 1.22 DriverManager.getConnection method. Because of the advantages it offers, using a DataSource object is the recommended way to obtain a connection.
For the application programmer, using a DataSource object is a matter of choice. However, programmers writing WebLogic Enterprise JDBC applications that include distributed (XA) transactions and connection pooling must use a DataSource object to get connections.
For example, the following code fragment is from the sample application file DBAccessImpl.java:
public void get_valid_accounts(short pinNo, CustAccountsHolder accounts)
throws DataBaseException, PinNumberNotFound
{
Statement stmt=null;
ResultSet rs=null;
Connection con= null;
try {con = BankAppServerImpl.pool.getConnection();
// Construct and execute the SQL SELECT statement.
stmt = con.createStatement();
String stmtBuf =
new String(
"SELECT CheckingAccountID, SavingsAccountID "
+ "FROM Cust_Data WHERE PinNo = "
+ pinNo);
rs = stmt.executeQuery(stmtBuf);
|
|
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|