Basic Tools

The basic setup of Glean is meant to give you feedback that is easy to generate, immediately useful to almost any project, and with the least reliance on other tools. Start with this set to get a feel for Glean and for how you can incorporate the feedback into your project team. If you find you want to add other feedback sources, there are scripts from Glean for any of the tools listed below (simply list it in the tool.pattern property in your project configuration file), or you can add support for another tool.

These tools come with all of their dependent JARs packaged together. You can download them using the links in the table, or with the tool download script that comes with Glean, and then tell Glean about their install location in the toolhome.properties.local file.

Name	Description
java2html	Source code cross-reference in HTML
javadoc	Class API documentation
javancss	Source code metrics (LOC, McCabe Complexity)
pmd	Static code analysis of style and design

All Tools

Glean comes with scripts for a number of tools. Add any of these to your builds by downloading the tool and then including the name for the tool (from the table below) in the tool.pattern property for your project. Glean's script will then run the tool using the same properties you specified for all of the other tools (e.g. source location). Any other tools or files you need for these is listed for each tool. For instance, in order to run UmlGraph, you need to have GraphViz installed.

More is not necessarily better, so start small and add feedback sources when you find that you can get some benefit from their data.

Name	Description	JDK Level	Dependencies	Home
beandoc	Spring bean documentation	1.4	Graphviz	Site
checkstyle	Checks code against team style and design guidelines.	1.4	None	Site
ckjm	Calculates Chidamber and Kemerer Java Metrics	1.4	None	Site
classycle	Analyzes class and package dependencies.	1.4	None	Site
cobertura	Unit test coverage report	1.4	Optional Ant tasks (JUnit)	Site
cpd	Report of copy/paste segments found in source	1.4	None	Site
dashboard	Summary view of feedback metrics	1.4	Groovy	Site
dbdoclet	Generates DocBook documentation from source code	1.4	Graphviz	Site
depfind	Dependency analysis of packages, classes and features.	1.4	None	Site
doccheck	Checks completion of JavaDoc comments	1.4	None	Site
emma	Unit test coverage report	1.4	Optional Ant tasks (JUnit)	Site
findbugs	Static code analysis for common programming errors	1.4	None	Site
jaranalyzer	Component-level dependency analysis	1.4	Graphviz	Site
java2html14	Java source cross-reference in HTML	1.4	None	Site
java2html15	Java source conversion to HTML	1.5	None	Site
javadoc	Java API documentation	1.4	None	Site
javancss	Source code size and complexity metrics	1.4	None	Site
jcsc	Checks code against naming and style standards.	1.4	None	Site
jdepend	Report on package-level dependency metrics	1.4	None	Site
junitpdfreport	Generates a PDF version of JUnit test results.	1.4	None	Site
junitreport	Browsable report of testcase results	1.4	Optional Ant tasks (JUnit)	Site
linguine-ant	Graph of Ant build file	1.4	Graphviz	Site
linguine-hbm	Graph of Hibernate relationships	1.4	Graphviz	Site
pmd	Static analysis of source files using design and style rules	1.4	None	Site
qalab	Consolidation and tracking of feedback data	1.4	JFreeChart	Site
schemaspy	Database schema and entity browser	1.4	Graphviz	Site
statcvs	Statistical data from CVS repository activity	1.4	CVS command-line client	Site
statsvn	Statistical data from Subversion repository activity	1.4	Subversion command-line client	Site
umlgraph-doc	Javadoc with embedded UML class diagrams	1.5	Graphviz	Site
umlgraph-views	UML class diagrams from source code	1.4	Graphviz	Site
xradar	Gathers feedback data from multiple sources to provide view of system state.	1.5	None	Site

Tool Descriptions

Each of the tools that Glean drives typically makes use of some of the basic common properties of a project, such as the source, binary and library directories. Many of them also have other properties that define what they do or how they produce their output. All of them have reasonable default values that should work for most people as they are, but if you want to customize any part of a tool, see the description below or just dive into the source Ant script.

beandoc

Beandoc is a tool for documenting Spring bean configuration files. Most importantly, it describes and diagrams the relationships between beans, with the bean definitions hyperlinked together.

Property Default value Description
spring.config.pattern **/*Context.xml Naming style for your Spring files

spring.config.dir ${src.dir} Root of search path for config files

Property	Default value	Description
spring.config.pattern	*/Context.xml	Naming style for your Spring files
spring.config.dir	${src.dir}	Root of search path for config files

checkstyle

Checkstyle is a static code analysis tool, in the same category as PMD and a few others. It comes with a number of rules for checking style and conventions, as well as some design patterns.

Property Default value Description
report.stylesheet ${tool.home}/contrib/checkstyle-noframes.xsl One of the output transformations that comes with Checkstyle. Check the distribution for others.

checkstyle.config ${tool.home}/sun_checks.xml Sun's Java style rules

Property	Default value	Description
report.stylesheet	${tool.home}/contrib/checkstyle-noframes.xsl	One of the output transformations that comes with Checkstyle. Check the distribution for others.
checkstyle.config	${tool.home}/sun_checks.xml	Sun's Java style rules

