Login | Register
My pages Projects Community openCollabNet

How to start the Java Measurement Tool application

The following steps are required to start the JMT application:

  1. Download the latest version from jmt.tigris.org
  2. Download the required configuration file (e.g. config.xml)
  3. Store both files in the same directory (e.g. jmt/)
  4. 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 java -jar jmt.jar. To analyse a given file, archive or directory just simply add the name of the resource to the java call.
  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.


2. The startup phase

  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.

Picture 3.3 - The methods view


4. The icons

  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.

Picture 4.2 - The basics of the type icon


5. How the application is used effectivly

  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 key once.

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 Class.forName(...) methode. 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.


6. Source code vs. compiled code

  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.
  Also the compiled code can be analysed three times faster then the source code. This results from the used JavaCC parser.


7. Tips'n tricks

  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.