Tutorial

This tutorial is a hands-on introduction to JSeq. All sample code can be found in the samples directory.

Using JSeq with JUnit

The first step in our tutorial is to generate some diagrams based on JUnit test cases.

To do this, first set the environment variable JSEQ_HOME to the directory where you installed JSeq. Then run Ant on the build.xml file in the samples directory. This should compile the code and run JSeq.

The result should be an ArgoUML file called scenarios.zargo in the samples directory. Open it with ArgoUML. It contains a number of collaborations, one for each thread in every scenario, and one for setting up the JUnit tests.

Please compare the sequence diagrams to the source code. You will notice some peculiarities:

• The method names are not in the right place. Click on one of the method names to correct this.
• Calls back to the same object are not visibile as arrows; only the method name is shown. This seems to be a problem with ArgoUML 0.12, one that I will try to fix.

To create SVG diagrams, update build.xml : change the jseq.format to svg and the jseq.outfile to some appropriate file, then run Ant again.

Using JSeq Stand-Alone

The next step in this tutorial is to experiment with different command-line options.

First of all, set up your classpath so that you can run the class files in the directory samples/build/classes . Verify by giving the command

java simple.Foo

You should see no output; in particular, you should not see a ClassNotFoundException .

Now give the command

jseq -save simple.sav -quiet simple.Foo

This runs simple.Foo , saving a trace of the run in the file simple.sav , without generating any sequence diagram.

Now generate a textual representation of the previous run:

jseq -read simple.sav -format text

This will produce a list of all top-level activations (method calls) in the program run. In this case, there is only one top-level activation, the call to simple.Foo.main . Nested activations are shown indented.

Now for something more interesting: let's run JSeq on itself!

jseq -save metasimple.sav -quiet th.co.edge.jseq.Main -read simple.sav -format text

This runs JSeq's main class, th.co.edge.jseq.Main , saving the program trace in the file metasimple.sav . No sequence diagram is generated. Please be patient — on my machine, this JSeq run takes more than three minutes.

Now, if we look at the textual representation of the run:

jseq -read metasimple.sav -format text

we see that there are too many activations to produce any useful sequence diagram. Sure, JSeq can produce a diagram for this, but no human will want to look at it!

To produce something useful from this mass of information, we can do two things: select appropriate starting points for our diagram; and cut away unnessesary information.

If you take a look at the textual dump of all activations, you see that the method th.co.edge.jseq.Formatter$TextFormatter.format is called near the end. Let's say that we are interested in generating a sequence diagram for just this part of the program:

jseq -read metasimple.sav -start th.co.edge.jseq.Formatter$TextFormatter.format \
    -format svg -out metasimple.svg

This creates an SVG diagram, starting from the given method call. If you open the diagram using some SVG viewer, you see that the diagram is still quite large.

The next thing we can do to reduce the diagram size is to cut away method calls that we are not interested in:

jseq -read metasimple.sav -start th.co.edge.jseq.Formatter$TextFormatter.format \
    -exclude *.getClassName -exclude *.getMethodName -format svg -out metasimple.svg

This produces a diagram without any calls to getClassName and getMethodName .

The -exclude flag can also be used to prune complete packages. For example, if you don't want to see any log4j calls, you would use -exclude org.apache.log4j.* .

Speeding Up JSeq Execution

As you saw when you ran JSeq on itself in the previous section, JSeq can take a long time to run. If we know beforehand which part of the program trace we are interested in, we can use the -start and -exclude flags to speed up program execution.

In the previous section, we generated a complete program trace, saved it to a file, and later pruned the sequence diagram. Of course, this does not make JSeq run faster. However, if we generate the program trace for only the part we are interested, it will run faster:

jseq -start th.co.edge.jseq.Formatter$TextFormatter.format \
    -exclude *.getClassName -exclude *.getMethodName -format svg -out metasimple2.svg \
    th.co.edge.jseq.Main -read simple.sav -format text

On my machine, this runs more than six times faster than generating the complete program trace.