Tools

Examples

Hello World Example

In this example, we have five versions of the classic hello world, and an additional working directory. In the typical evolution of a project, metrics will be collected from an individuals working directory or a staging area where a configuration control system has put the code before a formal build process.

This example first demonstrates collecting metrics and generating documentation for those metrics based on a set of archived versions of our hello world project. Located in /jmetra/examples/helloworld, we have five different versions of code (v1 through v5) and a working directory. Secondly, this example demonstrates how current/new metrics are incrementally added as a project evolves based on the contents of the working directory.

Setting Up the Example

This example is included with the jmetra.zip you downloaded. The example is located in the jmetra/examples/helloworld directory. The example contains two .bat files. One generates the baseline of metrics from the archived versions. The second .bat shows how jMetra is run repeatedly so new metrics are incrementally added to the existing collection of metrics.

Generating HelloWorld Metrics and Metrics Doc Baseline

The first .bat generates all the metrics and HTML metrics documents for the archived versions of helloworld. It executes the three phases of jMetra metrics collection: extracting the metrics, aggregating the metrics, and generating the jMetra HTML documentation.

For our examples, we have manually specified a timestamp for each of the versions. From the appropriate directory execute the following:

	jmetra/examples/helloworld/bin> runJMetraBaseline.bat

This first generated the metrics files for each of the archived versions and put them into individual files.After executing the command line JMetraMaker for the different versions of source code, the following XML files should be present in the directory examples/helloworld/metrics:

	2002.01.05.000000metrics.xml
	2002.01.10.000000metrics.xml
	2002.01.15.000000metrics.xml
	2002.02.05.000000metrics.xml
	2002.03.10.000000metrics.xml

Each of these files capture all the metrics associated with that particular version of helloworld. There is no ambiquity regarding which metrics files are newer when looking at the files since we have labeled them with timestamps.

Running runJMetraBaseline.bat next aggregated the five metrics files listed above. These aggregated metrics were put in the root directory /examples/helloworld/metrics/aggrbuild. Within this directory, there is a file for each class which contains the metrics for that class across time. These are used for generating the jMetra Doc.

In the final stage, jMetra generated HTML based documentation regarding all the metrics. It exclusively used the aggregated metrics located in /examples/helloworld/metrics/aggrbuild to generate the documents. The document HTML is found in /examples/helloworld/metrics/docs.

Incrementally adding new Metrics for HelloWorld

The second .bat collects a new set of metrics for the helloworld code residing in the /examples/helloworld/working directory. It then aggregates these metrics onto the existing aggregate metrics files. The jMetra doc is then reproduced. Note that since you do not specify a timestamp, it used the current time. From the appropriate directory execute the following:

	jmetra/examples/helloworld/bin> runJMetra.bat

Experiment by opening up a project with an IDE for the source code in the working directory. Add sometime to the existing code or add a class, and run the runJMetra.bat again. The data for your new code will be added to the metrics and the resulting metrics doc. Metrics taken on the same day are placed close together on the x-axis so it may not be apparent that multiple data points exist. As you move the cursor over the bars, the verbose information about the metrics are displayed on the left side.

Note: Code must have valid Java syntax for jMetra to collect metrics.

Summary

This example demonstrates the application of jMetra to collect metrics from archived versions of a project and also demonstrates how jMetra is may be set up so new metrics can be periodically taken from a working directory or build directory, and added on to the existing metrics.

Ant Open Source Example

Before you get confused, this example is using source code from five different versions of Ant to demonstrate jMetra. The example demonstrates jMetra collecting code metrics for each version of Ant source code (v1.0, v1.2, v1.3, v1.4, and v1.4.1), aggregating it, and showing the metrics in documentation. We are simply using Ant source code as a manageable code base for demonstrating jMetra. Plus, it is a real world example. To see how jMetra integrates with Ant, see the section entitled Ant Integration.

Important Notice: We make no claim regarding the source or execution of the Ant source code in the examples. If you wish to use Ant, you should download it from the Apache Foundation site located within the Jakarta Project. Ant source code is freely available.

