Using the Java Code Smell Browser

Installing jCosmo

Cookbook-style instruction for installing from the online package base (or read the README and INSTALL files)

• untar the bundle file (tar -xvzf or gunzip and then tar -xvf)
• cd to the jcosmo-bundle-0.2 directory
• run "./collect.sh"
• run "./configure --prefix= < directory to install to > " e.g. "./configure --prefix=/home/youruserid/jcosmo"
• run "make"
• You should now have the directory you specified in the prefix argument of config, and inside it there should be three subdirectories called bin, libexec, and share, and inside bin, you should have two executable scripts called javatorsf and structrsf.

• tar -xvzf rigiforjcosmo.tar.gz
• bash: "export RIGI=~/rigi" tcsh: "setenv RIGI ~/rigi; rehash"
• bash: "export PATH=$PATH:~/rigi/bin" and in tcsh: "setenv PATH ${PATH}:~/rigi/bin"
• To run rigi: cd to ~/rigi/Rigi/db/java, copy the rsf file you want to look at to filename "rsf" and type "rigiedit" to start.

Installing Rigi: regular

• save our fixed version of rigiedit 5.5.0
• make a directory for Rigi ("mkdir rigi")
• move rigiedit-5.5.0-bin-ix86-linux2.tar.gz to the new directory
• untar the file ("tar -xvzf rigiedit-5.5.0-bin-ix86-linux2.tar.gz")
• set an environment variable called RIGI to the directory where you have installed Rigi (in bash: "export RIGI=~/rigi" tcsh: "setenv RIGI ~/rigi; rehash")
• add the rigi/bin directory to your path (in bash: "export PATH=$PATH:~/rigi/bin" and in tcsh: "setenv PATH ${PATH}:~/rigi/bin")

Configuring Rigi

Install the java domain:

• copy javadomain.tar into your ~/rigi/Rigi/domain directory
• type "tar -xvf javadomain.tar" to untar the file
• you will now have a new directory called "java" with inside it four files called "Rigiarc", "Rigiattr", "Rigicolor", and "Riginode"
• the next time you start up Rigi, you will have a new domain choice called "java"
• to set java as your default domain, change ~/rigi/rigicfg.env so that "RIGIDOMAIN =" reads "RIGIDOMAIN = java"

Install the jCosmo interface:

• copy jcosmo.rcl into your ~/rigi/Rigi/rcl directory
• modify ~/rigi/rigicfg.env so that the "RIGIURCL = " line now reads "RIGIURCL = ~/rigi/Rigi/rcl/jcosmo.rcl"
• when you start up Rigi, the jCosmo toolbar should pop up automatically

Remember that javatorsf either has to be in your path or you will have to provide a path for where it is such as "./javatorsf" for current directory, or "~/jcosmo/bin/javatorsf" if you installed it in a directory called jcosmo in your home directory. To add the above example to your path in Bash "export PATH=$PATH:~/jcosmo/bin".

To structure unstructured rsf produced by another tool, use the structrsf script. Run "structrsf < inputfile > -o < outputfile.rsf >" where the input file is unstructured rsf. Again, if you don't specify an output file the ouput goes to standard out.

extractor considerations

• You might have to increase the stack size limit ("limit stacksize < newlimit >" in tcsh).
• If you have any identifiers in your Java program that are called "NotFound" with exactly that mix of upper and lowercase letters, the program won't run properly. You will have to change those names (Perl script!) before you can run the extractor.
• If there are any identifiers with the same names as Java domain arc types, attribute types, or the word "type", then the FormatRsf procedure in cjava will format the rsf output file incorrectly. You can either change your names in your Java sources or change the format section in cjava (you could change it so that it introduces a newline every third word).
• Unicode characters will choke the parser and have to be removed or replaced.
• Up to and including Java 1.2 should be supported. If you have more modern Java, you might have to comment out some constructs that are not parsing properly.

Sample Java Rsf Files

Rigi Resources

See the Rigi Group Home Page for general information.

