Developing Java Joint Client/Server Applications

 

This topic includes the following sections:

• Development Process

• Software Requirements

• The Callback Sample Application

• Step 1: Writing the OMG IDL

• Step 2: Generating Skeletons and Client Stubs

• Step 3: Writing the Methods That Implement Each Interface's Operations

• Step 4: Initializing the ORB

• Step 5: Writing the Client Portion of the Joint Client/Server Application

• Step 6: Creating a Callback Object Using the Callbacks Wrapper Object

• Step 7: Establishing a Connection to an ISH

• Step 8: Invoking Operations on the Callback Object

• Step 9: Specifying Configuration Information

• Step 10: Compiling Java Joint Client/Server Applications

• Threading Considerations for Java Joint Client/Server Applications

• Building and Running the Callback Sample Application

• Using the Callback Sample Application

 

---

Development Process

Table 3-1 outlines the development process for Java joint client/server applications.

Table 3-1 Development Process for Java Joint Client/Server Applications

Step	Description
1	Write the OMG IDL for the callback interface and the CORBA interfaces you want to use in your BEA WebLogic Enterprise application.
2	Generate the skeletons and client stubs.
3	Write the methods that implement each interface's operations.
4	Initialize the ORB.
5	Write the client main portion of the joint client/server application.
6	Create a callback object using the Callbacks Wrapper object.
7	Establish communication with an ISH.
8	Invoke operations on the BEA WebLogic Enterprise object by passing an object reference for the callback object.
9	Specify configuration information.
10	Compile the joint client/server application.

These steps are explained in detail in subsequent topics.

Because the callback object in a joint client/server application is not transactional and has no object management capabilities, you do not need to create a Server Description File (filename.xml) for it. However, you still need to create a Server Description File for the BEA WebLogic Enterprise objects in your BEA WebLogic Enterprise application. For information about writing a Server Description File, see Creating CORBA Java Server Applications.

 

---

Software Requirements

You need the Java JDK version 1.2.1 to create Java joint client/server applications.

 

---

The Callback Sample Application

Throughout this topic, the Callback sample application is used to demonstrate the development steps. The callback object in the joint client/server application has a print_converted method, which accepts a string from the Simple object in the BEA WebLogic Enterprise server application and prints the string in uppercase and lowercase letters.

Figure 3-1 illustrates how the Callback sample application works.

Figure 3-1 How the Callback Sample Application Works

The source files for the Callback sample application are located in the WLEdir\samples\corba\callback_java directory of the BEA WebLogic Enterprise software. See "Building and Running the Callback Sample Application"" for more information.

 

---

Step 1: Writing the OMG IDL

You use OMG IDL to describe available CORBA interfaces to client applications. An interface definition written in OMG IDL completely defines the CORBA interface and fully specifies each operation's arguments. OMG IDL is a purely declarative language. This means that it contains no implementation details. For more information about OMG IDL, see Creating CORBA Client Applications.

The Callback sample application implements the CORBA interfaces listed in Table 3-2.

Table 3-2 CORBA Interfaces for the Callback Sample Application

Interface	Description	Operation
Callback	Accepts a string from the Simple object in the BEA WebLogic Enterprise server application and prints the string in uppercase and lowercase letters	print_converted()
Simple	Calls the Callback object in the joint client/server application	Calls the Callback object in the joint client/server application
SimpleFactory	Creates object references to the Simple object	find_simple()

Listing 3-1 shows the simple.idl file that defines the Callback, Simple, and SimpleFactory interfaces in the Callback sample application.

Listing 3-1 OMG IDL for the Callback Sample Application

---

#pragma prefix "beasys.com"

interface Callback

//This method prints the passed data in uppercase and lowercase
//letters.

{
	void print_converted(in string message);
};

interface Simple

//Call the callback object in the joint client/server application

{
              void call_callback(in string val, in Callback 		
                                callback_ref);
};

interface SimpleFactory
{
     Simple find_simple();
};

---

 

---

Step 2: Generating Skeletons and Client Stubs

