Chapter 4   Tuxedo Sample


The Tuxedo sample applications enables you to run a Tuxedo sample application to help familiarize you with the Tuxedo Enterprise Connector. This chapter contains the following information:

• Running the Tuxedo Online Bank Example

• Additional Tuxedo OnlineBank Sample Information

• About the Tuxedo OnlineBank Example

• Sample Overview

• Writing Tuxedo Applications

• Exception Handling

Running the Tuxedo Online Bank Example

---

BEA Tuxedo comes with a sample application called bankapp. This is in <Tuxedo/APPS/bankapp> directory. On the Tuxedo server side, make sure that this application is built, configured and running properly.

Please refer to Tuxedo Application Development Guide for instructions on how to configure this application. Also, the Tuxedo workstation client comes with a client version of the same application, which is a GUI-based workstation client.

1. Make sure the bankapp Tuxedo server is up and running and is configured properly. To doublecheck this, on the machine where iPlanet Application Server for Tuxedo is installed, compile and run the Workstation client application that ships with BEA Tuxedo and is in directory <TuxedoW/APPS/ws>. (Note that Tuxedo /WS software should be present in the machine where iPlanet Application Server for Tuxedo is installed).

2. Double check the datasource Tuxedo-OnlineBank configuration structure in bspbrowser for the configuration information settings like WSNADDR, WSDEVICE and TUXDIR.

3. On Solaris system, make sure that the environment variables LD_LIBRARY_PATH includes the tuxedo workstation libraries directory (<TUXWSDIR/lib>).

Once these steps are done correctly, this sample application will run without any problem.

Use account numbers for testing in the range of 100001 - 100007 etc.

(See bankapp server source for more information of valid account numbers).

Additional Tuxedo OnlineBank Sample Information

---

The iPlanet Application Server 6.0 for Tuxedo is a highly scalable web connectivity solution to the BEA Tuxedo system . The solution enables HTTP servlets/EJBs running in the iPlanet Application Server 6.0 J2EE Application to call the services of the BEA Tuxedo system. The iPlanet Application Server 6.0 for Tuxedo enables Tuxedo applications to be web-enabled, using the iPlanet Application Server 6.0 as an HTTP and application server.

Key features

Key features of this architecture include:

• Enables use of Java HTTP servlets/EJBs to provide a dynamic HTML frontend for Tuxedo applications

• Provides session pooling to use Tuxedo resources efficiently

• Provides extensive failover capabilities

• Highly scalable solution

• Supports client side transactions
  Integrates session pool management into the iPlanet Application Server 6.0 for Tuxedo Management Console  

About the Tuxedo OnlineBank Example

---

This section provides step-by-step information on understanding and running the The iPlanet Application Server 6.0 for Tuxedo OnlineBank example, a J2EE application to access a Tuxedo service that calls various services for banking.

There are two parts to the OnlineBank example: the J2EE application that is shipped with the The iPlanet Application Server 6.0 for Tuxedo examples, and the Tuxedo service application (bankapp) that is shipped with the Tuxedo examples.

The Tuxedo bankapp server contains the services WITHDRAWAL, DEPOSIT, TRANSFER, INQUIRY, CLOSE_ACCT, OPEN_ACCT. The INQUIRY service accepts the integer input FML field ACCOUNT_ID and returns a string result FML field SBALANCE.

You can find the source code for the TuxBank example in the <iASinstallation/ias/APPS/TuxBank  directory.

Here is what you'll find in the TuxBank example directory:

File Name	Description
BankServlet.java	Sample Servlet that calls the BankManagerBean EJB which inturn calls tuxedo
IbankManager.java IbankManagerHome.java BankManagerBean.java	The stateless EJB which calls the tuxedo service
jsp/AccountCloseForm.jsp jsp/AccountOpenForm.jsp jsp/BalanceQueryForm.jsp jsp/Copyright.jsp jsp/DepositAmountForm.jsp jsp/ErrorPage.jsp jsp/Footer.jsp jsp/Header.jsp jsp/MainMenu.jsp jsp/ShowAccountClose.jsp jsp/ShowAccountOpen.jsp jsp/ShowBalance.jsp jsp/ShowDeposit.jsp jsp/ShowTransfer.jsp jsp/ShowWithdrawl.jsp jsp/TransferAmountForm.jsp jsp/WithdrawAmountForm.jsp	JSPs for the J2EE application. XXXForm.jsp displays a form for input and when the user submits the form, calls the Servlet BankServlet.java which inturn does trivial validation and calls the EJB BankManager which inturn forwards the request to the Tuxedo System using BSP API. The response is taken and sent back to the servlet which inturn calls a JSP ShowXXX.jsp to display the results back to the user. In case of Error, ErrorPage.jsp is shown with appropriate error message.
Tuxbank.ear	The J2EE packaged application. Register it with nas using command "j2eeappreg tuxbank"

The iPlanet Application Builder 6.0 can be used to rapidly develop applications like these in a short period of time. The entire Tuxedo OnlineBank Example was developed and tested using iAB 6.0.

A complete listing of the Tuxedo server-side source code of the bankapp application service is located in the Tuxedo distribution in the $TUXDIR/apps/bankapp where $TUXDIR is the Tuxedo home directory.

To run this example, you should be familiar with:

1. The Tuxedo architecture and the sample application, simpapp

2. The iPlanet Application Server 6.0 for Tuxedo

3. HTML

4. Java language, Servlet API and EJB API, J2EE

5. UIF API

Sample Overview

---

The TuxBank  example is easy to follow. Just launch the http://<hostname/GXApp/TuxBank page from the web Server and select the MainMenu link. The remaining steps are self explanatory.

Select one of the options in the menu for example, Deposit. The deposit form is displayed. Enter the account number and the deposit amount and click the SUBMIT button to submit the request.

