Installing and Configuring WebLogic Tuxedo Connector

 

The following sections describe how to install and configure the WebLogic Tuxedo Connector. Installation instructions are provided for Windows NT and UNIX platforms.

• Summary of Environment Changes and Considerations

• Installing the WebLogic Tuxedo Connector

• Configuring WebLogic Tuxedo Connector for Your Applications

• Uninstalling the WebLogic Tuxedo Connector

Summary of Environment Changes and Considerations

This section provides an overview of the changes you must make to the Tuxedo and WebLogic Server environments before you can start using the WebLogic Tuxedo Connector. These changes are discussed in detail in this chapter.

Tuxedo Changes

Tuxedo users need to make the following environment changes:

• If an existing Tuxedo application is already using Tuxedo /T DOMAINS, then a new domain must be added to the domains configuration file for each connection to a WebLogic Tuxedo Connector instantiation.

• If the existing Tuxedo application does not use domains, then the domain servers must be added to the TUXCONFIG of the application. A new DMCONFIG must be created with a Tuxedo /T Domain entry corresponding to the WebLogic Tuxedo Connector instantiation.

• WebLogic Tuxedo Connector requires that the Tuxedo domain always have encoding turned on. MTYPE should always be unset or set to NULL in the DMCONFIG file.

  Note: For more information on DMCONFIG files, see the BEA TUXEDO Domains Guide.

WebLogic Server Changes

WebLogic Server users need to make the following environment changes:

• Create Java clients or servers.

• Create a WebLogic Tuxedo Connector XML configuration file.

• Deploy WebLogic Tuxedo Connector on the WebLogic Tuxedo Connector.

  Note: For more information on creating WebLogic Tuxedo Connector clients or servers, see the WebLogic Tuxedo Connector ATMI Programmer's Guide.

WebLogic Server ThreadPoolSize

The number of client threads available when dispatching services from the gateway may limit the number of concurrent services running. For this release of WebLogic Tuxedo Connector, there is no WebLogic Tuxedo Connector XML configuration file parameter such as MAXDISPATCHTHREADS or MINDISPATCH threads. Use a reasonable thread model when invoking service EJBs. You may need to increase the WebLogic Server threadpool size in theWebLogic Server config.xml file to a large value.

Example: ThreadPoolSize="70".

For more information on WebLogic Server performance and tuning, see BEA WebLogic Server Performance and Tuning, Release 6.0.

Installing the WebLogic Tuxedo Connector

You install the WebLogic Tuxedo Connector as a WebLogic Server startup class and a WebLogic Server shutdown class.

Use the following steps to install the WebLogic Tuxedo Connector on your system.

1. Download the WebLogic Tuxedo Connector Release 1.0 distribution from the BEA Download Center, located at http://www.beasys.com/download.shtml. The WebLogic Tuxedo Connector is available from the Tuxedo 8.0 download page.

2. Execute the WebLogic Tuxedo Connector install program.

   - Windows NT/2000: run the wtc10_win.exe file

   - UNIX: run the wtc10_unix.bin file

3. Click NEXT.

   

4. Read the License Agreement.

5. Click Yes.

1. Click Next.

2. Select Full Installation.

1. Click Next.

2. Select a BEA home directory.

   • If you have an existing BEA directory, click NEXT.

   • If you want to create a new BEA directory, click Create a New BEA Home. Specify the new directory location and click NEXT.

1. Select a directory for the WebLogic Tuxedo Connector and click Install.

2. The installation is complete. Click Done.

Configuring WebLogic Tuxedo Connector for Your Applications

Note: This release of the WebLogic Tuxedo Connector provides only static configuration. If you need to change any parameters in the XML configuration file, the WebLogic Server must be restarted for the changes to take effect. For example, you can not add or remove domain network links, change network addresses, or import or export new services.

This section provides an information on how to configure the WebLogic Tuxedo Connector to allow WebLogic Server applications and Tuxedo applications to interoperate. Use the following main steps to configure the connector:

• Create a Configuration File

• Set the WebLogic Server Domain Environment

• Update the Start Server Script

• Create a StartUp Class

• Create a Shutdown Class

• Deploy EJBs

• Restart the Application Server

• Verify Installation

Create a Configuration File

The WebLogic Tuxedo Connector uses an XML configuration file to describe the Tuxedo /T DOMAINS connections used to link WebLogic Server to Tuxedo.

Note: This file must be installed on all WebLogic Server with JATMI instances.

• Create an XML configuration file by using a text editor, such as vi or WordPad.

• The most efficient method to create a new configuration file is to modify one of the example configuration files located in the WebLogic Tuxedo Connector distribution examples directory, such as: \examples\simpapp\bdmconfig.xml