The interface specification defined in OMG IDL is used by the IDL compiler to generate skeletons and client stubs. Note that a joint client/server application uses the client stub for the BEA WebLogic Enterprise objects and the skeleton and client stub for the callback object.

For example, in the Callback sample application, the joint client/server application uses the skeleton and the client stub for the Callback object to implement the object. The joint client/server application also uses the client stubs for for the Simple and SimpleFactory to invoke operations on the objects. The BEA WebLogic Enterprise server application uses the skeletons for the Simple and SimpleFactory objects to implement the objects and the client stub for the Callback object to invoke operations on the object.

During the development process, you use the following compilers to build client stubs and skeletons.

• You use the idltojava command supplied with the JDK version 1.2.1 to compile the OMG IDL file and generate client stubs and skeletons to be used by the joint client/server application.

• You use the m3idltojava command to compile the OMG IDL file and generate client stubs and skeletons to be used by the BEA WebLogic Enterprise server application.

The names of the files generated by the idltojava and m3idltojava commands are the same; however, the content is different. When developing a BEA WebLogic Enterprise application that contains a joint client/server application, it is recommended that you create two separate directories for each set of client stubs and skeletons. For the Callback sample application, the files generated by the idltojava command are located in the client directory and the files generated by the m3idltojava command are located in the server directory.

Table 3-3 lists the files that are generated by the idltojava and the m3idltojava commands.

Table 3-3 Files Created by the idltojava and m3idltojava Commands

File	Description
Callback.java	The Java version of the Callback OMG IDL interface. It extends org.omg.CORBA.Object.
CallbackHelper.java	The Java class that provides auxiliary functionality, notably the narrow method.
CallbackHolder.java	The Java class that provides operations for out and inout arguments that are included in CORBA, but that do not map exactly to Java.
_CallbackStub.java	The client stub that implements the Callback.java interface.
_CallbackImplBase.java	The skeleton that implements the Callback.java interface. The class CallbackImpl extends _CallbackImplBase.
Simple.java	The Java version of the Simple OMG IDL interface. It extends org.omg.CORBA.Object.
SimpleHelper.java	The Java class that provides auxiliary functionality, notably the narrow method.
SimpleHolder.java	The Java class that provides operations for out and inout arguments that CORBA has but that do not match exactly to Java.
_SimpleStub.java	The client stub that implements the Simple.java interface.
_SimpleImplBase.java	The skeleton that implements the Simple.java interface. The class SimpleImpl extends _SimpleImplBase.
SimpleFactory.java	The Java version of the SimpleFactory OMG IDL interface. It extends org.omg.CORBA.Object.
SimpleFactoryHelper.java	The Java class that provides auxiliary functionality, notably the narrow method.
SimpleFactoryHolder.java	The Java class that provides operations for out and inout arguments that are included in CORBA, but that do not map exactly to Java.
_SimpleFactoryImplBase.java	The skeleton that implements the SimpleFactory.java interface. The class SimpleFactoryImpl extends _SimpleFactoryImplBase.
_SimpleFactoryStub.java	The client stub that implements the SimpleFactory.java interface.

The skeleton class that is created by the idltojava command does not inherit from the TP Framework com.beasys.Tobj_Servant class. Instead, the skeleton class inherits directly from the org.omg.CORBA.DynamicImplementation class. Inheriting from com.beasys.Tobj_Servant means the joint client/server application must explicitly create a servant for the callback object and initialize the servant's state. The servant for the callback object cannot use the activate_object and deactivate_object methods as they are members of the com.beasys.Tobj_Servant class.

 

---

Step 3: Writing the Methods That Implement Each Interface's Operations

After you compile the OMG IDL, you need to write methods that implement the operations of each object. In a joint client/server application, you write the implementation file for the callback object. You write the implementation file for a callback object as you would write the implementation file for any other CORBA object. You also write the implementation file for the BEA WebLogic Enterprise object in your BEA WebLogic Enterprise application.

An implementation file consists of the following:

• Method declarations for each operation specified in the OMG IDL file

• Your application's business logic

• Constructors for each interface implementation (optional)

Listing 3-2 includes the implementation file for the Callback object.

