readme

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:

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_3.0.0\hextrace.jar;<eclipse-unzip-directory>\plugins\org.eclipse.hyades.execution.correlation_3.0.0\hcorrelation.jar;.;%CLASSPATH%

Change to the bin directory under the rmi-iiop project: The default location of <workspace-directory> is <eclipse-unzip-directory>\workspace.
Generate the server stub and tie using the Java RMI compiler: The following class files will be generated in the bin\org\eclipse\hyades\execution\trace\samples 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

Start the name server on port 6502: The server output should look like:
In the workbench, switch to the Profiling and Logging perspective by selecting Window > Open Perspective > Profiling and Logging.
From the toolbar, select the Run icon, and select Run.
In the Run dialog, under Configurations, select Java Application > Server. You do not need to change the configuration settings.
Click the Run to start the server.

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

From the toolbar, select the Profile icon and select Server. The monitoring agent will be displayed in the Profiling Monitor view.
In the Console view, click Enter. The following line will display in the console:

Launching and profiling the client

From the toolbar, select the Run icon, and select Run.
In the Run dialog, under Configurations, select Java Application > Client. You do not need to change the configuration settings.
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...
```
From the toolbar, select the Profile icon and select Client. The monitoring agent will be displayed in the Profiling Monitor view.
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.