## Working with the Distributed Trace Sample

This sample contains the following information:

- Overview
- Requirements
- Compiling the sample
- Running the sample
- Customization
- Termination
- Limitations

### Overview

This example illustrates a distributed end-to-end trace of a simple Remote Method Invocation (RMI) - Internet Inter-ORB Protocol (IIOP) program. The example consists of three parts: an interface (`IService`), a server (`Server`), and a client (`Client`). The function of the interface is twofold: to inform a client of what services to expect, and to inform a server of what services are to be implemented. In this example, the server provides "hello" and "add" services.

### Requirements

A Java Software Development Kit (SDK) is required which:

- supports Portable Object Adapter (POA);
- contains a Java RMI compiler (`rmic`) capable of generating POA stubs and ties (generally found in the `<sdk-root-directory>\bin` directory);
- has the Transient Name Server (`tnameserv`) (generally found in the `<sdk-root-directory>\jre\bin` directory);

Generally, a SDK v1.4.1 or above is sufficient but different vendors meet these requirements at different SDK levels. Also, a Java Runtime Environment (JRE) may not be sufficient as it does not generally contain a Java RMI compiler.

### Compiling the sample

After the example code is imported into the workspace, the client and server code should be compiled automatically. However, the server stub and tie must be generated manually using the Java RMI compiler, following these steps:

1. Open a console window, and ensure that `hextrace.jar`, `hcorrelation.jar`, and the current directory are all on the current classpath. For example, on Windows platforms:

           set CLASSPATH=<eclipse-unzip-directory>\plugins\org.eclipse.hyades.execution.trace\hextrace.jar;<eclipse-unzip-directory>\plugins\org.eclipse.hyades.execution.correlation\hcorrelation.jar;.;%CLASSPATH%

2. Change to the `bin` directory under the `rmi-iiop` project:

       cd <workspace-directory>\rmi-iiop\bin

   The default location of `<workspace-directory>` is `<eclipse-unzip-directory>\workspace`.
3. Generate the server stub and tie using the Java RMI compiler:

       rmic -iiop -poa Server

   The following class files will be generated in the `bin` directory:

       _IService_Stub.class
       _Server_Tie.class

If an error occurs during the compilation, ensure that the classpath has been set correctly.

### Running the sample

The server and client can be launched and profiled using the following steps:

#### Launching and profiling the server

1. Start the name server on port `6502`:

           tnameserv -ORBInitialPort 6502

   The server output should look like:

       Initial Naming Context:
       IOR:000000000000002b49444c3a6f6d672e6f72672f436f734e616d696e672f4e616d696e67436f6e746578744578743a312e300000000000010000
       000000000068000102000000000c392e32362e3135372e39320019660000000000164c4d4249000000157e262f360010000000040000000000000000
       0002000000010000001800000000000100010000000100010020000101000000000049424d0a000000080000000014000001
       TransientNameServer: setting port for initial object references to: 6502
       Ready.

2. In the workbench, switch to the Profiling and Logging perspective by selecting Window > Open Perspective > Profiling and Logging.
3. From the toolbar, select the Run icon, and select Run.
4. In the Run dialog, under Configurations, select Java Application > Server. You do not need to change the configuration settings.
5. Click the Run to start the server.
The following text will display in the console:

        Please attach to the server agent and press [Enter] to start profiling...

6. From the toolbar, select the Profile icon and select Profile.
7. In the Profile configuration dialog, select Java Application > Server. The profiling details are displayed in the right pane.
8. In the server profiling configuration, under the Profiling tab, select the Overview tab.
9. Click Add to add your own profiling set. The Add Profiling Set dialog window opens.
10. Specify a name and a description for your profiling set. Click OK. A new profiling set is created in the Profiling set list.
11. Select the newly created profiling set and click Edit. The Edit Profiling Set dialog opens.
To specify the information you want collected, select the relevant check boxes. To view graphical details of the program execution, select Time Analysis > Execution Time Analysis. On the details page of the Execution Time Analysis option, select Show execution flow graphical details. (For more details see the topic Profiling sets and available views under the References section of the Profiling Tool book.) Click Next.
12. On the Edit Filters page, under the Contents of selected filter set, click Add to add packages that you want to collect data for. For this example, add `*` as the package name and `*` as the class name.
13. Click Finish.
14. Click Profile.
15. The monitoring agent will be displayed in the Profiling Monitor view.
16. In the Console view, click Enter. The following line will display in the console:

            RMI-IIOP Sample Server ready...

#### Launching and profiling the client

1. From the toolbar, select the Run icon, and select Run.
2. In the Run dialog, under Configurations, select Java Application > Client. You do not need to change the configuration settings.
3. Click the Run to start the client. The following message should appear in the console window:

           Please attach to the client agent and press [Enter] to start profiling...

4. From the toolbar, select the Profile icon and select Profile.
5. In the Profile configuration dialog, select Java Application > Client. The profiling details are displayed in the right pane.
6. In the server profiling configuration, under the Profiling tab, select the Overview tab.
7. Select the profiling set created for the Server. The same profiling filters will be applied to the client.
8. Click Profile.
9. The monitoring agent will be displayed in the Profiling Monitor view.
10. In the Console view, click Enter. The following text will display in the console:

            Greetings from the server: Hello <client-hostname>!

            Addition: 5 + 17 = 22

    where `<client-hostname>` is the hostname of the machine on which the client code was running.

Once the client has finished execution, view the data collected using the various profiling views.

### Customization

The ORB bootstrap port number can be changed to any valid port number when the name server is started. However, this requires the modification to the VM argument:

        -Djava.naming.provider.url=iiop://localhost:<port-number>

where `<port-number>` is the customized port number used in the `-ORBInitialPort` option.

### Termination

The client terminates after a single invocation, and therefore does not require a manual termination. In contrast, the server must be terminated explicitly. To do this, switch to the Debug Perspective, right-click on the Server [Java Application] process, and choose Terminate from the context menu.

### Limitations

Due to the limited amount of request information offered in the `org.omg.PortableInterceptor.ServerRequestInfo` interface, and the need to keep the framework sufficiently generic, the class and instance data about the server tie cannot be determined. Therefore, the class of the tie is assumed to be `javax.rmi.CORBA.Tie`. For similar reasons, the method signatures during the IIOP transport are not available. Consequently, any relevant profiling data is most likely incorrect.

(C) Copyright IBM Corporation 2000, 2004. All Rights Reserved.