• Save the configuration file with your WebLogic Server application.

  Note: For more information on configuration file hierarchy and element definitions, see The WebLogic Tuxedo Connector XML Configuration File.

Configuration File Components

A WebLogic Tuxedo Connector configuration file consists of the following sections:

• Version

• DOCTYPE Declaration

• WTC_CONFIG

• BDMCONFIG

• tBridge

Version

Required.Specifies the version of XML used.

Example: <?xml version="1.0"?>

DOCTYPE

Note: You must modify the DOCTYPE with the name of your configuration file and specify the fully qualified path to its location.

Required.The DOCTYPE declaration provides the location of the wtc_config.dtd. When the WebLogic Server is started, the WebLogic Tuxedo Connector XML configuration file is checked against the document type definition (DTD) for errors.

Example:

<!DOCTYPE <your configuration file name> SYSTEM "file:<the WTC installation directory>\weblogic\wtc\gwt\wtc_config_1_0.dtd">

WTC_CONFIG

Required. WTC_CONFIG element is the root of the configuration file. WTC_CONFIG has two children:

• BDMCONFIG

• tBridge

BDMCONFIG

Required. BDMCONFIG describes connectivity information and security protocols used by the WebLogic Tuxedo Connector to process service requests between WebLogic Server and Tuxedo. These configuration parameters are analogous to the interoperability attributes required for communication between Tuxedo domains.

Note: For more information on how to configure BDMCONFIG, see Configuring BDMCONFIG.

tBridge

Optional. The tBridge is a bi-directional JMS interface to imported Tuxedo services. Configuring this section causes the tBridge to start as part of the WebLogic Server application environment.

Note: For more information on how to configure the tBridge, see Configuring tBridge.

Validate the XML file

Validate your configuration file using WTCValidateCF. This utility allows you to validate the XML configuration file before booting WebLogic Server.

To validate the XML configuration file, enter the following command:

 > java weblogic.wtc.gwt.WTCValidateCF your_XML_configuration_file

where your_XML_configuration_file is the name of your XML configuration file.

Set the WebLogic Server Domain Environment

Update the domain environment of your WebLogic Server application that you will use with the WebLogic Tuxedo Connector. Use the following steps to add the pathname of the jamti.jar file to your application's CLASSPATH.

1. From the command line, change directories to the location of the WebLogic Server application.

2. Edit the setEnv file with a text editor, such as vi or WordPad.

   - NT/2000 users: edit setEnv.cmd

   - UNIX users: edit setEnv.sh

   Note: The setExamplesEnv file is used to set the environment for the WebLogic Tuxedo Connector examples provided with your distribution.

3. Add the pathname of the jamti.jar file to the CLASSPATH.

   Example:

   set HOME=D:\bea\wlserver6.0sp1

   set JAVA_HOME=D:\bea\jdk130

   set CLASSPATH=%JAVA_HOME%\lib\tools.jar;D:\bea\wtc1.0\lib\jamti.jar;%HOME%\lib\weblogic_sp.jar;%HOME%\lib\weblogic.jar;%CLASSPATH%

4. Save the file.

5. Set your application environment.

   - NT/2000 users: run setEnv.cmd

   - UNIX users: run setEnv.sh

   The domain environment is updated.

Update the Start Server Script

Update the script that starts WebLogic Server. Use the following steps to add the pathname of the WebLogic Tuxedo Connector jamti.jar file to the CLASSPATH of your WebLogic Server.

1. Edit the startWebLogic file with a text editor, such as vi or WordPad.

   - NT/2000 users: edit startWebLogic.cmd

   - UNIX users: edit startWebLogic.sh

2. Add the pathname of the jamti.jar file to the CLASSPATH.

   Example:

   set CLASSPATH=.;.\lib\weblogic_sp.jar;d:\bea\wtc1.0\lib\jatmi.jar;.\lib\weblogic.jar;

3. Save the file.

4. Run startWebLogic.

   - NT/2000 users: run startWebLogic.cmd

   - UNIX users: run startWebLogic.sh

   WebLogic Server starts.

Create a StartUp Class

Create a startup class and assign the location of the configuration file as a property of the startup class. Use the following steps to create a Startup Class for a domain:

1. Start the WebLogic Server Console.

2. If necessary, right-click on the domain root and select Create or edit other domains. Left-click to select a domain from the repository.

3. Left-click and expand the Deployments branch.

4. Right-click on the Startup & Shutdown branch.

5. Select Create a new Startup Class . . .

   The Configuration tab is active.

6. Enter the Name.

   Example: MyWTCStartup Class

7. Enter weblogic.wtc.gwt.WTCStartup for the Classname.