ckjm

This is a tool for computing the Chidamber and Kemerer metrics for Java code. These are similar to metrics that JDepend computes, but this particular data is used to feed XRadar, so if you are using XRadar you will need to include this tool.

Property Default value Description
report.stylesheet ${tool.home}/xsl/ckjm.xsl The default stylesheet that comes with the tool.

Property	Default value	Description
report.stylesheet	${tool.home}/xsl/ckjm.xsl	The default stylesheet that comes with the tool.

classycle

Classycle is a dependency analyzer, looking at both class and package dependencies. Being able to analyze class dependencies means it can provide lower level dependency information than JDepend.

The Classycle download actually provides two tools, Analyser and Dependency Checker. The Glean script only runs the Analyser tool.

Property Default value Description
report.stylesheet ${tool.home}/reportXMLtoHTML.xsl The default stylesheet that comes with the tool.

Property	Default value	Description
report.stylesheet	${tool.home}/reportXMLtoHTML.xsl	The default stylesheet that comes with the tool.

cobertura

Cobertura is a tool for documenting code coverage in general, although it is usually used for test code coverage. Generating the output involves actually running the unit tests, so setting up this script for an individual project involves a few more proprties to consider than most of the other scripts.

Glean comes with a basic Ant script for running JUnit tests, either as a single suite or as a batchtest. It also allows you to define any extra classpaths, so for many projects this may be all that's needed. If it does not, you can either plug in your own test script or modify the Glean script.

If you want to restrict the classes that show up in the coverage report, for example excluding simple beans that have little value in testing, you can specify filters. You can supply a set of inclusion filters as well as a set of exclusion filters. They are written as simple Ant-style patterns in a file that you specify, one pattern per line.

Property Default value Description
unit.test.pattern **/*Test.class An Ant file pattern describing classes that represent unit tests to run. This is used to run a batchtest if no test.suite has been defined

test.suite (undefined) The fully-qualified name of a JUnit test suite.

test.bin.dir ${bin.dir} The location of unit test class files. These will be instrumented by Emma (in a separate location)

test.src.dir ${src.dir}/test-src The location of unit test source. Will be added to the test classpath so that any properties files will be found.

test.lib.dir ${lib.dir} The location of JARs needed for the tests, primarily junit.jar

test.script ${feedback.script.dir}/test.xml A general script for running JUnit test suites or batchtests. While this could be overridden, Glean expects a certain macrodef to be available in order to run the unit tests for Emma. If you find your tests need additional setup that isn't provided here, copy the test.xml file, modify it, and pass that in as the test.script.

cobertura.exclude.filter ${test.src.dir}/cobertura.filter.excludes Name of the file that holds exclusion filters for the coverage report. Filters are Ant-style path syntax, one filter per line.

cobertura.include.filter ${test.src.dir}/cobertura.filter.includes Name of the file that holds inclusion filters for the coverage report. Filters are Ant-style path syntax, one filter per line.

coverage.dir ${gen.report.dir} The output directory used for work files and coverage reports

out.instr.dir ${gen.report.dir}/outinstr The output directory for instrumented classes.

extra.test.path Comma-seperated paths to add to the classpath when running unit tests.

Property	Default value	Description
unit.test.pattern	*/Test.class	An Ant file pattern describing classes that represent unit tests to run. This is used to run a batchtest if no test.suite has been defined
test.suite	(undefined)	The fully-qualified name of a JUnit test suite.
test.bin.dir	${bin.dir}	The location of unit test class files. These will be instrumented by Emma (in a separate location)
test.src.dir	${src.dir}/test-src	The location of unit test source. Will be added to the test classpath so that any properties files will be found.
test.lib.dir	${lib.dir}	The location of JARs needed for the tests, primarily junit.jar
test.script	${feedback.script.dir}/test.xml	A general script for running JUnit test suites or batchtests. While this could be overridden, Glean expects a certain macrodef to be available in order to run the unit tests for Emma. If you find your tests need additional setup that isn't provided here, copy the `test.xml` file, modify it, and pass that in as the test.script.
cobertura.exclude.filter	${test.src.dir}/cobertura.filter.excludes	Name of the file that holds exclusion filters for the coverage report. Filters are Ant-style path syntax, one filter per line.
cobertura.include.filter	${test.src.dir}/cobertura.filter.includes	Name of the file that holds inclusion filters for the coverage report. Filters are Ant-style path syntax, one filter per line.
coverage.dir	${gen.report.dir}	The output directory used for work files and coverage reports
out.instr.dir	${gen.report.dir}/outinstr	The output directory for instrumented classes.
extra.test.path		Comma-seperated paths to add to the classpath when running unit tests.

cpd

CPD is a Copy/Paste Detector that comes with the PMD package. It looks for repeated segments of code within the codebase. The XSL that comes with Glean generates links to the source lines of the duplicate code based on the property src.link.prefix. There are other XSL templates that come with CPD that you can use as well. You may need to alter them if you want to link to your HTML source.

