## Working with the Distributed Trace Sample

### 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.3.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.

### Compilation

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_1.1.0\hextrace.jar;+eclipse-unzip-directory+\plugins\org.eclipse.hyades.execution.correlation_1.1.0\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 org.eclipse.hyades.execution.trace.sample.Server

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

### Execution

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

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. Switch to the Java Perspective, choose the Run >> Run... >> Java Application >> Server configuration, and click the Run button to start the server. The following message should appear in the console window:

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

3. Choose Profile >> Attach >> Java Process, double-click the unknown[PID:XXXXX] to move it from the Agents part of the window to the Selected agents part. Click the Next button, modify any profiling options as necessary, and finally click the Finish button. Start monitoring the agent by right-clicking on the agent and choosing Start Monitoring from the context menu. Switch back to the Java Perspective, press Enter in the console, and the server should display:

           RMI-IIOP Sample Server ready...

4. Choose the Run >> Run... >> Java Application >> Client configuration, and click the Run button 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...

5. Choose Profile >> Attach >> Java Process, double-click the unknown[PID:XXXXX] to move it from the Agents part of the window to the Selected agents part. Click the Next button, modify any profiling options as necessary, and finally click the Finish button. Start monitoring the agent by right-clicking on the agent and choosing Start Monitoring from the context menu. Switch back to the Java Perspective, press Enter in the console, and the client should display:

           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, switch to the Profiling and Logging Perspective to view the data collected in the various 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.