CORBA/Java-to-Tuxedo Simpapp Sample Application

 

This topic includes the following sections:

• How the CORBA/Java-to-Tuxedo Simpapp Sample Application Works

• Building and Running the CORBA/Java-to-Tuxedo Simpapp Sample Application

• Stopping the CORBA/Java-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 CORBA/Java-to-Tuxedo sample application:

  Window NT

  $TUXDIR\samples\interop\corbaj_tux

  UNIX

  $TUXDIR/samples/interop/corbaj_tux

 

---

How the CORBA/Java-to-Tuxedo Simpapp Sample Application Works

This topic includes the following sections:

• Key Application Components

• Application Flow

• OMG IDL Code for the CORBA/Java-to-Tuxedo Simpapp Interfaces

• Software Prerequisites

• Example Code

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

Key Application Components

The CORBA/Java-to-Tuxedo Simpapp sample application consists of the following components:

• A CORBA/Java client (SimpleClient) prompts the user for a string and then invokes methods on the CORBA/Java server, to_upper and to_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.

• A CORBA/Java server object (SimpleImpl) acts as the bridge between the WebLogic Enterprise and Tuxedo environments. This object provides the following methods to handle the conversion:

  • The to_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 to_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 4-1 illustrates how the CORBA/Java-to-Tuxedo Simpapp sample application works.

Figure 4-1 Overview of CORBA/Java-to-Tuxedo Simpapp Sample Application

OMG IDL Code for the CORBA/Java-to-Tuxedo Simpapp Interfaces

Table 4-1 describes the CORBA interfaces that are implemented in the CORBA/Java-to-Tuxedo Simpapp application.

Table 4-1 CORBA Interfaces Implemented in CORBA/Java-to-Tuxedo Simpapp Application

Interface	Description	Operation	Policies
SimpleFactory	Creates object references to the Simple object	find_simple()	Activation: method Transaction: optional
Simple	Converts the case of a string	to_upper() to_lower()	Activation: method Transaction: optional

Listing 4-1 shows the simple.idl file that defines the CORBA interfaces in the CORBA/Java-to-Tuxedo Simpapp sample application.

Listing 4-1 OMG IDL Code for the CORBA/Java-to-Tuxedo Simpapp Sample Application

---

#pragma prefix "beasys.com"
interface Simple
{
    // convert a string to lower case (return a new string)
    string to_lower(in    string val);

    // convert a string to upper case (in place)
    void   to_upper(inout string val);
};

interface SimpleFactory
{
    Simple find_simple();

   // To make simpapp scalable have the SimpleFactory use some means
   // to identify (specify in criteria) the user in the Simple object
   // reference it creates. eg. Name (string), SS# (unsigned long),
   // tel_no (string).
};

---

Software Prerequisites

To run the m3idltojava compiler that is used by the CORBA/Java-to-Tuxedo Simpapp sample application, you need to install Visual C++ version 6.0 with Service Pack 3 or later for Visual Studio. The m3idltojava compiler is installed by the WebLogic Enterprise software in the bin directory under TUXDIR.

Example Code

