User documentation

We tried to minimize the modifications required in your project to integrate CorbaTrace. We only use OMG methods to install it.
This file may not be perfectly synchronized with the last source files. See in CVS the file INSTALL and the API JavaDoc for the newest instructions.

Requirements

To run CorbaTrace, you must have :

• a Java Runtime Environnement
• a standard ORB (Corba 2.3 or up), for example Orbacus
• the JDK1.4 or an older version with the JAXP package

To be able to see the generated sequence diagrams in XMI or Tex, you must have:

• a UML tool that supports the XMI standard
or
• latex, with the msc.sty package (see our download section to get it) to transform the XMI files to tex files (and then PS, PDF...)

Compatibility

It should work properly on other systems, as we use only standards like Java and XML, but only made a few tests. If you have some compatibility troubles, please mail us.

See below for the tested configurations:

• JDK
  • Sun JDK 1.3.1
  • Sun JDK 1.4
• ORB
  • Orbacus 1.4.0
  • Orbacus 1.3.4
• OS
  • Linux (Debian 2.2, Mandrake 8.0)
  • Windows 2000

One of our futur work is to be compliant with the GNU project. So we will try to be compliant with GCC 3.0 and classpath, and with a free ORB. All should be possible and not so hard because we only use standards.

Integrate CorbaTrace in your project

You have an example of a Server and one of a Client in ./src/java/corbatrace/hello.

Just include the CorbaTrace.jar in your CLASSPATH.

set CLASSPATH=$CLASSPATH:mypath/CorbaTrace.jar

In the sources, add at the beginning :

import corbaTrace.Interceptor;

Client

In your sources, before the creation of the orb, initialize the interceptor by creating an instance of the InterceptorClient.
After initialization of the ORB, but before making remote calls, add :

obj = interceptorClient.active_interception(obj, orb);

org.omg.CORBA.Object obj = orb.string_to_object(myIOR);

You can get your own object by using the standard function :

Hello hello = HelloHelper.narrow(obj);

Once all objects are created, add :

interceptorClient.activate_log(orb, "My Name");

"My Name" is used to identify your component. All client objects on the same ORB are seen as a same component.

If you want to change the logging policy, call :

interceptorClient.change_level_interception(obj, orb, int);

See below for an example :

	import corbatrace.InterceptorClient;
	...
	class MyClass {
		...
		interceptorClient = new InterceptorClient();
		...
		ORB orb = ORB.init(args, props);
		...
		obj = orb.string_to_object(ref);
		obj = interceptorClient.active_interception(obj, orb);
		interceptorClient.activate_log(orb, "My Component");
		...
		Hello hello = HelloHelper.narrow(obj);
		...
	}

You can download all the code of this example of Client on our CVS: Click here.

Server

In your sources, before the creation of the orb, initialize the interceptor by creating an instance of the InterceptorServer.

After the initialization of the orb, call a method to resolve the references of the RootPOA :

obj = orb.resolve_initial_references("RootPOA");

Get your own rootPOA by using the standard :

POA rootPOA = org.omg.PortableServer.POAHelper.narrow(obj);

Then create the POA which calls the method "create_poa" of the class InterceptorServer :

poa_interceptor = interceptorServer.create_poa(orb, rootPOA, "myHelloPOA");

Activate the object on this POA :

obj = interceptorServer.activate_object(poa, helloImpl, "My Component");

This method records and activates the object of the POA that has just been created. This POA will enable client applications to have access on it.
This method activates also the POAManager that controls the way the POA is managing the requests of the different clients.

Get your own object by using the standard :

Hello hello = HelloHelper.narrow(obj);

Write your object "hello" to a file (or register your object on the CosNaming service) :

writeObjectToFile(orb, hello, filename);

The server waits for the requests of the clients and answers by calling the appropriate methods :

orb.run();

Before closing, destroy the server :

orb.destroy();

See below for an example :

	import corbaTrace.InterceptorServer;
	...
	class MyClass {
		...
		interceptorServer= new InterceptorServer();
		...
		ORB orb = org.omg.CORBA.ORB.init(args,props);
		obj = orb.resolve_initial_references("RootPOA");
		POA rootPOA = org.omg.PortableServer.POAHelper.narrow(obj);
		poa_interceptor = interceptorServer.create_poa(orb, rootPOA, "myHelloPOA");
		...
		obj = interceptorServer.activate_object(poa, helloImpl,"My Component");
	        Hello hello = HelloHelper.narrow(obj);
                writeObjectToFile(orb, hello, "My File");
		...
		orb.run();
		orb.destroy();
	}
        

You can download all the code of this example of Server on our CVS:

• Server.java
• Hello.idl
• Hello_impl.java

Result

Compile your project and run it.
Some log files are generated ( *_Ctrace.xml for clients and *_Strace.xml for server objects).
They are easy to understand.

You can convert them to XMI and use some filters (see below).

When you execute our example, you obtain the two screenshots beelow :

• Server
  
  

• Client
  
  

After interception, two logs are generated (files linked) :

• Log Server
  
• Log Client
  

Generate an UML sequence diagram

Click on the GUI area on which you want informations.

Project browser:
You can browse your project folders and add some xml log files and filter files to the logs list and filter list with the corresponding buttons.

