Getting Started

with the command line interface

jMetra uses two classes with supporting command line interfaces, JMetraMaker and JMetraDoc. The first class is used to actually collect the metrics from the code and store results into XML files (step 1. from How It Works). It is also used to compile different metrics (XML) files across time, into one collection of XML files that represents metrics through time for each class (step 2. from How It Works). The second class, JMetraDoc, takes collections of metrics that are compiles through time and produces HTML-based documentation for analyzing the metrics (step 3 from How It Works).

Each command line interface class displays explanations for options by using the -help option, such as

\bin> java com.jmetra.JMetraMaker -help

Command Line Interface for Collecting Metrics

Let's start with collecting metrics for a simple project called proj. All proj source code is located at one source root, D:\proj\src\java. We would like to collect metrics for proj and put them into a directory D:\proj\metrics. This would be done as follows,

\bin> java com.jmetra.JMetraMaker -rootsource D:\proj\src java D:\proj\metrics

First, the option -rootsource identifies where is the root of the project source code (D:\proj\src) and what is the keyword for identifying source roots (java). The reason this option doesn't simply take one argument D:\proj\src\java, is because the two argument format allows handling of large projects that might have multiple source roots and different levels as long as they consistently use the same source root keyword. For example, a project might have two source roots, one for the application and one for testing. The might result into two directories, D:\proj\src\app\java and D:\proj\src\testing\java. It would process both trees of code because they had the keyword java for their respective java source directories.

The only non-option agrument is simply the output directory for the generated XML metrics files.

By default, jMetra will use a timestamp based label for the file that is produced. Alternative timestamp formatting and also explicit label naming is supported via the JMetraMaker options. Additionally, there are options for supporting JSP metrics collection.

Command Line Interface for Aggregating Metrics across Time

Let's assume that using the directions above, we have collected metrics for proj across a period of time, say a month of project development. So, we have a collection of metrics XML files located in D:\proj\metrics for each time we collected metrics over the month (by running the command line discussed above). We can produce the aggregate xml files for proj by simply using JMetraMaker with the aggregation option, -aggr, and identify where the metrics are located. This would be done as follows,

\bin> java com.jmetra.JMetraMaker -aggr D:\proj\metrics D\proj\metrics\aggrbuilds

First, the -aggr option denotes aggregation is being performed. The other arguments that are required for aggregation are the directory where all the individual metrics files are located (D:\proj\metrics) and the directory that the aggregate directories/files for the aggregated XML metrics files should be place (D:\proj\metrics\aggrbuilds).

Note that typically a jMetra user would be aggregating metrics any time he/she would be interested in producing jMetraDocs, so this step would be done frequently. Note that jMetra is smart enough that it will not redundantly aggregate metrics it has already added to aggregate metrics files. It internally looks to see if there is a matching label for metrics of a given class and only adds the metrics if an identical label does not exist in the file. You can minimize the time it takes for jMetra to aggregate a new build by using the -recent <days> option so it will just attemp to aggregate recent metrics files.

Usage Note: Many projects using jMetra in a corporate environment often store the metrics aggregations on a shared, networked drive. Since the aggregation process is file-write intensive, aggregating new metrics files can take a substantially longer time. We have observed that performance for aggregating can take up to 10 times longer when writing to some networked drives. For this reason, we recommend that you put your metrics and aggregation files on a drive that is local to the platform where jMetra is executing. Users may still wish to write to a networked drive but should consider that aggregation performance is particularly sensative to drive access.

Command Line Interface for Generating jMetra Documents

The final step in using jMetra is to generate friendly HTML documentation pages from the aggregate metrics XML files. Note that the documentation generator is a different interface class, JMetraDoc. For our project, proj, we pass two arguments. First, the location of the aggregate metrics (D:\proj\metrics\aggrbuilds). Second, the desired location of the generated documentation files (D:\proj\doc). The following is an example

\bin> java com.jmetra.JMetraDoc D:\proj\metrics\aggrbuilds D:\proj\doc

The generated documentation follows a JavaDoc-styled format, where there is an index page, overview-summary.html which lists all the packages that had aggregated metrics. From this page, the user can navigate to package level metrics. From package level metrics, the user can navigate to metrics for a particular class.

NOTE: Details are dynamically filled in on the left side of each graph as the cursor is moved over different data points in the graph.

Helpful batch files

The \bin directory has a batch file template runjMetra.bat that shows the use of jMetra through the three steps that are explained above. Each of the necessary parameters for the project are identified as environment variables. Note that the batch file only shows one set of options that could be used in applying this package. The .bat file should serve as a baseline to customize for your projects. The may also take the approach of tailoring one of the examples .bat files for your project.