Tools
FAQ
How do I use this package in a project?
If you do not have a configuration control system or a build process, you probably just want to configure a .bat to collect metrics from your projects working directory periodically. How frequent you collect new metrics depends on the level of development occurring in the project. Most project teams either collect metrics at the end of every day of development or collect metrics within their build process.
My project has multiple java source roots. Can jMetra automatically compile metrics across all the different source roots?
Yes, it can. The only current restriction is that all the different source roots must be under one parent directory and must be identified by the same root keyword. For example, if we have three root sources, /proj/src/gl/java, /proj/src/gx/java, and /proj/src/orgs/java, the option -rootsource /proj/src java can be used on the commandline for collecting all metrics for classes rooted in any of subdirectories under /proj/src that have the root directory named java.
What happens if some source files change names through their lifecycle? Or certain project packages move while their contained classes stay the same?
jMetra is able to consistently collect metrics for classes eventhough their names or locations may change within the project lifecycle. But, you need to explicitly tell jMetra when class names change or packages are moved. See the section Code Metrics Continuity. If you don't provide this information to jMetra, the old package or class will just show up as [Not Current], identified by a red asterisk in the jMetraDoc. The package or class, with its new name, will show up in the jMetraDoc as newly added, with only one build measurement.
What happens if metrics collections are done sporadically? Are the metrics still helpful?
Yes, they are still helpful. jMetra generated graphs of metrics always have an X-axis of unit of days, so you can easily see when your project metrics evolve over absolute time. Of course, consistent collection of metrics will always provide more information.
What happens if a directory of metrics files is being aggregated, and some of the metrics files have already been aggregated to the destination before?
jMetra is smart enough to not redundantly add metrics that have the same timestamps/labels. Because of this, you can keep all your collected metrics in the same directory location, and repeatedly aggregate against the same directory. jMetra might be searching through a lot of metrics it has already added, but it will not add any redundantly.
Can I reproduce the aggregate metrics files if I just have a collection of metrics xml files?
Yes, you can. If you blow away your aggregate metrics directory and the aggregate archive file, and run aggregation again, as long as you still have all your metrics files. It will go through each metrics file and add those metrics to a new set of aggregate files. That is a good reason to always keep around your individual metrics files through time. You can always derive all the aggregate files and the documentation from these files.
How are the graphs scaled?
The X-axis is always in units of days. It currently has a fixed scale. The Y-axis will scale depending on the maximum data value for the collection of metrics being displayed.
Some of the graphs have a different number of days on the X-axis. How is that determined?
The number of days provided on the X-axis is based on the period between the oldest metric and most recent metric collected from the current package or any of its subpackages.
Why are package level metrics calculated on-the-fly during documentation generation? It would be nice to see the package level metrics in the project-level metrics or aggregate-level metrics files.
Through experience we found that there are many cases where it would be undesirable to calculate package level metrics up front. First, if packages are moved around or classes change locations in the future, the package metrics can reflect erroneous metrics. Secondly, package level metrics are only valid within the root package you used to produce the metrics file. For generating jMetra Doc you might want to select only specific packages from your project. The package level metrics for the packages selected will not nessassarily correspond to the package level metrics that you would have collected up front. This is because the collecting of packages that documentation is being generated for is not necessarily the same set of packages that you collected metrics for with JMetraMaker.
