User docs
     Developer docs

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.


To run CorbaTrace, you must have :

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...)


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;


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);
where obj comes from :
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 OMG specification for more details).

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.


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");
where obj is an org.omg.CORBA.Object.

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");
where "myHelloPOA" is the name of the new POA, dynamically created, and rootPOA your own POA.

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 :


Before closing, destroy the server :


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");

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


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) :

Generate an UML sequence diagram

After the logs of your interceptions have been created, you can process them with our tool (Log2sequencediagram) to generate a UML sequence diagram in SVG, XMI or latex format.

This tool has four purposes :
  - parse your log files, and merge all partial-messages to get full messages
  - synchronize all local objects clocks to a common clock (as it's often distributed on different computers all over the world).
  - apply some filters of your own to get more relevant informations
  - generate a file that you can directly display with the tool GUI for a SVG file, on common UML tools such as MagicDraw and Rational Rose for an XMI file.

To launch the GUI of Log2sequencediagram, the command is :
ant gui

In this GUI, you can select the logs files you want to use to generate the UML sequence diagram, the filter file, the options of the generation,...

This GUI also provides some usefull tools like a light FTP client to get distant logs files, a easy filter creation GUI (see the part below to know what is a filter) and a SVG viewer to display the SVG sequence diagram.

Here is a presentation of this GUI :

I . The main window
II . The FTP Get window
III . The filter creation window
IV . The SVG Viewer window




The Main Window

Click on the GUI area on which you want informations.



Filter Log files Log Files Output file XMI Generation Tex generation SVGGeneration Show more infos Synchronization Validation

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.

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.

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

You can decide to not synchronize the objects' clock.

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


The FTP Get Window

Click on the GUI area on which you want informations.

FTP parameters Local folder Distant folder Get button 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.


The Filter Window

Click on the GUI area on which you want informations.

Log files Filter Output file Magic Draw extensions Show more infos

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.


The SVG Viewer

Click on the GUI area on which you want informations.

Tool Bar Display

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 are written in an xml file, as defined in the DTD (log.dtd)

It works at two levels :
  • globally
  • to object level
Globally, you can restrict messages to :
  • your given message types
  • 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).

For given objects, you can also restrict your messages more precisely to given message types, dates, and operations, with same principles as at globally level.

Each different filter (date - type - object - methods) works as an "AND" with others.
Each component of a filter (all dates for a date filter, all arguments for an method filter, etc.) works as an "OR" with others.

For example : (filters.xml)

<type value="BROKEN_REQUEST"/>
<type value="BROKEN_REPLY"/>
<type value="BROKEN_EXCEPTION"/>
<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"/>
<method name="anOperation1">
<argumentAt position="3" value="ddd"/>
<typedArgument type="string" value="ccc"/>
<method name="anOperation2">
<object id="anObjectID1">
<type value="BROKEN_REQUEST"/>
<type value="BROKEN_REPLY"/>
<type value="BROKEN_EXCEPTION"/>
<method name="anOperation">
<argumentAt position="1" value="aaa"/>
<argumentAt position="2" value="bbb"/>
<object id="anObjectID2">

This messages filters keeps messages that :
      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"

Of course, this is an example. Here, giving the messages types as broken for object "anObject1" is useless as it is already defined globally for the same type of messages.

Display the UML sequence diagrams

The file generated by the Log2sequencediagram tool can be of three types:

 - SVG
 - XMI
 - Latex

* SVG :

The CorbaTrace team recommend to use the SVG format. The main reason is that with this format you don't have to use a external UML tool like with the XMI format. And you have a much better graphical quality with the SVG format than with the Latex one.

To see a SVG file, you can use the SVG Viewer provided with the Log2sequencediagram GUI presented above. You can also a web browser with a specific plug-in.

* XMI :

The DTD of the XMI file generated is the uml13.dtd of the XMI standard, corresponding to version 1.3 of the UML metamodel. XMI is a standard format for storing and exchanging UML data. It is a quite new standard.

Many UML design tools already use this format, some as export format, some as saving format. Even if XMI was created to be an exchange format between UML design tools, every tool developped some proprietary extensions format. These extensions are added in most cases at the end of the XMI file, and hold all the graphic data for drawing the diagrams.

We decided to program the XMI extensions for 2 XML design tools: MagicDraw UML and Rational Rose. Nevertheless, maybe some other tools are (or will be) able to display diagrams without any other data as the standard XMI.

MagicDraw UML:

MagicDraw UML is the best tool for displaying XMI files, because its architecture is based on XMI.

It is not free, but you can download an evaluation version. This evaluation is only limited in the number of actors and classes when you save a file. That's not a problem here, because the file already exists and we only want to display it. To load our XMI file, only choose "File->Open project..." and select the xmi file.

You must have the uml13.dtd file in the same directory, while MagicDraw validates the XMI file. You can get this dtd file in ou download section.
When you open our XMI file with MagicDraw, you get an error message saying "wrong metamodel version". Don't matter. This is due to the fact that for having the compatibility with rational rose we had to set the metamodel version to 1.0 instead of 1.3, even if the effective DTD we use is the DTD of metamodel 1.3. You can change this in the XMI file if you want (see where my comment is).

Example :

The XMI file with MagicDraw extensions: click here to get it.

Screenshot: the tree

Screenshot: the diagram

Rational Rose :

To be able to import XMI files into rational rose, you first have to download a plugin. You can get it at this addess: http://www.rational.com/support/downloadcenter/addins/rose/ . This plugin only exists for the windows platform.

Once installed, you can import XMI files by choosing "File->Import UML XMI file". You must place your files in the "XML files" directory of the directory where you installed the plugin or copy the "dtd13.uml" file in the same directory as your XMI file.

If the creating wizard window opens, click "cancel", to continue import.
During the import, some errors occur: warning messages are displayed, click "No" each time (normally 2 times). That's because we use the 1.3 version of the UML metamodel and the Rose XMI plugin supports only version 1.0, so some tags are not understood.
After that, Rose says "the mdl file does not exist" (of course, it is creating it from the XMI file!). Don't matter again. Then you get the message "import complete", and you can see your Sequence Diagram.
You have an empty "data types" package, because the plugin can't import the data types. Don't care.

If you can, download MagicDraw UML and use this tool, it's much better with XMI!!!


The XMI file with Rational Rose extensions: click here to get it.

Screenshot: the tree

Screenshot: the diagram

Other UML Tool :

We need your help. Poseidon (and ArgoUML) are some free UML tools and they use XMI too. It would be not very difficult to create a new extension for CorbaTrace to generated good diagrams.
However, XMI can be enough to show lots of informations, without any extensions.


You can also use latex to display diagramm sequence. You must use the msc.sty package for sequence diagram. You can hace it in our tar/gz or on our website. To run it, you must generated the XMI file with Log2XMI. And after, you just use :
java corbaTrace.xmi2tex.Xmi2tex <XMIFile> <outputFile>

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

If you want more informations or help, you can see our report and presentation. Go to our develop docs section.