How to start the Java Measurement Tool application
The following steps are required to start the JMT application:
- Download the latest version from jmt.tigris.org
- Download the required configuration file (e.g. config.xml)
- Store both files in the same directory (e.g. jmt/)
- Switch to the directory and run the jar-arvice using:
java -jar jmt.jar [options..]
Once you have successfully downloaded and started the application you
can browse the analysed elements and the measurement results.
How to use the Java Measurement Tool application
The current version of the Java Measurement Tool application was designed
to demonstrate the basic functions of the JMT API. Therefore it was not designed
to be as handy as possible. Never the less it is quite usefull and the following text
will give you a short introduction. To ease the introduction a bunch of screenshots
will also demonstrate the functions of the JMT application. The screenshots were taken
from the JMT application analysing the JMT source code itself.
1. Specifying the code to analyse
Before the JMT application can analyse given code it must know where to find it.
Generally there are two basic kind of Java code - the source code and the compiled byte code.
The application itself can be started using
2. The startup phase
java -jar jmt.jar.
To analyse a given file, archive or directory just simply add the name
of the resource to the
In our example we want
to analyse the jmt.jar and the src.jar archives. The jmt.jar archive contains the
byte code of the JMT application and the src.jar contains the source code of JMT.
The src.jar archive can be downloaded at jmt.tigris.org.
So the call will be
java -jar jmt.jar src.jar jmt.jar.
Additionally the JMT application can also use list files. These files contain lists
of file names. Each line may only contain one file name. The name of a list file ends with '.lst' or '.list'.
List files are a great help to batch JMT application works on huge projects with many librarys included.
While analysing and measuring the JMT application prints out some usefull informations.
The application prints out a status message for each resource it has read and the time it took to
analyse it. And also there is a meassage for the measurement phase including the duration time as well.
In our example the application printed following text:
reading jmt.jar done in 1102 ms analysing 217 resources
reading src.jar done in 3294 ms analysing 188 resources
measuring done in 1953 ms
If an error or an exception occured during reading, analysation or measurement the
the application will also print a message.
The meassage will describe the reason why the analysation attempt failed
and what resource caused the problem.
3. The main application window
After the application successfully read, analysed and measured the given resources
the main window pops up and shows the analysed elements and the measurement results.
Picture 3.1 shows the application window like it would be in our example.
Picture 3.1 - The application window
The window displays four tabbed panels each presenting a special group of code elements and
their associated measurement results.
The selected panel in the screenshot is the package view presenting all packages of the analysed code.
There are also panels for the classes, methods and fields (attributes) elements. Picture 3.2 shows the classes-view
of thirteen classes. This classes-view was created by selecting various classes and open a new window
only presenting the selected classes. To open a new window based on the current selection you may hit the
ENTER key or perform a double click with any mouse button.
Picture 3.2 - The classes view
Picture 3.3 shows the methods view of the application and the tooltip of the second method name.
This illustrates that a tooltip of an element's name is able to show the whole
name even if the table entry of the name is not fully visible.
4. The icons
Picture 3.3 - The methods view
While watching the pictures you might have noticed the type column and the
diffrent icons it is containing. Picture 4.1 gives you an idea how the diffrent icons
are composed. If you are not sure what a type icon describes, just read the tooltip
by placing the mouse cursor over the icon.
The tooltip will show up and display the aquivalent Java type definition. If the color of the dot
is blue the type icon indicates that the access type of the element is default.
Default means package-scope and is the access type Java picks automatically (by default)
if you do not specify any access modifier keywords within the type definition. In this case the tooltip
will display the pseudo keyword 'default'.
Picture 4.1 - The basics of the type icon
Another kind of icon is the quality icon. The quality icon is used by the 'Quality' column and visualises the overall quality
using three stars. The quality is measured in percent ranging from 0% to 100%. Picture 4.2 shows the icons and their associated
percentage value range.
5. How the application is used effectivly
Picture 4.2 - The basics of the type icon
Knowing the basics we can now start to think about using the application effectivly.
The application presents the analysed elements and the measured values. Each
measurement method is presented by its own column. A column of a measurement method
is only visible within a table if the measurement done by the method resulted in at least one presentable result.
- Lets take a look at our example. The package view is visible and the table is sorted by the 'Quality' column in
ascending order. You can sort the 'Quality' column by simply clicking on it's header with the mouse.
Picture 5.1 shows the packages sorted by their overall quality value.
Picture 5.1 - Package view sorted by overall quality
Now we know that the package 'jmt.application.measurement.classes' is rated worst because
it had the fewest stars visible and it is also located at the top of the sorted table. But why? -
Looking at the numbers does not help much to explain the reason.
After hitting the SPACE key once we see the quality rating of all measurement results
expressed by qualtiy icons. Picture 5.2 shows the package view after hitting the SPACE
Picture 5.2 - Package view after hitting the SPACE key.
You can switch back to numbers by hitting the SPACE key again. But let us take some time to discuss what we see.
The low overall quality rating of the package 'jmt.application.measurement.classes'
is caused by the poor rating of the NPEC measurement method result. So we have to think about the aspects
the NPEC method measures. - So what is the NPEC method all about? - Well the tooltip of the column's head tells us that
NPEC stands for 'Number of Public Extendable Classes' and it measures the number of public
classes which are extendable by any class even if the class is placed outside the package.
Picture 5.3 shows the tooltip of the NPEC method.
Picture 5.3 - The tooltip of the NPEC measurement method.
But why is the number 10 such a bad result? What does it mean having public extendable classes inside a package? -
To answer these questions we have to think about a programmer extending a public class.
If the class is extendable he might would create a new subclass by extending th class. This is not a bad thing in general,
but consider the programmer as a programmer using a package such as 'java.util'. The Java class HashMap implements a Map
using a hash algorithm to store and find an added object. The HashMap class is public and it is extendable. So why may it not good
to have an extandable classes here? -
Well a programmer can create a subclass of the default implementation of a hash map. Being able to do so
the people developing the next version of the java.util package have to ensure that
the new version still contains a HashMap implementation that has the same public
methods, the same protected methods (cause subclasses are able to call them directly) and the same constructors.
The constructors of the new version must also share the same basic 'initialisation' flavour. Luckily all declared methods
and fields of the HashMap class are private or default - well beside implemented methods declared by the interfaces.
So everytime you are declaring a extendable public class you will limit the creativity of the developers of the next
version of the package.
This seams not to be a big deal for the HashMap but think about the Stack and Vector implementations.
They feel like the JDK 1.0 versions. If you have to design such stack implementation today you won't design it
that way for sure. Or just think about the Calendar implementation... . But knowing the traps does not
mean avoiding them automatically. As you will see the JMT API has still design problems too. And mostly
you have to use a limited design to have more flexiblity.
Let us take a look on the classes of the package 'jmt.application.measurement.classes'. Therefore
a new window should be opened by double-clicking on the package table entry.
Picture 5.4 shows the window displaying the 'jmt.application.measurement.classes'.
Picture 5.4 - The classes of the package 'jmt.application.measurement.classes'.
As you can see there are ten public classes in the package marked by the green type icon.
So now we know which are our ten 'trouble makers'. All ten classes implement diffrent measurement methods.
And all ten classes are public and extendable. But why do we need public classes? And why should they be extandable?
Well this classes should be public because they are instanciated using the
6. Source code vs. compiled code
While placing a factory-class in the package and using a factory method instead of Class.forName(...) it would still
be possible to plug-in measurement methods. But every package containing a measurement method would require a factory
class too. Maybe we change that later on to hide the measurement methods from other packages.
This will avoid unauthorised extending of the shipped methods and will give us the freedom
to change the concret measurement method implementations and their names when ever we want to. And we do not have to waste
thoughts about how extended classes may react on that changes - which is nearly impossible to predict.
Most implementations will be modified or rewritten during a projects lifetime.
Because of performance problems or design illnesses the earlier versions tend to change a lot.
And it is the worst thing for a programmer seeing a new version of the library still
using worster class and interface design then nessecary.
Especially if it is just caused by compatibility requirements.
Another thing we can do is to add a final keyword to the class definitions.
This won't hide our measurement mehtods but it will forbid subclassing.
Also it will still frezze the measurement classes on their public level.
But in this case the resulting effect is only to force 3rd-party programmer
to use warper or adapter classes to be able to extend our measurement
methods. But never the less this would be an advantage too.
I think both ideas will make it into the next versions of the JMT API.
But what allready changed is a problem you can still see in the screenshots.
The package 'jmt.codebase.bytecode' containes five public classes. One of them
is the AbstractConstantPoolEntry.ExtractCaches inner class. The inner class
does a very importent job for analysing byte-sources. But never the less this
inner class must be hidden. In the current version the inner class became a private one.
Source code and compiled code basicly share the same informations about
the code structure. But there are also some diffrences. Some measurement methods can only
measure either source code or compiled code. Currently the 'Lines of Code' method
requires source code. If the application only analysed a compiled code version
of the element the 'Lines of Code' method will not be able to calculate a
measurement result. Therefore the element will not have a 'Lines of Code'
presentable measurement result. The 'Coupling Between Objects' and the 'Response of a Class'
measurement methods will require a analysed compiled code version of the element.
7. Tips'n tricks
Also the compiled code can be analysed three times faster then the source code.
This results from the used JavaCC parser.
The following tips, tricks and hints might be usefull:
- Start the application by java -jar jmt.jar toAnalyse1 toAnalyse2... .
- To batch thinks create batch files and also consider to use list files. (see 1.)
- Every table entry has a tooltip providing usefull informations.
- You can change the sorting of any column by clicking on it's head.
- Use the ENTER key or double-click with any mouse button (right one is preferred) to open a new window only
containing the selected elements
- The new window's size and position is set to cover the actuall JMT window.
- Use the SPACE key to switch between showing stars or showing numbers.
- Some measurement methods requires a special kind of code such as source code or compiled code.