EJB-to-Tuxedo Simpapp Sample Application

 

This topic includes the following sections:

• How the EJB-to-Tuxedo Simpapp Sample Application Works

• Building and Running the EJB-to-Tuxedo Simpapp Sample Application

• Stopping the EJB-to-Tuxedo Simpapp Sample Application

  Note: Each sample application directory tree provided with the WebLogic Enterprise software includes a Readme.txt file that explains how to build and run the sample. Refer to this file in the following directory for troubleshooting information or other last-minute information about using the EJB-to-Tuxedo Simpapp sample application.

  Windows NT

  $TUXDIR\samples\interop\ejb_tux

  UNIX

  $TUXDIR/samples/interop/ejb_tux

 

---

How the EJB-to-Tuxedo Simpapp Sample Application Works

This topic includes the following sections:

• Key Application Components

• Application Flow

• Software Prerequisites

• Example Code

The EJB-to-Tuxedo Simpapp sample application demonstrates the use of Java Enterprise Tuxedo (JET) technology to invoke a Tuxedo service from an EJB server running in the WebLogic Enterprise EJB container. For more information about JET, See Using Java Enterprise Tuxedo.

Key Application Components

The EJB-to-Tuxedo Simpapp sample application consists of the following main components:

• An EJB client (SimpClient) prompts the user for a string and then invokes methods on the EJB, upper and lower, to convert the string to all uppercase and all lowercase text, respectively. This client then displays the results of the conversion to the user.

• An Enterprise JavaBean (SimpBean) acts as the bridge between the WebLogic Enterprise and Tuxedo environments. This object provides the following methods to handle the conversion:

  • The upper method calls another method, joltNativeCall, which instantiates a JoltService object and uses the call method to invoke the TOUPPER service in the Tuxedo environment. The JoltService class is a component of the JET Class Library.

  • The lower method uses the Java toLowerCase method to perform the lowercase conversion.

• The TOUPPER service in the Tuxedo environment, which converts a text string to all uppercase characters.

Application Flow

Figure 5-1 illustrates how the EJB-to-Tuxedo Simpapp sample application works.

Figure 5-1 Overview of the EJB-to-Tuxedo Simpapp Sample Application

Software Prerequisites

In order to invoke a Tuxedo service using JET, you need to install Visual C++ version 6.0 with Service Pack 3 or later for Visual Studio.

Example Code

Listing 5-1 shows the joltNativeCall method from the SimpBean EJB in the EJB-to-Tuxedo Simpapp sample application. This method uses JET technology to invoke the TOUPPER service in the Tuxedo environment. It accepts the following parameters:

• svcName is the name of the Tuxedo service to invoke (TOUPPER).

• data is the string that the user entered in the SimpClient client.

  Listing 5-1 The joltNativeCall() Method in the SimpBean EJB

  ---

    String joltNativeCall (String svcName, String data)
    {
      JoltService svc;
  
      try {
        svc = new JoltService (svcName);
        svc.addString("STRING", data);
        svc.call (null);
      } catch (ServiceException e) {
        System.out.println("JoltService got "+e);
        return new String("");
      }
  
      return svc.getStringDef("STRING", "no_response");
    }

  ---

The joltNativeCall method performs the following operations:

• Instantiating a new JoltService object to represent the Tuxedo TOUPPER service. The JoltService class is part of the JET Class Library. For more information about the JET Class Library, see Using Java Enterprise Tuxedo.

• Calling the addString method on the JoltService object to set up the input parameters to the TOUPPER service: the conversion type ("STRING") and the string to convert (data).

• Calling the call method to invoke the TOUPPER service.

• Returning the results to the calling method, upper(), in the SimpBean EJB.

 

---

Building and Running the EJB-to-Tuxedo Simpapp Sample Application

This section includes the following steps to build the EJB-to-Tuxedo Simpapp sample application:

• Step 1: Verify the Settings of Environment Variables

• Step 2: Copy the Files into a Work Directory

• Step 3: Change the Protection Attribute on the Files for the EJB-to-Tuxedo Simpapp Sample Application

• Step 4: Run the EJB-to-Tuxedo Simpapp Sample Application

Step 1: Verify the Settings of Environment Variables

Before building and running the EJB-to-Tuxedo Simpapp sample application, you need to ensure that certain environment variables are set on your system. In most cases, these environment variables are set as part of the installation procedure. However, you need to check the environment variables to ensure that they reflect correct information.

Required Environment Variables