Property Default value Description
src.link.prefix ../java2html14 Set this based on the Java-to-HTML tool you chose to run.

Property	Default value	Description
src.link.prefix	../java2html14	Set this based on the Java-to-HTML tool you chose to run.

dashboard

The Glean dashboard is a custom Groovy script that gathers together a summary of the results of the other analysis tools for a point-in-time view of your feedback. The sample screenshot gives you an idea of what you will see.

Unlike the other tools, enabling the dashboard is done via a separate property, create.dashboard, which should have an Ant "true" value (yes/true/on). It is done this way rather than on the tool.pattern property to make sure that it run after all other tools have run so that it can work with their output..

The Groovy code that runs this needs to be downloaded separately. It is packaged as a JAR, but the source is there too if you want to see how it works or improve on it. (I am new to Groovy, so I make no claims to it being a model of Groovy code.) It is covered under the same style MIT License as Glean.

The Ant script assumes that the GROOVY_HOME environment variable has been set to point to your Groovy installation root.

The dashboard was inspired by Andy Glover's description of a summary page for feedback metrics, and his pointing out how easy it is to gather this stuff together with Groovy.

Glean will look in the standard places for data files from the different tools. You should only need to change any of the properties below if you have had to alter the name or location of the output for these tools.

Property Default Value Description
create.dashboard false Dashboard switch. Any Ant boolean values are valid (yes/true/on).

jdepend.data.file ${gen.report.root}/jdepend/${src.project.name}-jdepend-feedback.xml Data from JDepend

checkstyle.data.file ${gen.report.root}/checkstyle/${src.project.name}-checkstyle-feedback.xml Data from Checkstyle

cobertura.data.file ${gen.report.root}/cobertura/coverage.xml Data from Cobertura

javancss.data.file ${gen.report.root}/javancss/${src.project.name}-javancss-feedback.xml Data from Javancss

junitreport.data.file ${gen.report.root}/junitreport/TESTS-TestSuites.xml Data from JUnitReport

findbugs.data.file ${gen.report.root}/findbugs/${src.project.name}-findbugs-feedback.xml Data from Findbugs

cpd.data.file ${gen.report.root}/cpd/${src.project.name}-cpd-feedback.xml Data from CPD

pmd.data.file ${gen.report.root}/pmd/${src.project.name}-pmd-feedback.xml Data from PMD

emma.data.file ${gen.report.root}/emma/coverage.xml Data from Emma

Property	Default Value	Description
create.dashboard	false	Dashboard switch. Any Ant boolean values are valid (yes/true/on).
jdepend.data.file	${gen.report.root}/jdepend/${src.project.name}-jdepend-feedback.xml	Data from JDepend
checkstyle.data.file	${gen.report.root}/checkstyle/${src.project.name}-checkstyle-feedback.xml	Data from Checkstyle
cobertura.data.file	${gen.report.root}/cobertura/coverage.xml	Data from Cobertura
javancss.data.file	${gen.report.root}/javancss/${src.project.name}-javancss-feedback.xml	Data from Javancss
junitreport.data.file	${gen.report.root}/junitreport/TESTS-TestSuites.xml	Data from JUnitReport
findbugs.data.file	${gen.report.root}/findbugs/${src.project.name}-findbugs-feedback.xml	Data from Findbugs
cpd.data.file	${gen.report.root}/cpd/${src.project.name}-cpd-feedback.xml	Data from CPD
pmd.data.file	${gen.report.root}/pmd/${src.project.name}-pmd-feedback.xml	Data from PMD
emma.data.file	${gen.report.root}/emma/coverage.xml	Data from Emma

dbdoclet

DocBook Doclet is a Javadoc doclet that generates DocBook code rather than HTML. It is great if you want to generate a nicely formatted API document for your system or component. The basic Glean script will generate a PDF document of your API with a basic layout.

Their process takes place in three steps, each of which has settings you can alter.

The Javadoc step uses the same basic properties as the Javadoc script so you can set any of those to affect the content of the documentation. The output of this step is a DocBook formatted file
The transformation from DocBook to FO format files involves an XSL transformation, so you can choose from the stylesheets that come with DocBook Doclet or supply your own.
The final step of creating a PDF from an FO file is handled by Apache FOP, and there are currently no setting choices for that in the Glean script other than the eventual file name. If there are other options that would be worth including, please let me know.

Note: If you are running Java 5 the XSL transformation task in Ant will, by default, use the XSLTC engine, which will want to compile the XSL stylesheet. There is a known issue with the DocBook stylesheets that can cause compiler errors, so the Glean script has the XSLT task use the Xalan processor instead. If Ant complains that it can't find the Xalan classes, you may need to put a copy of them in your ${user.home}/.ant/lib folder.

Property Default value Description
dbdoclet.report.file ${gen.report.dir}/Reference.xml DocBook output file from the doclet

dbdoclet.fo.file ${gen.report.dir}/dbdoclet.fo Intermediate FO file