Listing 3-2 Implementation File for the Callback Object

---

//The implementation file for the Callback object. The Callback
//object implements the print_converted method.

class CallbackImpl extends _CallbackImplBase {

//Prints a string in upper and lower case

       public void print_converted(String data) {
          if (data == null)
              System.out.println("Null String");
	else
       {
              //Print input data in uppercase 
              System.out.println(data.toUpperCase());

              //Print input data in lowercase
              System.out.println(data.toLowerCase());
       }
   }
}

---

Listing 3-3 includes the implementation file for the Simple object.

Listing 3-3 Implementation File for the Simple Object

---

import com.beasys.Tobj.TP;

//The implementation file for the Simple interface. The Simple 
//interface implements the call_callback method of the Callback //object.

public class SimpleImpl extends _SimpleImplBase
{
       public void call_callback(String data, Callback 
                                 callback_ref)

//Call the print_converted method on the reference to the Callback
//object 
       {
         callback_ref.print_converted(data);
         return;
       }
}

---

Listing 3-4 includes the implementation file for the SimpleFactory object.

Listing 3-4 Implementation File for the SimpleFactory Object

---

import com.beasys.Tobj.TP;

//The implementation file for the SimpleFactory object. The
//SimpleFactory object provides methods to create a Simple object.


public class SimpleFactoryImpl extends _SimpleFactoryImplBase
{

//Create an object reference to a Simple object.

       public Simple find_simple()
         {
              try {
                    org.omg.CORBA.Object simple_oref =
                         TP.create_object_reference(
                            SimpleHelper.id(),  // Repository id
                            "simple_callback",  // object id
                             null                // routing criteria
                            );

       // Send back the narrowed reference.

                   return SimpleHelper.narrow(simple_oref);

           } catch (Exception e){
              TP.userlog("Cannot create Simple: " +e.getMessage());
             e.printStackTrace();
             return null;
           }
    }
}

---

 

---

Step 4: Initializing the ORB

In previous versions of the BEA WebLogic Enterprise product, Java client applications used the JDK ORB without modifications. Versions 4.2 and later of the BEA WebLogic Enterprise product provide a value-added implementation of the JDK ORB. The modifications to the JDK ORB include classes and methods that support callback objects. The classes and methods for the callback objects are in the wleclient.jar file located in the following directories:

Window NT

%wledir%\udataobj\java\jdk

UNIX

$wledir/udataobj/java/jdk

To use this modified JDK ORB, Java joint client/server applications must set certain properties. Listing 3-5 contains the command to initialize the JDK ORB with the correct properties. For more information about the properties used to initialize the JDK ORB, see the CORBA Java Programming Reference.

Listing 3-5 Initializing the ORB in the Callback Sample Application

---

properties prop = new Properties(System.getProperties());
prop.put("org.omg.CORBA.ORBclass", 
    "com.beasys.CORBA.iiop.ORB");
prop.put("org.omg.CORBA.ORBSingletonclass", 
    "com.beasys.CORBA.idl.ORBSingleton");
System.setProperties(prop);

//Initialize the ORB

ORB orb = ORB.init(args, prop);

 

---

Step 5: Writing the Client Portion of the Joint Client/Server Application

During development of a joint client/server application, you write the client portion of the joint client/server application as you would write any BEA WebLogic Enterprise client application. The client application needs to include code that does the following:

1. Uses the Bootstrap object to establish communication with the BEA WebLogic Enterprise domain.

2. Resolves initial references to the FactoryFinder object.

3. Uses a factory to get an object reference for the desired BEA WebLogic Enterprise object.

The client development steps are illustrated in Listing 3-6, which includes code from the Callback sample application. In the Callback sample application, the client portion of the joint client/server application uses a factory to get an object reference to the Simple object.

Listing 3-6 The Client Portion of the Callback Sample Application

---

//Create a Bootstrap object
       Tobj_Bootstrap bootstrap = new Tobj_Bootstrap(orb,"");

//Create the Bootstrap object. The TOBJADDR system property 
//defines the host and port.