8. Enter the Arguments. If more than one argument is used, separate them using a comma. Valid arguments include:

   BDMCONFIG: This required argument specifies the location of the WebLogic Tuxedo Connector XML configuration file.

   Example: BDMCONFIG=.\config\mydomain\wtc_config.xml

   • TraceLevel: This optional argument specifies the level of error tracing used.

     Example: BDMCONFIG=.\config\mydomain\wtc_config.xml,TraceLevel=100000

   • PasswordKey: This optional argument specifies the password key used for encrypting passwords when configuring local and remote domains.

     BDMCONFIG=.\config\mydomain\wtc_config.xml,PasswordKey=mykey

9. Check Abort startup on failure.

10. Click Create.

11. Select the Target tab.

12. From the Available servers list, click on the server you wish to select.

    The server is highlighted.

13. Click on the right-arrow.

    The selected server appears in the Chosen servers list.

14. Click Apply.

Create a Shutdown Class

Use the following steps to create a shutdown class for a domain:

1. Right-click on the Startup & Shutdown branch.

2. Select Create a new Shutdown Class . . .

3. Enter the Name.

   Example: MyWTCShutdown Class

4. Enter weblogic.wtc.gwt.WTCShutdown for the Classname.

5. Click Create.

Deploy EJBs

Deploy any EJBs that are referenced in the WebLogic Tuxedo Connector XML configuration file.

Restart the Application Server

To make the console changes active, you must shut down and restart the application server.

Verify Installation

Check the WebLogic Server log file. If the WebLogic Tuxedo Connector started properly, messages similar to those shown below are displayed:

####<Apr 20, 2001 10:55:08 PM EDT> <Info> <WTC> <mymachine> <myserver> <Thread-1> <system> <> <180001> <Done Loading the XML config file.>

####<Apr 20, 2001 10:55:08 PM EDT> <Debug> <WTC> <mymachine> <myserver> <Thread-2> <> <> <180056> <[/WTCStartup/run/>

####<Apr 20, 2001 10:55:08 PM EDT> <Debug> <WTC> <mymachine> <myserver> <Thread-2> <> <> <180056> <]/WTCStartup/run/05>

####<Apr 20, 2001 10:55:09 PM EDT> <Info> <WebLogicServer> <randyr-nt> <myserver> <Thread-1> <system> <> <000288> <weblogic.wtc.gwt.WTCStartup reports: WTC started...>

Check the WebLogic Server config.xml file. The WebLogic Tuxedo Connector configuration is added to the WebLogic Server StartUp and Shutdown Classes.

<StartupClass Arguments="BDMCONFIG=d:\wtc_load4\examples\simpapp\bdmconfig.xml" ClassName="weblogic.wtc1.0.gwt.WTCStartup" FailureIsFatal="false" Name="MyWTCStartup Class" Targets="myserver"/>

<ShutdownClass Arguments="" ClassName="weblogic.wtc1.0.gwt.WTCShutdown" Name="MyWTCShutdown Class"/>

Note: If your installation is not successful, see Troubleshooting The WebLogic Tuxedo Connector.

Uninstalling the WebLogic Tuxedo Connector

This section describes how to remove the WebLogic Tuxedo Connector from WebLogic Server and from your system.

Removing WebLogic Tuxedo Connector from WebLogic Server

This section provides an information on how to remove the WebLogic Tuxedo Connector using the WebLogic Server Console:

1. Shutdown the WebLogic Server instance that uses WebLogic Tuxedo Connector.

2. Remove necessary EJBs.

3. Remove the StartUp class.

4. Remove the Shutdown class.

5. Remove the path to the jamti.jar file from the CLASSPATH of the setEnv.cmd or setEnv.sh file.

6. Remove the path to the jamti.jar file from the CLASSPATH of the startWebLogic.cmd or startWebLogic.cmd file.

7. Restart WebLogic Server.

The WebLogic Tuxedo Connector is removed from your WebLogic Server application.

Removing WebLogic Tuxedo Connector from the System

This section provides information on how to remove WebLogic Tuxedo Connector from your system.

GUI

Use the following steps to uninstall WebLogic Tuxedo Connector using the GUI.

1. Click the Windows Start button.

2. Select Programs > BEA WebLogic E-Business Platform > BEA WebLogic Tuxedo Connector 1.0 > uninstallwtc10_win.

Command Line

Use the following steps to uninstall the WebLogic Tuxedo Connector from a command line:

1. Change directories to the WebLogic Tuxedo Connector uninstaller directory.

2. Run the uninstall program.

   • Windows NT: run the uninstallwtc10_win.exe file.

   • Unix: run the uninstallwtc10_Unix.bin file.

Using the Uninstaller

1. Click Uninstall.

1. Click Exit.