dbdoclet.pdf.file ${gen.report.dir}/${src.project.name}-API.pdf Final PDF document

dbdoclet.fo.transform ${tool.home}/xslt/fo/Modern.xsl The FO transform. There are several others in the DocBook Doclet distribution you can choose from.

dbdoclet.maxmemory 512m JVM size for the Javadoc task. The doclet can require a significant amount of memory to render the DocBook output.

Property	Default value	Description
dbdoclet.report.file	${gen.report.dir}/Reference.xml	DocBook output file from the doclet
dbdoclet.fo.file	${gen.report.dir}/dbdoclet.fo	Intermediate FO file
dbdoclet.pdf.file	${gen.report.dir}/${src.project.name}-API.pdf	Final PDF document
dbdoclet.fo.transform	${tool.home}/xslt/fo/Modern.xsl	The FO transform. There are several others in the DocBook Doclet distribution you can choose from.
dbdoclet.maxmemory	512m	JVM size for the Javadoc task. The doclet can require a significant amount of memory to render the DocBook output.

depfind

Depfind is another dependency analyzer, like JDepend or Classycle, which can also computer some metrics, like JavaNCSS or ckjm does. The standard report that the Glean script produces is raw dependency information, which can be rather large. The main use of this tool in Glean is as input to XRadar. If you are using XRadar, you will need to run this tool.

Property Default value Description
report.stylesheet ${tool.home}/etc/DependencyGraphToHTML.xsl The default stylesheet that comes with the tool.

Property	Default value	Description
report.stylesheet	${tool.home}/etc/DependencyGraphToHTML.xsl	The default stylesheet that comes with the tool.

doccheck

This is a fairly antiquated and unsupported tool from Sun, but it does its job well: report on missing or incorect Javadoc. Checkstyle has some rules that can be configured to do similar checks, but this could be a useful tool if you are using a different code analysis tool that doesn't have Javadoc checks.

emma

Emma, like Cobertura, is a general code coverage tool most often used for test code coverage. It works in a similar way to Cobertura, with the script needing to run the project's unit tests.

If you want to restrict the classes that show up in the coverage report, for example excluding simple beans that have little value in testing, you can supply a filter file. The Emma documentation descibes the format of its coverage filters.

Property Default value Description
unit.test.pattern **/test/*Test.class An Ant file pattern describing classes that represent unit tests to run. This is used to run a batchtest if no test.suite has been defined

test.suite (undefined) The fully-qualified name of a JUnit test suite.

test.bin.dir ${bin.dir} The location of unit test class files. These will be instrumented by Emma (in a separate location)

test.src.dir ${src.dir}/test-src The location of unit test source. Will be added to the test classpath so that any properties files will be found.

test.lib.dir ${lib.dir} The location of JARs needed for the tests, primarily junit.jar

test.script ${feedback.script.dir}/test.xml A general script for running JUnit test suites or batchtests. While this could be overridden, Glean expects a certain macrodef to be available in order to run the unit tests for Emma. If you find your tests need additional setup that isn't provided here, copy the test.xml file, modify it, and pass that in as the test.script.

project.report.filter ${test.src.dir}/emma-filters.txt Name of the file the script will look for if you wish to define filters for the coverage report.

default.filter filters.txt A set of basic filters the script will use if there are no project-specific filters.

coverage.dir ${gen.report.dir} The output directory used for work files and coverage reports

out.instr.dir ${gen.report.dir}/outinstr The output directory for instrumented classes.

extra.test.path Comma-seperated paths to add to the classpath when running unit tests.

Property	Default value	Description
unit.test.pattern	*/test/Test.class	An Ant file pattern describing classes that represent unit tests to run. This is used to run a batchtest if no test.suite has been defined
test.suite	(undefined)	The fully-qualified name of a JUnit test suite.
test.bin.dir	${bin.dir}	The location of unit test class files. These will be instrumented by Emma (in a separate location)
test.src.dir	${src.dir}/test-src	The location of unit test source. Will be added to the test classpath so that any properties files will be found.
test.lib.dir	${lib.dir}	The location of JARs needed for the tests, primarily junit.jar
test.script	${feedback.script.dir}/test.xml	A general script for running JUnit test suites or batchtests. While this could be overridden, Glean expects a certain macrodef to be available in order to run the unit tests for Emma. If you find your tests need additional setup that isn't provided here, copy the `test.xml` file, modify it, and pass that in as the test.script.
project.report.filter	${test.src.dir}/emma-filters.txt	Name of the file the script will look for if you wish to define filters for the coverage report.
default.filter	filters.txt	A set of basic filters the script will use if there are no project-specific filters.
coverage.dir	${gen.report.dir}	The output directory used for work files and coverage reports
out.instr.dir	${gen.report.dir}/outinstr	The output directory for instrumented classes.
extra.test.path		Comma-seperated paths to add to the classpath when running unit tests.

findbugs

Findbugs is a tool to check for common Java coding errors. Glean runs its Ant task, along with a basic XSLT to generate a static HTML report. It also produces XML output can also be used by the QALab script.

