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:
-
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:
<![CDATA[
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%
]]>
-
Change to the
bin directory under the rmi-iiop project:
<![CDATA[
cd +workspace-directory+\rmi-iiop\bin
]]>
The default location of <workspace-directory> is <eclipse-unzip-directory>\workspace.
-
Generate the server stub and tie using the Java RMI compiler:
<![CDATA[
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:
-
Start the name server on port
6502:
<![CDATA[
tnameserv -ORBInitialPort 6502
]]>
The server output should look like:
<![CDATA[
Initial Naming Context:
IOR:000000000000002b49444c3a6f6d672e6f72672f436f734e616d696e672f4e616d696e67436f6e746578744578743a312e300000000000010000
000000000068000102000000000c392e32362e3135372e39320019660000000000164c4d4249000000157e262f360010000000040000000000000000
0002000000010000001800000000000100010000000100010020000101000000000049424d0a000000080000000014000001
TransientNameServer: setting port for initial object references to: 6502
Ready.
]]>
-
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:
<![CDATA[
Please attach to the server agent and press [Enter] to start profiling...
]]>
-
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:
<![CDATA[
RMI-IIOP Sample Server ready...
]]>
-
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:
<![CDATA[
Please attach to the client agent and press [Enter] to start profiling...
]]>
-
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:
<![CDATA[
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:
<![CDATA[
-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.