Tobj_Bootstrap bootstrap = new Tobj_Bootstrap(orb, "");

//Use the Bootstrap object to find the FactoryFinder object.

org.omg.CORBA.Object fact_finder_oref =
       bootstrap.resolve_initial_references("FactoryFinder");

//Narrow the FactoryFinder object.

FactoryFinder fact_finder_oref =
	FactoryFinderHelper.narrow(fact_finder_oref);

//Use the FactoryFinder object to locate a factory for the
//Simple object.

org.omg.CORBA.Object simple_fact_oref =
     fact_finder_oref.find_one_factory_by_id
     (SimpleFactoryHelper.id());

//Narrow the factory.

SimpleFactory simple_factory_oref =
     SimpleFactoryHelper.narrow(simple_fact_oref);

//Find the Simple object.

Simple simple = simple_factory_oref.find_simple();

---

 

---

Step 6: Creating a Callback Object Using the Callbacks Wrapper Object

To allow the use of outbound IIOP in Java joint client/server applications, the JDK ORB has been extended to implement certain POA functionality. The POA functionality is implemented through the Callbacks Wrapper object.

The Callbacks Wrapper object does the following:

• Defines the object policy for the callback object. The following object policies are supported:

  • Transient/SystemID (_transient)

  • Persistent/SystemID (_persistent/systemid)

  • Persistent/UserID (_persistent/userid)

    For a complete description of the object policies for callback objects, see "Object Policies for Callback Objects".

• Creates a servant for the callback object.

• Sets the ORB to the state in which it will accept requests on the callback object.

• Returns an object reference to the activated callback object. The object Id can be generated by the system or supplied by the user.

• Tells the ORB to stop accepting requests on either a single servant or all the active servants.

For a complete description of the Callbacks Wrapper object, see the CORBA Java Programming Reference.

Listing 3-7 shows how the Callbacks object is used in the Callback sample application.

Listing 3-7 Using the Callbacks Wrapper Object in the Callback Sample Application

---

import java.io.*;
import java.util.Properties;
import org.omg.CORBA.*;
import org.omg.CORBA.portable.ObjectImpl;
import com.beasys.*;
import com.beasys.Tobj.*;
import com.beasys.BEAWrapper.Callbacks;
...
//Create the servant for the Callback object

CallbackImpl callback_ref = new CallbackImpl();

//Use the Callbacks Wrapper object to create the callback object

Callbacks callbacks = new Callbacks(orb);

//Activate the servant and allow the ORB to accept
//callback requests.

callbacks.start_persistent_userid(callback_ref,
       ((ObjectImpl)callback_ref)._ids() [0],
        "myID");
...

---

 

---

Step 7: Establishing a Connection to an ISH

To support IIOP more efficiently in Java joint client/server applications, the Bootstrap object supports a register_callback_port method. This method registers the callback object in a joint client/server application with the listening port of an ISH, causing invocations to the callback object to be routed through the specified ISH.

In this situation, the joint client/server application is using dual-pair connection IIOP. A joint client/server application that does not perform this registration will force server applications that invoke the callback object in the joint client/server application to use asymmetric IIOP, which uses the ORB infrastructure to locate an available ISH.

Note: The callback object must be activated before the register_callback_port method is called.

Listing 3-8 shows how the register_callback_port method is used in the Callback sample application.

Listing 3-8 The register_callback_port Method in the Callback Sample Application

---

...
//Register the callback port are specified in org.omg.CORBA.ORBport

bootstrap.register_callback_port(callback_ref);
...

---

 

---

Step 8: Invoking Operations on the Callback Object

Once you have an object reference to a callback object, you pass the callback object reference as a parameter to a method of a BEA WebLogic Enterprise object. In the Callback sample application, the Simple object (the BEA WebLogic Enterprise object) uses an object reference to the Callback object as a parameter to the call_callback method. Listing 3-9 illustrates this step.

Listing 3-9 Invoking the call_callback Method

---

...
//Call the call_callback method which invokes the Callback object

simple.call_callback(mixed, callback_ref);
...

---

 

---

Step 9: Specifying Configuration Information