Download page There is now a version of Rigi for Windows available as Rigi550-Win-BETA. I quickly tested this with the jCosmo Java domain, jcosmo script and test files (see above) on a Windows 2000 system, and came up with two problems: node labels are not visible, although they are displayed at the bottom of the screen when clicked, and there is an error message on startup that you can get past by clicking the "details" option. Hopefully these problems will be fixed soon.

The version of Rigi that we use in jCosmo is Rigi 5.5.0 for Linux with an important bug fixed and an increased limit on the number of nodes you can lay out. See Installing Rigi to download this version.

Pdf version of the manual Also in ps. Html version is an older version.

Rigi page on the Program Transformation tWiki

Rigi Faq from above site.

Partial list of rcl commands is useful although not complete.

Another list of rcl commands

Description of Rsf file format

jCosmo user interface for Rigi

The simplest way to work is to make a new directory in your ~/rigi/Rigi/db directory and store your files there. Copy the file you want to work on to filename "rsf" and start rigiedit from that directory.

Overview of commands

Show All Smells(jcosmo_showallsmells) does some filtering and then shows the entire system with all the code smells in a spring layout. This view applied to curvedraw.rsf.

Show Smells by Class(jcosmo_showsmellsbyclass) does the same as the previous layout, but collapses the methods into their parent classes. Smell nodes are shown attached to their parent classes. To see the methods in the class, double-click on the class and this will open a window showing the methods and where the smell nodes actually are. Use this option for larger programs. This view applied to curvedraw.rsf. The Show Smells by Class Filter "Empty"(jcosmo_showsmellsbyclassnoempty) variant hides classes that don't contain any smells, for a cleaner view.

Show Casts by Gradient(jcosmo_showgradient {smell}) This view arranges all methods in a system along the x axis according to the number of the given smell they contain. Packages and classes are arranged above according to the average number of smells their methods contain. To view the parents and children for a given node, select that node and click Prune Tree(jcosmo_prunetree). This will show the contain tree for that node, with the node names. To return to the gradient view, click Unprune Tree(jcosmo_unprunetree). This returns to the gradient view without doing the layout over again. It is possible to change the layout parameters in the script in the deoverlap_all procedure. Gradient view of curvedraw.rsf
View after clicking the rightmost class node and pruning.
View after clicking a method and pruning.

At any time if you feel it will improve the view, you can run Hide Smell Labels, Show Smell Labels, Hide All Labels, and Show All Labels(jcosmo_hidesmelllabels etc.) which shows or hides labels. This just makes the view less cluttered, especially with Cast nodes, which have big labels. You can modify the script to call this procedure automatically in the other procedures.

Filter Cast Nodes(jcosmo_filtercast < direction (to or from) > < list of types >) This allows you to show only those Cast nodes that cast to or from the given types. For example, to see all casts from Object, choose "from" and type in "Object" and you will only see those casts. The rcl command would be "jcosmo_filtercast to Object" You can also fill in several types to filter on. To view all the casts again, just use "to all" or "from all". This feature allows you to find clusters of a particular typecast in your program.

jcosmo_showdepen taking either "Class" or "Package" as argument collapses all the program nodes into their parent class or package and shows the dependencies between them. Using something like this, you should be able to collapse your program into its component modules and check to see whether modules that shouldn't communicate with each other actually are. Use the class option for smaller programs and the package option for larger ones. "showdepen Class" applied to curvedraw.rsf.

More sample scripts (written for C files, but possibly adaptable to the Java domain):
Mozilla scripts (Mozilla rsf available here)
Linux kernel scripts

sdf specifications for Java and Java RSF

RSF describing the structure of the rsf files generated. The main difference between structured and unstructured rsf is that unstructured rsf must have a unique node name for each node. This means that if a method contains three switch statements, they have to be given three unique names such as 1!switch, 2!switch, and 3!switch, otherwise Rigi will collapse them into a single node. In the same way, methods have to contain the names of their parent classes in case there are two methods in different classes with the same name. In structured rsf, each node has a hidden unique node name that identifies it, so that the visible labels no longer have to be unique.