We have already organized all the different versions of Ant source code within a zip for you to download. We include this detailed example in a seperate zip file, because it is larger than the jMetra zip itself. Once you download the jmetra_examples.zip file, unpack it at the install home directory of JMetra (e.g. your path will look like d:/jmetra/examples/ant/.... after you unpack it).This will be the location of our source code used for the example, and the metrics derived from the different versions of Ant source code by jMetra.

Setting Up the Example

Downloading

The zip file contains Ant source code versions 1.1, 1.2, 1.3, and 1.4.1. We've made it easy, you just click here....

Unpack

All the files contained it the jmetra_examples.zip have the relative path /examples/ant. Extract these into the ${INSTALL_HOME}/jmetra directory.

Generating Project Metrics Files and Aggregated Metrics Files

In the example, we want to first generate metrics for each of the versions of source code for Ant. As we run jMetra on each of the versions of source code, a metrics file specific to that source code will be generated. Each of the metrics files will be output to the directory examples/ant/metrics. For our example, we have provided two .bat files. One demonstrates assigning project metrics files named with a specific label, such as a version. The other demonstrates the use of a timestamp for labeling. For simplicity, the .bat files delete all the metrics that may already exist in the directory from a previous run. From the directory execute the following:

	/examples/ant/bin> metricswversions.bat

This .bat file does two things. It collects metrics for each version of the code first, then it adds metrics from each of the versions into the aggregate metrics it creates.

After executing JMetraMaker for the different versions of source code, the following XML files should be present in the directory examples/ant/metrics:

	v1.1metrics.xml
	v1.2metrics.xml
	v1.3metrics.xml
	v1.4metrics.xml
	v1.4.1metrics.xml

Each of these files capture all the metrics associated with that particular version of Ant. Eventhough we have chosen to explicitly label these metrics files, they internally contain the date that was specified for the build/version on the command line.

After these five metrics files were generated, aggregation was executed. You might have noted some of the verbose messages displaying "aggregating package ....". For each of the java source files with the name XXXX.java, a corresponding metrics file named XXXXmetrics.xml will be generated. All these files are generated within the directory /examples/ant/metrics/aggrbuild. These files are used to generate the HTML-documents for the project.

For generating these same metrics, but using the the implicit timestamp labelling, execute the following:

	/examples/ant/bin> metricswtstamps.bat

After executing JMetraMaker for the different versions of source code again, the following XML files should be present in the directory examples/ant/metrics:

	2000.06.18.000000metrics.xml
	2000.10.24.000000metrics.xml
	2001.03.02.000000metrics.xml
	2001.09.03.000000metrics.xml
	2001.10.11.000000metrics.xml

Each of these files capture all the metrics associated with that particular version of Ant, tabled by the timestamp that was specified on the command line. These files contain the same metrics data as the labeled ones, they just have a different file naming scheme. There is no ambiquity regarding which metrics files are newer when looking at the files since jMetra implicitly labeled them with timestamps.

The collection of aggregate (temporal) metrics files can be used to generate jMetra Doc, to more easily visualize and analyze the metrics collected over time.

Usage Note: If we were developing more code, we would periodically run a .bat where we would not specify the timestamp so the current time would be used. During the aggregation phase, it would just add an entry to each aggregated metrics file for the new metrics collected for that class. To reduce time during the aggregation phase, you can use the -recent option to only aggregate builds that occurred over the last X days. Eventhough jMetra will not add duplicate metrics for builds with the same labels, it reduces the execution time since jMetra will simply skip over builds with it sees are not recent enough to actually check if the metrics have been added.

Generating jMetraDoc

Generating JavaDoc-styled HTML to assist in browsing the metrics results for a project is easily produced. The JMetraDoc interface is simply provided the location of the produced aggregate Ant metrics. From the /bin directory execute the following:

	/examples/ant/bin> metricsdoc.bat

After executing this .bat, the documentation for the metrics of Ant, spanning the different versions, is browsable, starting at /examples/ant/metrics/doc/overview-summary.html .

Summary

This example demonstrates the application of jMetra to collect metrics across several different versions of Ant. These .bat files should be viewed to understand how the command line options and arguments were used for this example. It should be noted that a user is typically collecting metrics on a regular basis during the development of a project so the data points would be substantially greater in number.

Additionally, in a typical development scheme, the -tstamp option is usually not specified since the metrics are being collected and assigned the current time of execution.