Property Default value Description
report.stylesheet ${tool.basedir}/findbugs.xsl Analysis report with links to source xref. Other stylesheets are available with the Findbugs distribution.

findbugs.report.level medium The priority level threshold for bugs that are reported

findbugs.timeout 600000 Amount of time in milliseconds before the Findbugs task will be assumed to be hung and will be ended.

findbugs.stylesheet default.xsl This stylesheet is only used if the findbugs.report.format is set to html. Otherwise, the report.stylesheet will be used.

findbugs.report.format xml:withMessages The 'withMessages' format for the XML provides more readable results, and having it in XML format allows the data to be read by QALab as well.

Property	Default value	Description
report.stylesheet	${tool.basedir}/findbugs.xsl	Analysis report with links to source xref. Other stylesheets are available with the Findbugs distribution.
findbugs.report.level	medium	The priority level threshold for bugs that are reported
findbugs.timeout	600000	Amount of time in milliseconds before the Findbugs task will be assumed to be hung and will be ended.
findbugs.stylesheet	default.xsl	This stylesheet is only used if the `findbugs.report.format` is set to `html`. Otherwise, the report.stylesheet will be used.
findbugs.report.format	xml:withMessages	The 'withMessages' format for the XML provides more readable results, and having it in XML format allows the data to be read by QALab as well.

jaranalyzer

JarAnalyzer is a great tool for discovering or keeping track of the dependencies you have between components (JARs). It is like JDepend taken up one level. The report it produces is very similar to JDepend's, with similar metrics that you can track or investigate. It is also possible to produce output in DOT format that you can send to Graphviz and generate a graph view of the component relationships. I'm working on a way to specify that format through Glean because I think that's a very powerful way to express it.

Property Default value Description
jaranalyzer.jar.filter Ant glob pattern of JAR files to exclude from processing

jaranalyzer.package.filter java.*;javax.* Ant glob pattern of packages to exclude from processing

jaranalyzer.lib.dir ${lib.dir} Location of JAR files to analyze.

Property	Default value	Description
jaranalyzer.jar.filter		Ant glob pattern of JAR files to exclude from processing
jaranalyzer.package.filter	java.;javax.	Ant glob pattern of packages to exclude from processing
jaranalyzer.lib.dir	${lib.dir}	Location of JAR files to analyze.

java2html14

There are two open-source tools with the name "Java2HTML". This script drives the one from java2html.com. It creates a very nice framed source browser, but it only supports syntax through JDK 1.4. If you have source with Java 5 syntax (e.g. generics, enums) you should use the java2html15 script, which drives the other Java2html.

If you are running Glean under JDK 1.4 and want to use this script, you will also need to grab a slightly older version of Java2HTML, v1.3. The v1.4 release seems to have been compiled with JDK 1.5, so that it complains about an "Unsupported major.minor version 49.0" when you run it. The v1.3 release works just fine for JDK 1.4 code.

java2html15

This script drives the other tool with the name Java2HTML, the one from java2html.de. This tool simply creates HTML versions of the source, without any intent for it to be easily browsable. If you have Java 5 source, however, it is the only one to use. It still serves fine for creating targets for the static code analysis tools, like PMD, CPD or Findbugs.

javadoc

The venerable Javadoc is something that most build scripts probably generate already. I include it as an option in Glean so that you can remove it from your custom build script if you want to. Like all of these other tools, the Ant script for Javadoc is not going to differ greatly from one project to another.

That said, there are plenty of ways that you may be customizing Javadoc already. Glean has some properties that should hopefully let you get the same mileage out of it's script as you get out of yours.

If you use XDoclet, Glean provides lists of common XDoclet tags that you may want to ignore, if for no other reason than to keep your Javadoc log more readable. You can look in the tool/javadoc folder for the list of files of tags available. You can then define javadoc.taglist.files to be the file(s) to use as filters for Javadoc.

Property Default value Description
report.title ${src.project.name} The value of the doctitle Javadoc argument.

report.header ${src.project.name} API The value of the header Javadoc argument.

report.footer Generated on ${tool.timestamp} The value of the bottom Javadoc argument.

report.overview ${src.dir}/overview.html

javadoc.taglist.files empty A list of files to use as Javadoc tag filters. A set of files containing common XDoclet tags is in tool/javadoc.

Property	Default value	Description
report.title	${src.project.name}	The value of the `doctitle` Javadoc argument.
report.header	${src.project.name} API	The value of the `header` Javadoc argument.
report.footer	Generated on ${tool.timestamp}	The value of the `bottom` Javadoc argument.
report.overview	${src.dir}/overview.html
javadoc.taglist.files	empty	A list of files to use as Javadoc tag filters. A set of files containing common XDoclet tags is in `tool/javadoc`.

javancss

JavaNCSS calculates a number of different source metrics. First among them is Non-Commenting Source Statements (NCSS), what we might call Lines Of Code. It also calculates cyclomatic complexity and Javadoc comments at the method level.