Log files:
You can remove some xml log files, generated by CorbaTrace. They contain the messages exchanged by the objects of your CORBA application.

Filter:
You can remove the xml filter file that will be applied on the log files by Log2SequenceDiagram. You can filter informations as object name, message date, method name and parameters.
To learn more about filter, see the filter window part of this help file.

Output file:
You can specify the name of the XMI, TEX and/or SVG output file.

XMI Generation:
You can select to output the sequence diagram as a XMI file. You can add to this file the specific Rational Rose and/or Magic Draw extensions.

TEX Generation:
You can select to output the sequence diagram as a TEX file.

SVG Generation:
You can select to output the sequence diagram as a SVG file. This is the option the CorbaTrace team recommend you, see you can visualize this file with the SVG Viewer provided with CorbaTrace.

Validation:
You can decide to not validate the XML log files with the log DTD.

Synchronization:
You can decide to not synchronize the objects' clock.

Show more infos:
This option shows more informations on screen during the Log2Xmi process.

Click on the GUI area on which you want informations.

FTP parameters:
You have to fill these fields with the FTP hostname and port number, and if the FTP host needs it your FTP username and password, before connecting to the FTP server.

Local folder:
This is a small browser of your local folder. The directories are written inside [ ].

Distant folder:
This is a small browser of your distant folder on the FTP server. The directories are written inside [ ].

Get button:
A click on this button will download the selected file in the distant folder into your local folder.

Get button:
Here are the logs of all the FTP actions.

Click on the GUI area on which you want informations.

Object:
You can select here on which level you want the filter to operate :

• At a global level (on all the objects), by selecting 'Global'
• On a specific object, by selecting this object's name

The combo box is populated with the objects which are in the log files added in the Main window.

The filter parameters:
You can filter the data on :

• Message types
  
• Dates
  
• Methods
  

By clicking on the Add button, you add this parameter on the selected Object (see Object).
You can learn more on filters by reading the CorbaTrace documentation.

The filter display:
This is the display of the filter you are creating.

The 'Save' button:
When you have finished your filter, you can save it as a file by clicking on this button.

The 'Save and add' button:
As for the 'Save' button, you can save your filter in a file by clicking ths button. And the filter is added in the Main window.

Click on the GUI area on which you want informations.

The tool bar:
3 buttons with which you can open a SVG file, zoom in the content of this file and zoom out the content of this file.

The display:
This is the area where the content fo the SVG file is displayed. Some key+mouse combination provide functionnality is the display area:
- SHIFT + left click : move the picture
- SHIFT + right click : manual zoom
- CTRL + left click : zoom in a select area
- CTRL + right click : picture rotation

Filters

• globally
• to object level

• your given message types
  types are : REQUEST, REPLY, EXCEPTION, BROKEN_REQUEST, BROKEN_REPLY, and BROKEN_EXCEPTION.
• your given dates (or intervalls)
  There is three types of date filters : after a date, before a date, or between two dates.
  Dates uses the same format as logs : year-month-dayThours-minutes-seconds-milliseconds (by ex: 2002-03-09T17:00:00.000)
• your given operations, independently of objects.
  For each operation you give its name, and can restrict it more precisely with its operation arguments' values.
  Defined arguments are of two types :
  
  • a datatype and a value
  • an argument position in this operation (from 1 to n) and a value
• your given objects with their ID (objects' name).

<filter>
	<message_types>
		<type value="BROKEN_REQUEST"/>
		<type value="BROKEN_REPLY"/>
		<type value="BROKEN_EXCEPTION"/>
	</message_types>
	<dates>
		<after date="2002-03-09T17:00:00.000"/>
		<before date="2002-03-09T15:00:00.000"/>
		<between from="2002-03-09T15:30:00.000" to="2002-03-09T16:30:00.000"/>
	</dates>
	<methods>
		<method name="anOperation1">
			<argumentAt position="3" value="ddd"/>
			<typedArgument type="string" value="ccc"/>
		</method>
		<method name="anOperation2">
		</method>
	</methods>
	<objects>
		<object id="anObjectID1">
			<message_types>
				<type value="BROKEN_REQUEST"/>
				<type value="BROKEN_REPLY"/>
				<type value="BROKEN_EXCEPTION"/>
			</message_types>
			<methods>
				<method name="anOperation">
					<argumentAt position="1" value="aaa"/>
					<argumentAt position="2" value="bbb"/>
				</method>
			</methods>
		</object>
		<object id="anObjectID2">
		</object>
	</objects>
</filter>

      are of type broken (any of them)
  AND are after 17H (the 2002/3/9)
          OR before 15H
          OR between 15H30 and 16H30
  AND are of operation named "anOperation1" 
             with (an argument at position 3 equals to "ddd"
                   OR an argument of type string equals to "ccc")
          OR operation named "anOperation2"
  AND concerns object "anObject1"
               with messageType of type broken
                    AND concerning operation "anOperation"
                                   with an argument at position 1 equals to "aaa"
                                        OR an argument at position 2 equals to "bbb"
     OR concerns object "anObjectID2"

Display the UML sequence diagrams

java corbaTrace.xmi2tex.Xmi2tex <XMIFile> <outputFile>

java corbaTrace.xmi2tex.Xmi2tex xmi_file.xml latex_generated.tex