This tutorial is a hands-on introduction to JSeq. All sample code can be found in the samples directory.
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:
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.
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
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.* .
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.