Glean includes one of the XSLTs that comes with JavaNCSS to generate the report. You can use any other XSLT you want by overriding the report.stylesheet property.

jcsc

JCSC is a static analysis tool, along the lines of Checkstyle and PMD, with some metrics calculations thrown in as well. It presents its results in a three-paned frame for easy browsing.

Property Default value Description
jcsc.rules ${tool.home}/rules/jcsc.jcsc.xml Coding style rules

Property	Default value	Description
jcsc.rules	${tool.home}/rules/jcsc.jcsc.xml	Coding style rules

jdepend

JDepend calculates dependency metrics at a package level, along with some design metrics developed by Bob Martin. Its feedback can be useful for designers to keep an eye on how an application or component design is coming together.

junitpdfreport

JUnitPDFReport does just what it says: it produces a PDF version of a JUnit report. It comes with a handful of "themes" to give you a choice of the look for the report, from the simple to the complex.

This tool depends on the Batik library, which must be downloaded separately.

Property Default value Description
fop.dir ${tool.home}/lib The location of the FOP JARs to use.

junitpdfreport.style default The theme to use for the report.

Property	Default value	Description
fop.dir	${tool.home}/lib	The location of the FOP JARs to use.
junitpdfreport.style	default	The theme to use for the report.

junitreport

JUnitReport is an optional task in Ant that creates a browsable report of your unit test results. The Glean script assumes that you have the Ant optional tasks installed.

Property Default value Description
test.report.dir ${gen.report.dir}/tests The directory that contains XML-formatted test results.

test.results.pattern TEST-*.xml The naming pattern for the unit test results files.

junitreport.format frames Valid choices for format are 'frames' and 'noframes'

Property	Default value	Description
test.report.dir	${gen.report.dir}/tests	The directory that contains XML-formatted test results.
test.results.pattern	TEST-*.xml	The naming pattern for the unit test results files.
junitreport.format	frames	Valid choices for format are 'frames' and 'noframes'

linguine-ant

The Linguine Maps tool creates diagrams of various artifacts from your project. This script will create a diagram showing the relationship of targets in an Ant file.

Property Default value Description
linguine.colors cyan, black, black Defines the look of the resulting graph

linguine.ant.file ${project.root}/build.xml The build file to diagram.

Property	Default value	Description
linguine.colors	cyan, black, black	Defines the look of the resulting graph
linguine.ant.file	${project.root}/build.xml	The build file to diagram.

linguine-hbm

This is another use of the Linguine Maps tool, this time to generate a diagram of the relationships defined in a set of Hibernate mapping files.

Property Default value Description
linguine.hbm.dir ${resources.dir} The root of the directory that contains .hbm files

linguine.colors cyan, black, black Defines the look of the resulting graph

Property	Default value	Description
linguine.hbm.dir	${resources.dir}	The root of the directory that contains .hbm files
linguine.colors	cyan, black, black	Defines the look of the resulting graph

pmd

PMD is a static code analysis tool. It is in the same category as Checkstyle, but has a slightly different set of rules it uses, and a different mechanism for configuring and creating new rules.

Glean provides a basic ruleset definition file, but you will probably want to define your own to match the expectations of your group or organization.

Property Default value Description
pmd.rulesets ${basedir}/ruleset.xml The ruleset definition file.

Property	Default value	Description
pmd.rulesets	${basedir}/ruleset.xml	The ruleset definition file.

qalab

QALab is a tool that consolidates data from a number of analysis tools and then creates graphs that allow you to see the change in metrics over time. It is a great tool for helping to keep an eye on key quality metrics during an ongoing development effort. The tools it tracks are (almost) all ones that Glean also supports, so Glean can discover which ones you are running and automatically include them in the QALab report. That means that to start using QALab, all you need to do is add its name to the tool.pattern setting for your project and let it go.

QALab parses the XML output of the different tools, so in order to make sure that the data is ready, you will need to place it after the other tools in the tool.pattern list. QALab currently supports these tools:

Checkstyle
Cobertura (line and branch metrics tracked separately)
Findbugs
PMD
CPD
Simian

The Glean script supports all of these except for Simian, since Simian is not an open-source tool and I have not had a chance to work with it. CPD is in the same category of tool, so if you are looking for a copy/paste detection tool, start with CPD.

There is also currently a bit of a conundrum with Findbugs in the QALab 1.0 release. The Findbugs format that QALab parses is the "xdoc" format, which is what Findbugs can emit for Maven reporting. And unfortunately, Findbugs does not allow you to specify multiple output formats. The good news is that QALab 1.1 should have support for the XML format from Findbugs. Until then, you will have to choose between getting a Findbugs report and getting QALab analysis of Findbugs data.

Another important note is that the QALab data files contain historical data, with each run of QALab adding more data on your project. Therefore they should live somewhere where they can be backed up or committed to source control, and not in the same place as the normal Glean output.

Lastly, the XSLTs for QALab are only included in the source distribution, so you can either download the binary and the source, or just the source and build the binaries.