The BankServlet calls the EJB BankManager which then uses the UIF API to populate the input data for the Tuxedo service, calls the service, gets back the results which are passed back to servlet which forwards the data to the JSP, which finally displays the results.

1. Getting started checklist

   Check that you have a supported browser (Netscape or IE, later than 3.2) installed on your client machine. The client machine must have a network connection to the iPlanet Application Server 6.0 for Tuxedo that is used to connect to the Tuxedo environment.

2. Configure and boot Tuxedo and the bankapp example.

   Follow the directions in the Tuxedo user documentation to bring up the server-side bankapp application. Make sure the WITHDRAWAL, DEPOSIT, TRANSFER, INQUIRY, CLOSE_ACCT, OPEN_ACCT services are available.

Set up the data source for the iPlanet Application Server 6.0 for Tuxedo. See the earlier chapters on Installation and Administration, for a review of the required steps.

Ensure that the WITHDRAWAL, DEPOSIT, TRANSFER, INQUIRY, CLOSE_ACCT, OPEN_ACCT services are defined in the iPlanet Application Server 6.0 for Tuxedo data source Repository.

The bankapp repository definition is provided in <iasinstallation/ias/APPS/adapters/tux/samples/metadata/BankDataSource.xml.

Import this xml file into the repository after the required modifications.

Writing Tuxedo Applications

---

Calling a configured and imported service from a servlet/ejb :

1. Packages

To use the iPlanet Application Server 6.0 for Tuxedo, import the following into your servlet/EJBs:

import netscape.bsp.*;
import netscape.bsp.runtime.*;
import netscape.bsp.dataobject.*;

2. Configuring data Source and services in repository

Use the Tuxedo management console to create/edit data source (tuxconsole.bat or tuxconsole.sh).

Use fmlminer command line utility to mine the fml/fml32 tables into the repository. Use viewminer command line utility to mine the view/view32/xcommon/xctype tables into the repository.

Define the services in Jolt Bulk Loader format and import them inside the repository using the joltmigrator tool. The OnlineBank application sevices are defined in Jolt Bulk Loader format and are present in the <ias installation/ias/APPS/TuxBank/joltbankfo.txt> file.

3. Getting a runtime instance (refer to the UIF API Reference)

In a servlet/EJB using, com.kivasoft.IContext ctx = com.kivasoft.util.GX.GetContext();

IBSPRuntime ibspruntime = access_cBSPRuntime.getcBSPRuntime(ctx, null, null);

4. Getting the service provider (refer to UIF API Reference)

IBSPServiceProvider sp = runtime.createServiceProvider("Tuxedo-OnlineBank", "tuxConnection");

where "Tuxedo-OnlineBank" is the data source name and "tuxConnection" is the type of the service provider requested (in this case it is a non transactional service provider. If you give tuxConnectionTx, we get a transactional tuxedo service provider on which we can call tuxedo services under client side transaction.

5. Calling a tuxedo service
   1. Setting the security attributes (if a service expects any)

      IBSPDataObject config = sp.getConfig();

      if (config 1) != null) { config.setAttrString("WebUserId", "webuser-smith"); }

   2. Creating a function object

      fn = runtime.createFunctionObject("Tuxedo-OnlineBank", "BalanceInquiry");

   3. Enabling the service provider

      hr = sp.enable();

   4. Preparing the service provider and setting up

      hr = fn.useServiceProvider(sp);

      hr = fn.prepare("callService");

   5. Populating the input data

      data = fn.getDataBlock();

      data.setAttrInt("INPUT.inputBlock.ACCOUNT_ID", Integer.parseInt(accountNumber));

   6. Calling the service

      hr = fn.execute();

   7. Getting the output results from the service

      String outputBalance = data.getAttrString("OUTPUT.outputBlock.SBALANCE");

   8. Sisabling the data source

      sp.disable();

Converting DataObjects to Tuxedo Data Types

The following is a mapping between Java types and Tuxedo parameter types required by a Tuxedo service. Use the appropriate DO types for the value to the DataObject.

FML, FML32, VIEW, VIEW32, X_COMMON, X_C_TYPE   <--- struct

primitive STRING <-- string

primitive c_array, primitive X_OCTET <-- vbinary

FML/VIEW field types  <-- UIF types

char  int short <-- integer

long <-- integer

float <--  float

double <-- double

carray<-- vbinary

string <-- STRING

multiple occurence field of any of above type<-- array

Exception Handling

---

Errors or failures may occur when the Tuxedo Enterprise Connector initiates a Tuxedo service call that are reported to your application via Java exceptions. You should always enclose the execute() method within a try / catch block and attempt to deal with any exceptions appropriately. See the BankManagerBean.java EJB implementation source code for an example.

The execute() method can throw a runtime exception netscape.bsp.BSPException and the application program can catch and handle that exception appropriately.

The BSPException class instance that is thrown as an exception has methods to get more information regarding the actual exception. If the exception is due to a tuxedo system error, more information about the error can be retrieved by getting the info object on the exception by calling its getInfo() method and getting attributes errno and errstr in that.

Here is the code snippet:

catch (BSPException e) {

IBSPDataObjectStructure info = null;
errorMessage = "Error in service Execution : <br" +
"Error message from adapter : " +  e.getMessage() + "<br";
info=e.getInfo();
if (info != null) {
errorMessage += (info.attrExists("errno") ? " Tuxedo System Error code : " + info.getAttrInt("errno") + "<br" : "") +
(info.attrExists("errstr") ? " Tuxedo System Error string : " + info.getAttrString("errstr")  + "<br" : "");
}
}

The netscape.tux.TuxError has constants, which can be compared with the errno attribute return value for the tuxedo specific errors.