When using joint client/server applications, the object references for the callback object must contain a host and port number, as follows:

• For transient callback objects, any port is sufficient and can be obtained dynamically by the ORB.

• For persistent callback objects, the ORB must be configured to accept requests for the callback object on the same port on which the object reference for the callback object was created.

The ORB is configured by setting the org.omg.CORBA.ORBPort system property. Every time you run the joint client/server application, you must enter the following commands to set the org.omg.CORBA.ORBPort system property:

Window NT

java -DTOBJADDR=//Host:Port
-Dorg.omg.CORBA.ORBport=portnumber
-classpath=%CLASSPATH% JointClientServerApplication

UNIX

java -DTOBJADDR=//Host:Port
-Dorg.omg.CORBA.ORBport=portnumber
-classpath=$CLASSPATH JointClientServerApplication

The administrator assigns the port number for the joint client/server application from the user range of port numbers, rather than from the dynamic range. Assigning port numbers from the user range prevents joint client/server applications from using conflicting ports.

For Java joint client/server applications, the administrator needs to boot the IIOP Server Listener (ISL) with startup parameters that enable outbound IIOP to invoke callback objects not connected to an IIOP Server Handler (ISH). The -O option of the ISL command enables outbound IIOP. The ISL parameter is defined in the configuration file. Additional parameters allow administrators to obtain the optimum configuration for their BEA WebLogic Enterprise application. For more information about the ISL command, see the Commands, System Processes, and MIB Reference.

Note: The Callback sample application does not demonstrate using asymmetric IIOP. Therefore, the -O option is not used in the configuration file.

 

---

Step 10: Compiling Java Joint Client/Server Applications

When creating joint client/server applications, use the javac command provided with the JDK 1.2.1 to construct an executable for the joint client/server application. The command compiles the java source code of the joint client/server application.

When compiling joint client/server applications, you need to include the following Java ARchive (JAR) files in your CLASSPATH:

• The m3envobj.jar file, which contains Java versions of the BEA WebLogic Enterprise environmental objects

  Note: The m3envobj.jar file is in this directory: wledir\udataobj\java\jdk.

• The wleclient.jar file, which contains the classes and methods for the Callbacks Wrapper object

For the syntax of the javac command, see the CORBA Java Programming Reference.

You use the buildjavaserver command to build the BEA WebLogic Enterprise server application that invokes the callback object. For information about compiling server applications, see Getting Started and Creating CORBA Java Server Applications.

 

---

Threading Considerations for Java Joint Client/Server Applications

Note: The Callback sample application does not use multiple threads.

Since Java as an execution environment is multithreaded, there is no need to implement the ORB org.omg.CORBA.orb.work_pending and org.omg.CORBA.orb.perform_work methods. These methods throw a NO_IMPLEMENT exception when a user tries to invoke them. In addition, the org.omg.CORBA.orb.run method does not need to be called. Be aware that any code that executes concurrently must be written to be thread-safe.

When using multiple threads in Java, the client functionality of the joint client/server application starts up in the main thread. The joint client/server application then activates the callback object using one of the start methods of the Callbacks Wrapper object. The Callbacks Wrapper object registers the servant for the callback object, and its associated object ID, in the ORB's object manager. The joint client/server application is then free to pass the object reference for the callback object to any application that may need to invoke the callback object.

Note: The BEA version of the JDK ORB requires an explicit call to one of the start methods of the Callbacks Wrapper object to initialize the servant for the callback object and create a valid object ID. This requirement differs from the base JDK ORB, which allows implicit creation of object references through the orb.connect method when marshaling an object reference when an application has not already done so.

Invocations on the callback object are handled by the ORB. As each request is received, the ORB validates the request against the object manager and spawns a thread for that request. Multiple requests can be made simultaneously to the same callback object, since the ORB creates a new thread for each request.

As each request terminates, the thread that runs the servant for the callback object terminates. The main thread that controls the client functionality of the joint client/server application can make as many client invocations as it needs. There is no restriction to prevent other servants defined in the joint client/server application to act as client applications and invoke on BEA WebLogic Enterprise objects. A call to stop_all_objects() merely takes the callback object out of the object manager's list, thus preventing any further invocations on the callback object. Any invocation to a stopped callback object fails as if it never existed.