Property Default value Description
qalab.data.file ${user.home}/${src.project.name}-qalab.xml The main datafile.

qalab.movers.file ${user.home}/${src.project.name}-qalab-movers.xml The datafile for "movers", or classes whose metrics are changing most in a given period.

qalab.chart.width 500 The default width of the data charts.

qalab.chart.height 333 The default height of the data charts.

qalab.summary.only false Whether or not to have individual class charts or only a project summary chart.

qalab.moving.average 10 The number of days to use as a moving average to smooth out the graphs.

qalab.chart.stylesheet ${qalab.home}/qalab/src/xslt/qalab-chart-html.xsl The XSL for generating charts.

qalab.movers.stylesheet ${qalab.home}/qalab/src/xslt/qalab-movers-html.xsl The XSL for generating the movers reports.

jfreechart.home ${tools.base}/jfreechart-1.0.5 The location of your JFreechart installation.

checkstyle.data.file ${gen.report.root}/checkstyle/${src.project.name}-checkstyle-feedback.xml The location of the Checkstyle XML output.

cobertura.data.file ${gen.report.root}/cobertura/coverage.xml The location of the Cobertura XML output.

cpd.data.file ${gen.report.root}/cpd/${src.project.name}-cpd-feedback.xml The location of the CPD XML output.

pmd.data.file ${gen.report.root}/pmd/${src.project.name}-pmd-feedback.xml The location of the PMD XML output.

findbugs.data.file ${gen.report.root}/findbugs/${src.project.name}-findbugs-feedback.xdoc The location of the Findbugs XML output.

Property	Default value	Description
qalab.data.file	${user.home}/${src.project.name}-qalab.xml	The main datafile.
qalab.movers.file	${user.home}/${src.project.name}-qalab-movers.xml	The datafile for "movers", or classes whose metrics are changing most in a given period.
qalab.chart.width	500	The default width of the data charts.
qalab.chart.height	333	The default height of the data charts.
qalab.summary.only	false	Whether or not to have individual class charts or only a project summary chart.
qalab.moving.average	10	The number of days to use as a moving average to smooth out the graphs.
qalab.chart.stylesheet	${qalab.home}/qalab/src/xslt/qalab-chart-html.xsl	The XSL for generating charts.
qalab.movers.stylesheet	${qalab.home}/qalab/src/xslt/qalab-movers-html.xsl	The XSL for generating the movers reports.
jfreechart.home	${tools.base}/jfreechart-1.0.5	The location of your JFreechart installation.
checkstyle.data.file	${gen.report.root}/checkstyle/${src.project.name}-checkstyle-feedback.xml	The location of the Checkstyle XML output.
cobertura.data.file	${gen.report.root}/cobertura/coverage.xml	The location of the Cobertura XML output.
cpd.data.file	${gen.report.root}/cpd/${src.project.name}-cpd-feedback.xml	The location of the CPD XML output.
pmd.data.file	${gen.report.root}/pmd/${src.project.name}-pmd-feedback.xml	The location of the PMD XML output.
findbugs.data.file	${gen.report.root}/findbugs/${src.project.name}-findbugs-feedback.xdoc	The location of the Findbugs XML output.

schemaspy

SchemaSpy is a schema browser for JDBC-compliant databases. It uses the JDBC metadata to create browsable documentation of the tables, columns, constraints and relationships of a database. It supports a lot of databases, and has been invaluable to me for understanding the structure of a system that's new to me.

It also can generate relationship diagrams if you have Graphviz installed. If you don't, it will still generate the table-based documentation.

Configuring SchemaSpy has some dependencies on the type of database you want to inspect, so see the SchemaSpy documentation for specifics of the values for the properties.

Property Default value Description
schemaspy.jar ${tool.home}/schemaSpy_3.1.1.jar Location of the SchemaSpy JAR

db.driver.path ${tools.base}/mysql-connector-java-5.0.4/mysql-connector-java-5.0.4-bin.jar Location of the JDBC driver for your database.

db.name Name of the database

db.type mysql Type of database

db.schema Schema name

db.user root Name to use when connecting to the database

db.password Password for db.user. Can be empty

db.host localhost Server name of the database

db.port Port to connect to on the database server

Property	Default value	Description
schemaspy.jar	${tool.home}/schemaSpy_3.1.1.jar	Location of the SchemaSpy JAR
db.driver.path	${tools.base}/mysql-connector-java-5.0.4/mysql-connector-java-5.0.4-bin.jar	Location of the JDBC driver for your database.
db.name		Name of the database
db.type	mysql	Type of database
db.schema		Schema name
db.user	root	Name to use when connecting to the database
db.password		Password for db.user. Can be empty
db.host	localhost	Server name of the database
db.port		Port to connect to on the database server

svatcvs

StatCVS is a tool that analyzes the commit history from a CVS repository. You can see line count graphs over time, commit counts by developer, when the busiest commit time during the day or week was, or where there is the most activity in the codebase. It is the basis for StatSVN, which does the same thing (with a few more features) for a Subversion repository.