Listing 4-2 shows the joltNativeCall method from the SimpleImpl CORBA/Java server in the CORBA/Java-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 SimpleClient CORBA/Java client.

  Listing 4-2 The joltNativeCall() Method in the SimpleImpl CORBA/Java Server

  ---

    String joltNativeCall (String svcName, org.omg.CORBA.StringHolder data)
    {
      JoltService svc;
  
      try {
        svc = new JoltService (svcName);
        svc.addString("STRING", data.value);
        svc.call (null);
      } catch (ServiceException ee) {
        System.out.println("JoltService got " + ee);
        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, to_upper, in the SimpleImpl CORBA/Java server object.

 

---

Building and Running the CORBA/Java-to-Tuxedo Simpapp Sample Application

To build and run the CORBA/Java-to-Tuxedo Simpapp sample application, complete the following steps:

• 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

• Step 4: Run the CORBA/Java-to-Tuxedo Simpapp Sample Application

Step 1: Verify the Settings of Environment Variables

Before building and running the CORBA/Java-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 4-2 describes the environment variables that are required to run the CORBA/Java-to-Tuxedo Simpapp sample application.

Table 4-2 Required Environment Variables for the CORBA/Java-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 CORBA/Java-to-Tuxedo Simpapp sample application runme command. See the Administration Guide for more information about selecting appropriate values for these environment variables.

Table 4-3 describes the optional environment variables that you can set before running the CORBA/Java-to-Tuxedo Simpapp sample application.

Table 4-3 Optional Environment Variables for the CORBA/Java-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. The address 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 CORBA/Java-to-Tuxedo Simpapp sample application into a work directory on your local machine. The files for the CORBA/Java-to-Tuxedo Simpapp sample application are located in the following directories under TUXDIR:

Windows NT

$TUXDIR\samples\interop\corbaj_tux

UNIX

$TUXDIR/samples/interop/corbaj_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 corbaj_tux directory to the working directory created in the previous step:

   Windows NT

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

   UNIX

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

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

4. For UNIX, start a ksh.

5. Change the permissions on all the files to give them read-access.

6. Verify that the following command is in your search path:

   Windows NT

   nmake

   UNIX

   make

7. Execute the following command, which copies the remaining CORBA/Java-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 directories and files that were copied into your working directory when you executed the makefile.

Utility Files

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

Table 4-4 Utility Files in the Root of the Working Directory

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

CORBA/Java Client and Server Files

Table 4-5 describes the source files for the CORBA/Java client and server portions of this sample application. These files reside in the corbaj subdirectory of the working directory.

Table 4-5 CORBA/Java Client and Server Files in the corbaj Subdirectory

File	Description
SimpleClient.java	CORBA/Java client application.
Simple.idl	The OMG IDL that declares the SimpleFactory and Simple interfaces.
Simple.xml	The Server Description File for the Simple CORBA/Java server object.
SimpleFactoryImpl.Java	The implementation of the SimpleFactory methods.
SimpleImpl.Java	The implementation of the Simple methods. Illustrates the interoperability between the CORBA/Java server and the Tuxedo server by providing the bridge between them.
ServerImpl.Java	The implementation of the Server.initialize and Server.release methods.

Tuxedo Files

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

Table 4-6 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

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 CORBA/Java-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 CORBA/Java-to-Tuxedo Simpapp Sample Application

Once you have copied the files and changed their protection attributes, you can build and run the CORBA/Java-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 CORBA/Java Server application.

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 EJB-to-CORBA 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 CORBA/Java-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, which is located in the corbaj_tux working directory. You can check in the results 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 CORBA/Java client application output and exceptions.

Running the Sample Application Manually

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

To run the CORBA/Java-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, as follows:

   Windows NT

   prompt>tmboot -y
   prompt>java -DTOBJADDR=%TOBJADDR% -classpath %CLIENTCLASSPATH% SimpleClient

   UNIX

   prompt>tmboot -y
   prompt>java -DTOBJADDR=${TOBJADDR} -classpath ${CLIENTCLASSPATH} SimpleClient

3. The CORBA/Java-to-Tuxedo Simpapp sample application prompts you to 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 CORBA/Java client application output and exceptions.

Server Processes Started by the Sample Application

Table 4-7 describes the server processes that are started when the tmboot command is executed to start the CORBA/Java-to-Tuxedo Simpapp sample application.

Table 4-7 Server Processes Started When tmboot Is Executed

Process	Description
TMSYSEVT	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	JavaServer process that deploys the Simple CORBA/Java object (the deployment of this process also includes the SimpleFactory factory for the Simple object). The JavaServer takes one argument, Simple.jar, which is the module for the Simple CORBA/Java server object.
JREPSVR	Jolt Repository Server, which manages the Jolt Repository. The Jolt Repository contains service definitions for BEA Tuxedo services.
ISL	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 4-8 describes the file that is generated in the .adm subdirectory.

Table 4-8 File in the .adm Subdirectory

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

Files Generated in the corbaj Subdirectory

Table 4-9 describes the files that are generated in the corbaj subdirectory.

Table 4-9 Files Generated in the corbaj Subdirectory

File	Description
Simple.java	Generated by the m3idltojava command for the Simple interface. This interface contains the Java version of the IDL interface. It extends the org.omg.CORBA.Object class.
SimpleHelper.java	Generated by the m3idltojava command for the Simple interface. This class provides auxiliary functionality, notably the narrow method.
SimpleHolder.java	Generated by the m3idltojava command for the Simple interface. This class holds a public instance member of type Simple. It provides operations for out and inout arguments, which CORBA has, but which do not map easily to Java's semantics.
_SimpleImplBase.java	Generated by the m3idltojava command for the Simple interface. This abstract class is the server skeleton. It implements the Simple.java interface. The server class SimpleImpl extends _SimpleImplBase.
_SimpleStub.java	Generated by the m3idltojava command for the Simple interface. This class is the client stub. It implements the Simple.java interface.
SimpleFactory.java SimpleFactoryHelper.java SimpleFactoryHolder.java _SimpleFactoryImplBase.java _SimpleFactoryStub.java	Generated by the m3idltojava command for the SimpleFactory interface.
Simple.ser	The server descriptor file that is generated by the buildjavaserver command.
Simple.jar	The CORBA/Java server archive file that is generated by the buildjavaserver command.
SimpleClient.jar	The CORBA/Java client archive file that is generated by the make or nmake command.

Files Generated in the tux Subdirectory

Table 4-10 describes the files that are generated in the tux subdirectory.

Table 4-10 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 4-11 describes the files that are generated in the results subdirectory.

Table 4-11 Files Generated in the results Subdirectory

File	Description
input	Generated by the runme command. Contains the input that runme gives to the SimpleClient CORBA/Java application.
output	Generated by the runme command. Contains the output that is produced when runme executes the SimpleClient CORBA/Java application.
expected_output	Generated by the runme command. Contains the output that is expected when the SimpleClient CORBA/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 CORBA/Java-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.
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 the stderr file 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 CORBA/Java-to-Tuxedo Simpapp sample application.
ULOG.<date>	A log file that contains messages generated by the tmboot command. If there are any compile or run-time errors, check this file.

 

---

Stopping the CORBA/Java-to-Tuxedo Simpapp Sample Application

Before using another sample application, use the following procedure to stop the CORBA/Java-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