If the client functionality of a joint client/server application needs to retrieve the results of a callback from another thread, the client functionality must use normal thread synchronization techniques.

If any thread in the joint client/server application invokes an exit method, all activity is stopped and the Java execution environment terminates. It is recommended to only call return() to terminate a thread.

 

---

Building and Running the Callback Sample Application

To build and run the Callback sample application:

1. Copy the files for the Callback sample application into a work directory.

2. Change the protection attribute on the files for the Callback sample application.

3. Verify the environment variables.

4. Execute the runme command.

The following sections describe these steps.

Copying the Files for the Callback Sample Application into a Work Directory

You need to copy the files for the Callback sample application into a work directory on your local machine. The files for the Callback sample application are located in the following directories:

Windows NT

drive:\WLEdir\samples\corba\callback_java

UNIX

/usr/local/WLEdir/samples/corba/callback_java

You will use the files listed in Table 3-4 to build and run the Callback sample application.

Table 3-4 Files Included in the Callback Sample Application

File	Description
Simple.idl	The OMG IDL code that declares the Callback, Simple, and SimpleFactory interfaces.This file is copied from the sample application directory by the runme command file.
ServerImpl.java	The Java source code that implements the Server.initialize and Server.release methods.
SimpleJCS.java	The Java source code for the joint client/server application in the Callback sample application.
SimpleFactoryImpl.java	The Java source code that implements the methods of the SimpleFactory object .
SimpleImpl.java	The Java source code that implements the methods of the Simple object.
CallbackImpl.java	The Java source code that implements the methods of the Callback object.
Simple.xml	The Server Description File used to associate activation and transaction policy values with CORBA interfaces. For the Callback sample application, the Simple and SimpleFactory interfaces have an activation policy of method and a transaction policy of never.
Readme.txt	The file that provides the latest information about building and running the Callback sample application.
runme.cmd	The Windows NT batch file that builds and runs the Callback sample application.
runme.ksh	The UNIX Korn shell script that builds and executes the Callback sample application.
makefile.mk	The UNIX Korn make file for the Callback sample application. This file is used to manually build the Callback sample application. Refer to the Readme.txt file for information about manually building the Callback sample application. The UNIX make command needs to be in the path of your machine.
makefile.nt	The Windows NT make file for the Callback sample application. This make file can be used directly by the Visual C++ nmake command. This file is used to manually build the Callback sample application. Refer to the Readme.txt file for information about manually building the Callback sample application. The Windows NT nmake command needs to be in the path of your machine.
smakefile.nt	The make file that is used with the Visual Cafe smake command for the Callback sample application. Note: makefile.nt is included by smakefile.nt.

Note: When running the Callback sample application on the UNIX operating system, you need to make sure the makefile is in the path of your machine.

Changing the Protection Attribute on the Files for the Callback Sample Application

During the installation of the BEA WebLogic Enterprise software, the sample application files are marked read-only. Before you can edit or build the files in the Callback sample application, you need to change the protection attribute of the files you copied into your work directory, as follows:

Windows NT

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

UNIX

prompt>/bin/ksh

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

On the UNIX operating system platform, 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

Verifying the Settings of the Environment Variables

Before building and running the Callback 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 they reflect correct information.

Table 3-5 lists the environment variables required to run the Callback sample application.

Table 3-5 Required Environment Variables for the Callback Sample Application

Environment Variable	Description
TUXDIR	The directory path where you installed the BEA 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 UNIX JAVA_HOME=/usr/local/JDK1.2

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

ksh prompt>printenv TUXDIR

ksh prompt>printenv JAVA_HOME

To change the settings, perform the following steps:

Windows NT

1. 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.

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

3. Click OK to save the changes.

UNIX

ksh prompt>export TUXDIR=directorypath

ksh prompt>export JAVA_HOME=directorypath

Table 3-6 lists additional environment variables that may be set prior to running the Callback sample application.