By default, the Glean script will have StatCVS look at all history on the files. If you want to limit it, you can set a value for one of the statcvs.prev.(units) properties listed below.

Property Default value Description
cvs.log.file ${gen.report.dir}/cvslog.log Where to generate the cvs log file needed as input to StatCVS

cvs.include.pattern **/*.java Pattern of which files whose history you are interested in

statcvs.prev.days The number of days of history to analyze

statcvs.prev.weeks The number of weeks of history to analyze

statcvs.prev.months The number of months of history to analyze

Property	Default value	Description
cvs.log.file	${gen.report.dir}/cvslog.log	Where to generate the cvs log file needed as input to StatCVS
cvs.include.pattern	*/.java	Pattern of which files whose history you are interested in
statcvs.prev.days		The number of days of history to analyze
statcvs.prev.weeks		The number of weeks of history to analyze
statcvs.prev.months		The number of months of history to analyze

svatsvn

StatSVN is a tool that slices and dices data on Subversion commit history in various and sundry ways. You can see line count graphs over time, commit counts by developer, when the busiest commit time during the day or week was, or where there is the most activity in the codebase. It is derived from StatCVS, which does the same sort of thing with CVS activity data.

By default, the Glean script will have StatSVN look at all history on the files. If you want to limit it, you can set a value for one of the statsvn.prev.(units) properties listed below.

Property Default value Description
svn.log.file ${gen.report.dir}/svnlog.log Where to generate the svn log file needed as input to StatSVN

svn.include.pattern **/*.java Pattern of which files whose history you are interested in

statsvn.prev.days The number of days of history to analyze

statsvn.prev.weeks The number of weeks of history to analyze

statsvn.prev.months The number of months of history to analyze

Property	Default value	Description
svn.log.file	${gen.report.dir}/svnlog.log	Where to generate the svn log file needed as input to StatSVN
svn.include.pattern	*/.java	Pattern of which files whose history you are interested in
statsvn.prev.days		The number of days of history to analyze
statsvn.prev.weeks		The number of weeks of history to analyze
statsvn.prev.months		The number of months of history to analyze

umlgraph-doc

UMLGraph is a tool that can generate UML class diagrams from declarative descriptions. Since those descriptions are a subset of the Java class syntax, you can feed it your source files and it will generate class diagrams from them.

One of the recent additions to UMLGraph is a doclet that will insert class diagrams into Javadoc. The umlgraph-doc script in Glean runs this doclet. It uses the same properties that the javadoc script does for title/header/footer.

Property	Default value	Description
graphviz.font.name	Arial	Name of the default font to use for the diagrams.
umlgraph.hide.classes	(java.io.\|java.lang.\|java.math.\|java.net.\|java.nio.\|java.sql.\|java.text.*)	Regular expression describing classes to hide from the diagrams.

umlgraph-views

UMLGraph can also generate class diagrams based on "view" descriptions. These are descriptions based on UMLGraph-specific Javadoc tags that allow you to specify the content, style, and color of diagram elements. To use this Glean script, you will need to have these description files somewhere in your source tree. The UMLGraph documentation describes the content of the files.

The output from UMLGraph will be PNG files, located in the directory defined by gen.report.dir.

Property Default value Description
report.view.src ${project.root}/report-src/views The location of view description files.

Property	Default value	Description
report.view.src	${project.root}/report-src/views	The location of view description files.

xradar

XRadar is a meta-tool that provides a rich set of reports and visualizations of the state of your software, based on the data generated by a number of other tools. Because of the number of data sources that XRadar uses, and the number of other customizations that XRadar allows, the potential configuration setup could be large. Since Glean already has the ability to run all of the tools it needs, and it knows about the structure of your project, you should not need to define anything new to get an initial report running.

You will, however, need to make sure that you are running the set of tools that XRadar uses. As of XRadar v0.99.2, these are the tools it uses:

checkstyle
ckjm
cpd
depfind
java2html15
javancss
jdepend
pmd

Additionally, if you have unit tests and want to include their data, you should include these tools:

cobertura
junitreport

There are actually two types of reports that XRadar can produce, a "statics" report and a "dynamics" report. The "dynamics" report requires a history of tool data available, which Glean can't assume exists, so for now the Glean script just runs a "statics" report.

Property Default value Description
date.label ${tool.timestamp} A date label to include in the report header

system.label ${src.project.name} The name to include in the report header

version.prefix String to include before any system version information.

version.current 1 Version string too use in report header

statics.properties.file ${tool.basedir}/etc/statics.properties Location of the main XRadar config file. See this file for descriptions of the other parameters available for the tool.

Property	Default value	Description
date.label	${tool.timestamp}	A date label to include in the report header
system.label	${src.project.name}	The name to include in the report header
version.prefix		String to include before any system version information.
version.current	1	Version string too use in report header
statics.properties.file	${tool.basedir}/etc/statics.properties	Location of the main XRadar config file. See this file for descriptions of the other parameters available for the tool.