|
|
|
|
|
|
You can use the WebLogic Enterprise (WLE) JDBC/XA driver to make local or distributed connections to Oracle 8i databases. You can use this driver with WLE CORBA Java and WLE 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 WLE JDBC/XA driver, see Transactions and the WLE JDBC/XA Driver. It includes the following topics:
WLE applications using the WLE JDBC/XA for Oracle 8i driver can perform local transactions as well as distributed (also called global) transactions. A local transaction involves updates to a single Resource Manager, such as a database. A distributed transaction involves updates across multiple Resource Managers.
Read the following topics before you start using the WLE JDBC/XA for Oracle 8i driver:
Before You Begin
The following table lists the platforms supported by the WLE JDBC/XA driver.
Platforms Supported by the JDBC/XA Driver
Operating System and Version |
Java 2 Software Development Kit (SDK) |
DBMS |
Client Libraries |
|---|---|---|---|
Be sure to add the WLE JAR files that include the JDBC/XA driver classes to your environment. You can do this by appending the following to your CLASSPATH
system environment variable, where TUXDIR
is the directory in which you installed the WLE software:
On UNIX Systems:
$TUXDIR/udataobj/java/jdk/M3.jar;$TUXDIR/udataobj/java/jdk/weblogicaux.jar; On NT Systems:
%TUXDIR%\udataobj\java\jdk\M3.jar;%TUXDIR%\udataobj\java\jdk\weblogicaux.jar; During development, or any time you are using BEA tools, you should also setup 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 WLE software:
On UNIX Systems:
$TUXDIR/locale/java/M3; On NT Systems:
%TUXDIR%\locale\java\M3;
The JDBC/XA driver calls native libraries that are supplied with the driver. The UNIX libraries (shared object files) are in the $TUXDIR/lib
directory. The Windows DLL
files are included in the WLE software kit in the %TUXDIR%\bin
directory.
The following table lists the names of the driver files included with the WLE Java system.
Adding the JAR Files to Your CLASSPATH
Adding Locale to Your CLASSPATH
Shared Libraries and Dynamic Link Libraries
Windows NT/98/95 |
Solaris |
HP-UX |
|---|---|---|
For the WLE JDBC/XA driver, the driver class name is 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 WLE environment, this step is done by setting parameters in the WLE application's UBBCONFIG file. For more information, see the section Setting Data Source Properties.
For the JDBC/XA driver, you also need the Oracle-supplied version 8i libraries for the database.
You need the following components to connect to a DBMS using a JDBC/XA driver:
Requirements for Making a Connection to a DBMS
In addition to the supported sample applications that are provided with the WLE 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 pointer to the JDBC/XA Bankapp sample that is shown in this chapter, see the BEA WebLogic Enterprise Release Notes.
The WLE 5.0 software supports:
About the Sample Code
About the JDBC API
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 WLE. If a WLE application calls a new JDBC 2.0 method that was not in JDBC 1.22, an SQLException
will be thrown.
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:
Setting Data Source Properties
In the WLE environment, you set the data source properties separate from the WLE 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 runtime 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 WLE application's Java server is booted, its infrastructure will read the properties from TMIB and initialize the connection pools.
The set up 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 WLE Java application, as described in Starting and Shutting Down Applications, an administration topic in the WebLogic Enterprise online documentation.
The administration steps are as follows:
Administration Steps
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
Use buildXAJS to create an XA version of JavaServer
Note:
See the BEA WebLogic Enterprise Release Notes for information about the rmname
values that must be supplied for Oracle 8i.
Environment Variables
Portability
The buildXAJS command is supported in UNIX and NT systems. It is not supported on client-only WLE systems.
From a system prompt, use the buildtms command to build a transaction manager server load module for the XA resource manager (RM). In the current release, Oracle 8i is the RM that you can use with the JDBC/XA driver. The files that result from the buildtms command need to be installed in $TUXDIR/bin directory.
Syntax
buildtms [ -v ] -o name -r rmname
Examples
The following examples build transaction manager server load modules for Oracle 8i.
On UNIX Systems
prompt> buildtms -o $TUXDIR/bin/TMS_ORA -r Oracle_XA
On NT Systems
prompt> buildtms -o $TUXDIR\bin\TMS_ORA -r Oracle_XA
Options
The value rmname
must appear in the resource manager table located in $TUXDIR/udataobj/RM
on UNIX systems, or %TUXDIR%\udataobj\RM
on Windows NT systems. On UNIX systems, each entry in this file is of the form rmname:rmstructure_name:library_names
. On NT systems, each entry in this file is of the form rmname;rmstructure_name;library_names
.
Note:
See the BEA WebLogic Enterprise Release Notes for information about the rmname
values that must be supplied for Oracle 8i.
Portability
The buildtms command is supported in UNIX and NT systems. It is not supported on client-only WLE systems.
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 8i 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 8i in the previous buildtms step.
In the SERVERS section of the application's UBBCONFIG file, define parameters to indicate how this WLE application will use JavaServerXA. The parameters include the name of the connection pool. For example:
Each JavaServerXA can only host WLE JDBC connection pools that connect to one Resource Manager. The current release supports the Oracle 8i XA Resource Manager only.
These parameters are 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.
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 the bank_pool value to give a handle for a JDBC connection pool. Also, you must specify SRVTYPE=JAVA for the JavaServer or JavaServerXA to use JDBC connection pooling.
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 BankApp.jar TellerFactory_1 bank_pool
"
RESTART = N
The -M 10 parameter 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.
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 WLE product in version 5.0. Listing 1-3 shows a sample section.
Listing 1-3 Defining Driver and Connection Pooling Properties in 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 used as a command line (CLOPT ) parameter in the SERVERS section for JavaServerXA. The use of bank_pool forms the association between the JavaServerXA that will run in BANK_GROUP1 and this connection pool.
For the WLE JDBC/XA driver, set the DRIVER parameter value to the value shown: weblogic.jdbc20.oci815.Driver . Also, the ENABLEXA parameter must be set to Y .
See Chapter 2, "Using JDBC Connection Pooling" for information about the other JDBCCONNPOOLS parameters. They include settings for the initial and runtime behavior of the named connection pool.
The programming steps include the following:
After you complete these steps described in these sections, use the tmloadcf
and tmboot
commands to deploy the WLE Java application, as described in Starting and Shutting Down Applications, an administration topic in the WebLogic Enterprise online documentation. The steps include:
Listing 1-4 shows the packages that a Java application imports. In particular, note that:
Import the Required API Packages
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;
In your Java application code, initialize the JavaServerXA. In the sample file BankAppServerImpl.java, when the sample BankApp JavaServerXA is initialized, it:
Initialize JavaServerXA and Get the Pool Name
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) tellerFName = new String(args[0]); // write the input arguments to ULOG file 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 pool_name) 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 WLE JDBC applications that include distributed (XA) transactions and connection pooling must use a DataSource
object to get connections.
For example, the following code fragement is from the sample application file DBAccessImpl.java:
public void get_valid_accounts(short pinNo, CustAccountsHolder accounts) Statement stmt=null; try { con = BankAppServerImpl.pool.getConnection();
{
try {
// get input arguments
if(args.length < 2 ) {
TP.userlog("Not enough arguments");
TP.userlog("Correct Argument list: ");
TP.userlog("TellFactoryName JdbcConnPoolName");
return false;
}
String pool_name = args[1];
TP.userlog("Input Arguments for Server.initialize(): ");
TP.userlog("tellerFName: " + tellerFName );
TP.userlog("JDBC connection pool name: " + pool_name); Use a JNDI lookup to create a pool of connections
throws Exception
{
try {
javax.naming.Context ctx = new InitialContext();
pool = (DataSource)ctx.lookup("jdbc/" + pool_name);
}
catch (javax.naming.NamingException ex){
TP.userlog("Couldn't obtain JDBC connection pool: " +
pool_name);
throw ex;
}
} Get Database Connections from the Pool
throws DataBaseException, PinNumberNotFound
{
ResultSet rs=null;
Connection con= null;
// 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 © 1999 BEA Systems, Inc. All rights reserved.
|