Table 3-6 Optional Environment Variables for the Callback 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 the ORB. 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 is 2468.
IPCKEY	The address of shared memory; it must be a number greater than 32769 unique to this application on this system. The default value is 55532.
CALLBACK_PORT	The TCP port number at which the client application process listens for incoming callback requests; it must be a number between 0 and 65535. The default value is 2458.

Executing the runme Command

The runme command automates the following steps:

1. Setting the system environment variables

2. Loading the UBBCONFIG file

3. Compiling the code for the client application

4. Compiling the code for the server application

5. Starting the server application using the tmboot command

6. Starting the client application

7. Stopping the server application using the tmshutdown command

   Note: You can also run the Callback sample application manually. The steps for manually running the Callback sample application are described in the Readme.txt file.

To build and run the Callback sample application, enter the runme command, as follows:

Windows NT

prompt>cd workdirectory

prompt>runme

UNIX

ksh prompt>cd workdirectory

ksh prompt>./runme.ksh

The Callback sample application runs and prints the following messages:

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

Note: After executing the runme command, you may get a message indicating that the Host, Port, and IPCKEY parameters in the UBBCONFIG file conflict with an existing UBBCONFIG file. If this occurs, you need to set these parameters to different values to get the Callback sample application running on your machine.

The runme command starts the following application processes:

• TMSYSEVT

  The BEA TUXEDO system event broker.

• TMFFNAME

  The following three TMFFNAME server processes are started:

  • The TMFFNAME server process started with the -N and -M options is the Master NameManager service. The NameManager service maintains a mapping of the application-supplied names to object references.

  • The TMFFNAME server process started with only the -N option is the Slave NameManager service.

  • The TMFFNAME server process started with the -F option contains the FactoryFinder object.

• JavaServer

  The server application server process that implements the SimpleFactory and Simple interfaces. The JavaServer process has one option, simple.jar, which is the Java ARchive (JAR) file that was created for the application.

• ISL

  The IIOP Listener server process.

Table 3-7 lists the files in the work directory generated by the runme command.

Table 3-7 Files Generated by the runme Command

File	Description
SimpleFactory.java, SimpleFactoryHolder.java, SimpleFactoryHelper.java, _SimpleFactoryStub.java, _SimpleFactoryImplBase.java, Simple.java SimpleHolder.java, SimpleHelper.java, _SimpleStub.java, _SimpleImplBase.java, Callback.java, CallbackHolder.java CallbackHelper.java _CallbackStub.java _CallbackImplBase.java	Client stubs, skeletons, and Java Helper and Holder classes for the SimpleFactory, Simple, and Callback interfaces. For a description of the files, see Table 3-3.
Simple.ser	The Server Descriptor File.
Simple.jar	The server JAR file.
SimpleJCS.jar	The JAR file for the joint client/server application.
.adm/.keybd	A file that contains the security encryption key database.
results	A generated directory.

Table 3-8 lists files in the results directory generated by the runme command.

Table 3-8 Files in the results Directory Generated by the runme Command

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

 

---

Using the Callback Sample Application

This section describes how to use the Callback sample application after the runme command is executed.

Run the joint client/server application in the Callback sample application, as follows:

Windows NT

prompt>tmboot -y
prompt>java -classpath %CLIENTCLASSPATH% -DTOBJADDR=%TOBJADDR
-Dorg.omg.CORBA.ORBPort=%CALLBACK_PORT% SimpleJCS
String?
Hello World
HELLO WORLD
hello world

UNIX

ksh prompt>tmboot
ksh prompt>java -classpath $CLIENTCLASSPATH -DTOBJADDR=$TOBJADDR
-Dorg.omg.CORBA.ORBPort=$CALLBACK_PORT SimpleJCS
String?
Hello World
HELLO WORLD
hello world

Before using another sample application, enter the following commands to stop the Callback sample application and to remove unnecessary files from the work directory:

Windows NT

prompt>tmshutdown -y

prompt>nmake -f makefile.nt clean

UNIX

ksh prompt>tmshutdown -y

ksh prompt>make -f makefile.mk clean