Tool: Jepends-BCEL
Purpose: Jepends-BCEL is a tool I have built to collects the metrics described here, from the bytecode of a Java program. I have made the tool is available for download as sources and as binaries. You will need Java 5 to compile and run it.

How to use it: You can run Jepends-BCEL from the command line as follows:

>>java -cp path/to/jepends-bcel.jar;path/to/bcel-5.1.jar melton.hayden.jepends.bytecode.JependsCmdLine [inputDir] [outputDir] [listOfPkgPrefixes]

[inputDir] is the directory containing the jar files to process
[outputDir] is the directory to write the meta data
[listOfPkgPrefixes] is a list of Java package names to include. If not specified all packages are included. Usually you only want to include the packages containing an application's source-declared classes. See the examples below for more information.... 


Here are some examples (the "..." is where you invoke the Java VM and tell it where the Jepends-BCEL jar is, and allocate the VM any extra memory if necessary):

... JependsCmdLine c:\ant\bin c:\jepends-data\ant org.apache.ant.
The above line would run Jepends-BCEL on Apache Ant, assuming the jar files comprising Ant were located in c:\ant\bin or any of its subdirectories. It would then write the metrics data out to subdirectories in the directory c:\jepends-data\ant. Any class files contained in the Ant jars that did not belong to the package org.apache.ant would be ignored.

... JependsCmdLine c:\jdk\bin c:\jepends-data\jdk java. sun. javax.
The above line would run Jepends-BCEL on the JDK, assuming the jar files comprising the JDK were located in c:\jdk\bin or any of its subdirectories. It would then write the metrics data out to subdirectories in the directory c:\jepends-data\jdk. Any class files contained in the JDK jars that did not belong to the one of the packages java, sun, javax, would be ignored.

... JependsCmdLine c:\jepends\bin c:\jepends-data\jepends melton.hayden.
The above line would run Jepends-BCEL on itself, assuming the jar files comprising the JDK were located in c:\jepends\bin or any of its subdirectories. It would then write the metrics data out to subdirectories in the directory c:\jepends-data\jepends. Any class files contained in the Jepends-BCEL jars that did not belong to the package melton.hayden would be ignored.  


You will know when Jepends-BCEL is running because it will spit stuff out to stdout as it runs. Here is a sample of what got spat out when I ran it on ArgoUML-0.20:

processing jar:C:\ArgoUML-0.20\gef.jar
processing jar:C:\ArgoUML-0.20\antlrall.jar
processing jar:C:\ArgoUML-0.20\jmiutils.jar
processing jar:C:\ArgoUML-0.20\mof.jar
processing jar:C:\ArgoUML-0.20\argouml-model.jar
    parsing: org.argouml.model.StateDiagram
    parsing: org.argouml.model.CoreFactory
    parsing: org.argouml.model.UndoCoreHelperDecorator$ObjectSetter
    parsing: org.argouml.model.AbstractDataTypesHelperDecorator
    parsing: org.argouml.model.mdr.XmiReferenceResolverImpl
processing jar:C:\ArgoUML-0.20\commons-logging.jar
processing jar:C:\ArgoUML-0.20\nbmdr.jar
cull supers

Once you have run Jepends-BCEL three subdirectories will appear in the output directory (specified through the [outputDir] parameter). For the ArgoUML example above I specified C:\ArgoUML-0.20\metrics as the output directory. The three subdirectories created were _Jepends-BCEL, _Jepends-BCEL-merged and _Jepends-BCEL-summaries. If you are just interested in collecting the CRSS and SCC metrics for your project you can pretty much ignore all of the files except _Jepends-BCEL-summaries\_all.txt. All of the other files are for other things I have done, and am currently doing, as part of my PhD research.

If you open [outputDir]\_Jepends-BCEL-summaries\_all.txt you will see something like this (again, taken from ArgoUML):

class crss fanout fanin scc
org.argouml.ui.explorer.rules.GoProjectToCollaboration 1201 6 1 724
org.argouml.uml.cognitive.critics.CrTooManyStates 1201 5 1 724
org.argouml.uml.diagram.ui.FigSingleLineText 1201 1 3 724
org.argouml.persistence.XMLTokenTableBase 1 0 2 1 1203 9 0 1
org.argouml.uml.ui.behavior.state_machines.UMLStateVertexOutgoingListModel 71 3 1 1

Basically the above file is a tab-delimited summary of metrics for all the classes in the application. I strongly suggest you load it into MS Excel (or other tool) to get a nicer view of it (see below).


The "crss" column shows the Class Reachability Set Size value for the class, the "fanout" column shows the number of other source files the class depends on, "fanin" shows the number of source files that depend on this class and "scc" shows the size of the Strongly Connected Component the class participates in. (We can see in the above screen dump that ArgoUML has a strongly connected component of size 724!)

To draw a histogram like that shown below (again, taken from ArgoUML-0.20) you have to pass the crss column into Excel's FREQUENCY function. It is a bit of a hassle because it's an "array function" so you have to do some weird keystrokes to make it work (ctrl+shft+enter on the PC). Anyway, there is a good guide here on using Excel to draw a histogram. I have produced a histogram of ArgoUML-0.20 below:


Troubleshooting: The most common problem is the Java VM running out of memory when running the Jepends-BCEL over a large application (like Eclipse). To remedy this problem specify an extra parameter to the Java VM "-Xmx700M" --- this will allocate the VM 700 megs of memory.

Another problem is having spaces in the arguments (e.g. spaces in the [inputDir] directory name). If you have a space in the directory name Java will treat the space as an argument separator. The simplest solution is not to use spaces in directory names, or escape the spaces by surrounding the argument in quotes (I think this only works for Windows, but there is a way to do it in Unix too).

Home Research Corpus Software Papers Other