Table 5-1 describes the environment variables that are required to run the EJB-to-Tuxedo Simpapp sample application.

Table 5-1 Required Environment Variables for the EJB-to-Tuxedo Simpapp Sample Application

Environment Variable	Description
TUXDIR	The directory path where you installed the WebLogic Enterprise software. For example: Windows NT TUXDIR=c:\WLEdir UNIX TUXDIR=/usr/local/WLEdir
JAVA_HOME	The directory path where you installed the JDK software. For example: Windows NT JAVA_HOME=c:\JDK1.2.2 UNIX JAVA_HOME=/usr/local/JDK1.2.2

Optional Environment Variables

You may optionally set the following system environment variables to change their default value before running the EJB-to-Tuxedo Simpapp sample runme command. See the Administration Guide for more information about selecting appropriate values for these environment variables.

Table 5-2 describes the optional environment variables that you can set before running the EJB-to-Tuxedo Simpapp sample application.

Table 5-2 Optional Environment Variables for the EJB-to-Tuxedo Simpapp Sample Application

Environment Variable	Description
HOST	The host name portion of the TCP/IP network address used by the ISL process to accept connections from CORBA. The default value is the name of the local machine.
PORT	The TCP port number at which the ISL process listens for incoming requests. It must be a number between 0 and 65535. The default value is 2468.
IPCKEY	The address of shared memory. It must be a number greater than 32769 that is unique to this application on this system. The default value is 55432.

Verifying the Environment Variables

To verify that the information for the environment variables defined during installation is correct, complete the following steps:

Windows NT

1. From the Start menu, select Settings.

2. From the Settings menu, select the Control Panel.

   The Control Panel appears.

3. Click the System icon.

   The System Properties window appears.

4. Click the Environment tab.

   The Environment page appears.

5. Check the settings for TUXDIR and JAVA_HOME.

UNIX

1. Execute the ksh command to use the Korn shell.

2. Execute the printenv command to display the values of TUXDIR and JAVA_HOME, as shown in the following example:

   ksh prompt>printenv TUXDIR
   ksh prompt>printenv JAVA_HOME

Changing the Environment Variables

To change the environment variable settings, complete the following steps:

Windows NT

1. From the Start menu, select Settings.

2. From the Settings menu, select the Control Panel.

   The Control Panel appears.

3. Click the System icon.

   The System Properties window appears.

4. Click the Environment tab.

   The Environment page appears.

5. On the Environment page in the System Properties window, click the environment variable you want to change, or enter the name of the environment variable in the Variable field.

6. Enter the correct information for the environment variable in the Value field.

7. Click OK to save the changes.

UNIX

1. Execute the ksh command to use the Korn shell.

2. Execute the export command to set the correct values for the TUXDIR and JAVA_HOME environment variables, as in the following example:

   ksh prompt>export TUXDIR=directorypath
   ksh prompt>export JAVA_HOME=directorypath

Step 2: Copy the Files into a Work Directory

You need to copy the files for the EJB-to-Tuxedo Simpapp sample application into a work directory on your local machine. The files for the EJB-to-Tuxedo Simpapp sample application are located in the following directories under TUXDIR:

Windows NT

$TUXDIR\samples\interop\ejb_tux

UNIX

$TUXDIR/samples/interop/ejb_tux

Copying the Files

The following steps describe how to execute a makefile to copy all of the example files into a work directory.

1. Create the work directory on your machine.

2. Copy the entire ejb_tux directory to the working directory created in the previous step:

   Windows NT

   > copy $TUXDIR\samples\interop\ejb_tux\*.* <work_directory>

   UNIX

   > cp -R $TUXDIR/samples/interop/ejb_tux/* <work_directory>

3. Change to the working directory created in step 1.

4. Execute the following command, which copies the remaining EJB-to-Tuxedo Simpapp sample application files to the working directory:

   Windows NT

   >nmake -f makefile.nt copy

   UNIX

   >make -f makefile.mk copy

Files Copied to the Working Directory

This section describes the files that were copied into your working directory when you executed the makefile.

Utility Files

Table 5-3 describes the utility files for this sample application. These files reside in the root of the working directory.

Table 5-3 Utility Files in the Root of the Working Directory

File	Description
Readme.txt	Contains directions for building and executing the EJB-to-Tuxedo Simpapp sample application.
runme.cmd	Windows NT batch file that contains commands to build and execute the EJB-to-Tuxedo Simpapp sample application.
runme.ksh	UNIX Korn shell script that contains commands to build and execute the EJB-to-Tuxedo Simpapp sample application.
makefile.nt	Common makefile for the EJB-to-Tuxedo Simpapp sample application on the Windows NT platform. This makefile can be used directly by the Visual C++ nmake command.
makefile.mk	Makefile for the EJB-to-Tuxedo Simpapp sample application on the UNIX platform.

EJB Files

Table 5-4 describes the files that are needed to create the EJB client and EJB server for this sample application. These files reside in the ejb subdirectory of the working directory.

Table 5-4 EJB Files in the ejb Subdirectory

File	Description
SimpClient.java	The EJB client application that calls methods on the SimpBean object.
SimpBean.java	The Java source code for the SimpBean class. This is an example of a stateless session bean. This bean contains the methods that are invoked by the SimpClient class.
Simp.java	The Java source code for the Remote interface of the SimpBean class.
SimpHome.Java	The Java source code for the Home interface of the SimpBean class.
weblogic-ejb-extensions.XML	The XML file specifying the WebLogic EJB extensions to the deployment descriptor DTD.
ejb-jar.xml	The standard deployment descriptor for the SimpBean class.

Tuxedo Files

Table 5-5 describes the source files for the Tuxedo portion of this sample application. These files reside in the tux subdirectory of the working directory.

Table 5-5 Tuxedo Files in the tux Subdirectory

File	Description
jrepository	Jolt Repository definition file.
simpserv.c	Simpapp server source code.

Step 3: Change the Protection Attribute on the Files for the EJB-to-Tuxedo Simpapp Sample Application

During the installation of the WebLogic Enterprise software, the sample application files are marked read-only. Before you can edit or build the files in the EJB-to-Tuxedo Simpapp sample application, you need to change the protection attribute of the files you copied into your work directory (including the respective ejb and corbaj subdirectories), as follows:

Windows NT

prompt>attrib /S -r drive:\workdirectory\*.*

UNIX

prompt>/bin/ksh
ksh prompt>chmod +w /workdirectory/*.*

On UNIX, you also need to change the permission of runme.ksh to give execute permission to the file, as follows:

ksh prompt>chmod +x runme.ksh

Step 4: Run the EJB-to-Tuxedo Simpapp Sample Application

Once you have copied the files and changed their protection attributes, you can build and run the EJB-to-Tuxedo Simpapp sample application by executing the runme command, which starts server processes, generates files in various subdirectories of the working directory, and starts the sample application.

Executing the runme Command

The runme command automates the following steps:

1. Set the system environment variables.

2. Load the UBBCONFIG file.

3. Compile the code for the EJB server object.

4. Compile the code for the Jet Server application.

5. Start the server application using the tmboot command.

6. Start the client application.

7. Stop the server application using the tmshutdown command.

To build and run the CORBA/Java Simpapp sample application, execute the runme command, as follows:

Windows NT

prompt>cd workdirectory

prompt>runme

UNIX

ksh prompt>cd workdirectory

ksh prompt>./runme.ksh

The EJB-to-Tuxedo Simpapp sample application runs and prints the following messages:

Testing simpapp
    cleaned up
    prepared
    built
    loaded ubb
    booted
    ran
    shutdown
    saved results
  PASSED

All of the sample application output is placed in the results directory. You can check in that directory for the following files:

• The .log file, for any compile, server boot, or server shutdown errors.

• The ULOG file for server application errors and exceptions.

• The output file for EJB client application output and exceptions.

Running the Sample Application Manually

After you have executed the runme command one time, you can subsequently run the EJB-to-Tuxedo Simpapp sample application manually.

To run the EJB-to-Tuxedo Simpapp sample application manually:

1. Verify that your environment variables are correct by entering the following command:

   Windows NT

   prompt>results\setenv

   UNIX

   prompt>. results/setenv.ksh

2. Run the sample:

   Windows NT

   prompt>tmboot -y
   prompt>java -classpath %CLIENTCLASSPATH% ejb.SimpClient corbaloc:%TOBJADDR%

   UNIX

   prompt>tmboot -y
   prompt>java -classpath ${CLIENTCLASSPATH} ejb.SimpClient corbaloc:${TOBJADDR}

3. To run the CORBA/C++ joint client/server application, enter a string. After you enter the string, the application returns the string in uppercase and lowercase characters, respectively:

   String?
   Hello World
   HELLO WORLD
   hello world

All of the sample application output is placed in the results directory. You can check in that directory for the following files:

• The .log file, for any compile, server boot, or server shutdown errors.

• The ULOG file for server application errors and exceptions.

• The output file for EJB client application output and exceptions.

Server Processes Started by the Sample Application

Table 5-6 describes the server processes that are started when the tmboot command is executed to start the EJB-to-Tuxedo Simpapp sample application.

Table 5-6 Server Processes Started When tmboot Is Executed

Process	Description
TMSYSEVT	The BEA Tuxedo system Event Broker.
TMFFNAME	Starts the following TMFFNAME processes: The TMFFNAME server process with the -N option and the -M option is the MASTER NameManager service. The -N option says to start the NameManager Service. The -M option says to start this name manager as a Master. This service maintains a mapping of application-supplied names to object references. The TMFFNAME server process with the -N option only is a SLAVE NameManager service. The TMFFNAME server with the -F option contains the FactoryFinder object.
JavaServer	The Simpapp server process that implements EJB-JAR file for the SimpBean and SimpHome interfaces. The JavaServer has one argument, SimpleEjb.jar, which is the EJB Java ARchive (JAR) file that was created for the application.
JREPSVR	Jolt Repository Server, which manages the Jolt Repository. The Jolt Repository contains service definitions for BEA Tuxedo services.
ISL	The IIOP Listener/Handler.

Files Generated by the Sample Application

This section describes the files that are generated in various subdirectories of the working directory.

File Generated in the .adm Subdirectory

Table 5-7 describes the file that is generated in the .adm subdirectory.

Table 5-7 File in the .adm Subdirectory

File	Description
.keydb	Generated by the tmloadcf command. Contains the security encryption key database.

File Generated in the ejb Subdirectory

Table 5-10 describes the file that is generated in the ejb subdirectory.

Table 5-8 File Generated in the ejb Subdirectory

File	Description
ejb.jar	EJB client archive file that is generated by the make or nmake command.

Files Generated in the tux Subdirectory

Table 5-9 describes the files that are generated in the tux subdirectory.

Table 5-9 File Generated in the tux Subdirectory

simpserv.exe	Simpapp server object file that is generated by the buildserver command.
simpserv.obj	Simpapp server object file.

Files Generated in the results Subdirectory

Table 5-10 describes the files that are generated in the results subdirectory.

Table 5-10 Files Generated in the results Subdirectory

File	Description
input	Generated by the runme command. Contains the input that runme gives to the SimpClient Java application.
output	Generated by the runme command. Contains the output that is produced when runme executes the SimpClient Java application.
expected_output	Generated by the runme command. Contains the output that is expected when the SimpClient Java application is executed by the runme command. The data in the output file is compared with the data in the expected_output file to determine whether the test passed or failed.
log	Generated by the runme command. Contains the output generated by the runme command. If the runme command fails, check this file, and the ULOG file, for errors.
setenv.cmd	Generated by the Windows NT runme.cmd command. Contains the commands to set the environment variables needed to build and execute the EJB-to-Tuxedo Simpapp sample application.
setenv.ksh	Generated by the UNIX runme.ksh command. Contains the commands to set the environment variables needed to build and execute the Simpapp sample application.
stderr	Generated by the tmboot command, which is executed by the runme command. If the -noredirect server option is specified in the UBBCONFIG file, the System.err.println method sends the output to stderr instead of to the ULOG user log file.
stdout	Generated by the tmboot command, which is executed by the runme command. If the -noredirect server option is specified in the UBBCONFIG file, the System.out.println method sends the output to the stdout file instead of to the ULOG user log file.
tmsysevt.dat	Generated by the tmboot command, which is executed by the runme command. It contains filtering and notification rules used by the TMSYSEVT (system event reporting) process.
tuxconfig	Generated by the tmloadcf command, which is executed by the runme command.
ubb	The UBBCONFIG file for the EJB-to-Tuxedo Simpapp sample application.
ULOG.<date>	A log file that contains messages generated by the tmboot command.

 

---

Stopping the EJB-to-Tuxedo Simpapp Sample Application

Before using another sample application, use the following procedure to stop the EJB-to-Tuxedo Simpapp sample application and to remove unnecessary files from the work directory:

1. Stop the application:

   Windows NT

   prompt>tmshutdown -y

   UNIX

   ksh prompt>tmshutdown -y

2. Restore the working directory to its original state:

   Windows NT

   prompt>nmake -f makefile.nt clean

   UNIX

   prompt>. ./results/setenv.ksh
   prompt>make -f makefile.nt clean