Getting Started Quickly

If you have a straight-forward project structure with all of your source code in one directory and all of your unit tests in another directory then the quickest way to get started is to copy and edit the build-example.xml file in the panopticode directory. If you have a more complicated project structure then please proceed to the detailed overview for instructions.

  1. Check if you have Java 5 or later installed by typing 'Java -version'
  2. Check if you have Javadoc installed and available on your path by typing 'javadoc' If you get a message that says something like 'javadoc: error - No packages or classes specified.' then you are good to go.
  3. Check if you have Ant 1.6 or later installed and available on your path by typing 'ant -version'
  4. Unzip the panopticode-0.1.zip file into your project's root directory.
  5. Copy PROJECT_ROOT/panopticode/build-example.xml to PROJECT_ROOT/build.xml
  6. Edit the build.xml:
    1. Replace PROJECT_NAME with the name of your project
    2. Replace PROJECT_VERSION with the version of your project
    3. Replace prod/src with the location of your project's source code
    4. Edit the <classpath> element to include any classes needed to build your project
    5. Replace unittest/src with the location of your project's source code
  7. From the command line type ant metrics

That's it! You should now have a directory called target containing several files including:

Detailed Overview

Using Panopticode is a three step process:

  1. Gather your project's structure
  2. Supplement project structure with metrics
  3. Generate reports and visualizations

Gather Your Project's Structure

Panopticode gathers project structure using a custom doclet. This doclet creates a canonical representation of your Java project that is used as the foundation to integrate metrics into.

Usage:

<javadoc classpath="PATH_TO_PANOPTICODE_JAR"
         sourcepath="SOURCE_CODE_DIR"
         access="private">
   <fileset dir="SOURCE_CODE_DIR" />
   <doclet name="org.panopticode.doclet.PanopticodeDoclet"
           path="PATH_TO_PANOPTICODE_JAR">
      <param name="-projectName" value="PROJECT_NAME" />
      <param name="-projectVersion" value="PROJECT_VERSION" />
      <param name="-outputFile" value="PANOPTICODE_FILE" />
   </doclet>
</javadoc>

Supplement Project Structure With Metrics

CheckStyle Supplement

Usage:

<taskdef name="mergeCheckStyle"
         classpath="PATH_TO_PANOPTICODE_JAR"
         classname="org.panopticode.supplement.ant.CheckstylePanopticode">
</taskdef>

<mergeCheckStyle panopticodeFile="PANOPTICODE_FILE"
                 checkstyleFile="CHECKSTYLE_XML_FILE" />

CKJM Supplement

Usage:

<taskdef name="mergeCKJM"
         classpath="PATH_TO_PANOPTICODE_JAR"
         classname="org.panopticode.supplement.ant.CKJMPanopticode">
</taskdef>

<mergeCKJM panopticodeFile="PANOPTICODE_FILE"
           ckjmFile="CKJM_XML_FILE" />

Complexian Supplement

Usage:

<taskdef name="mergeComplexian"
         classpath="PATH_TO_PANOPTICODE_JAR"
         classname="org.panopticode.supplement.ant.ComplexianPanopticode">
</taskdef>

<mergeComplexian panopticodeFile="PANOPTICODE_FILE"
                 complexianNPathFile="COMPLEXIAN_NPATH_XML_FILE" />

Emma Supplement

Usage:

<taskdef name="mergeEmma"
         classpath="PATH_TO_PANOPTICODE_JAR"
         classname="org.panopticode.supplement.ant.EmmaPanopticode">
</taskdef>

<mergeEmma panopticodeFile="PANOPTICODE_FILE"
           emmaFile="EMMA_XML_FILE" />

JavaNCSS Supplement

Usage:

<taskdef name="mergeJavaNCSS"
         classpath="PATH_TO_PANOPTICODE_JAR"
         classname="org.panopticode.supplement.ant.JavaNCSSPanopticode">
</taskdef>

<mergeJavaNCSS panopticodeFile="PANOPTICODE_FILE"
               javancssFile="JAVANCSS_XML_FILE" />

JDepend Supplement

Usage:

<taskdef name="mergeJDepend"
         classpath="PATH_TO_PANOPTICODE_JAR"
         classname="org.panopticode.supplement.ant.JDependPanopticode">
</taskdef>

<mergeJDepend panopticodeFile="PANOPTICODE_FILE"
              jdependFile="JDEPEND_XML_FILE" />

Generate Reports and Visualizations

Panopticode generates reports in SVG format. While not as popular as some other image formats SVG has several advantages including:

Panopticode supports treemap reports of complexity and code coverage in both static and interactive styles. The static styles make full use of the display area given to them for the treemap. The interactive styles reserve a portion of the display area for showing the detailed metrics for whatever is clicked on in the treemap.

To view these reports you must have a SVG viewer installed. For those users who do not have an SVG viewer Panopticode distributes the Batik project to support converting these reports into TIFF, JPEG, or PNG format.

What is a Treemap?

In his article, "Discovering Business Intelligence Using Treemap Visualizations," Ben Shneiderman explains that "Treemaps are a space-filling approach to showing hierarchies in which the rectangular screen space is divided into regions, and then each region is divided again for each level in the hierarchy."

Software projects have a natural hierarchy. In the case of Java we have project -> package -> file -> class -> method -> statement.

To really understand treemaps we recommend examining several of them. You can find some in the Panopticode Gallery.

In a future release report generation will be done with a full-fledged ant task. Until then, we recommend using the following macrodef:

<macrodef name="report">
   <attribute name="reportClass" />
   <attribute name="panopticodeXmlFile" />
   <attribute name="outputFile" />
   <attribute name="interactive" default="" />
   <sequential>
      <java classpath="PATH_TO_PANOPTICODE_JAR"
            classname="org.panopticode.ReportRunner"
            fork="true" />
         <arg value="@{reportClass}" />
         <arg value="@{panopticodeXmlFile}" />
         <arg value="@{outputFile}" />
         <arg value="@{interactive}" />
      </java>
   </sequential>
</macrodef>

Complexity Treemap

Panopticode's complexity treemap reports uses NCSS (Non-Comment Source Statements) to determine the size of each region and CCN (Cyclomatic Complexity) to determine how each region, which maps to a method, is filled. Method regions with low complexity are green all the way to those with very high complexity which are black.

Interactive

The interactive treemap allows users to click on a region and see all metrics associated with that method and its parent class, file, package, and project.

<report reportClass="org.panopticode.report.treemap.CCNComplexityTreemap"
        panopticodeXmlFile="PANOPTICODE_FILE"
        outputFile="OUTPUT_FILE"
        interactive="-interactive" />

Static

The static treemap uses all available space for rendering the visualization. This is especially useful when the report will be transcoded into another file format where the interactive features will be lost.

<report reportClass="org.panopticode.report.treemap.CCNComplexityTreemap"
        panopticodeXmlFile="PANOPTICODE_FILE"
        outputFile="OUTPUT_FILE" />

Coverage Treemap

Panopticode's coverage treemap reports uses NCSS (Non-Comment Source Statements) to determine the size of each region and line coverage to determine how each region, which maps to a method, is filled. Method regions with low coverage are black all the way to those with high coverage which are green.

Interactive

The interactive treemap allows users to click on a region and see all metrics associated with that method and its parent class, file, package, and project.

<report reportClass="org.panopticode.report.treemap.CoverageTreemap"
        panopticodeXmlFile="PANOPTICODE_FILE"
        outputFile="OUTPUT_FILE"
        interactive="-interactive" />

Static

The static treemap uses all available space for rendering the visualization. This is especially useful when the report will be transcoded into another file format where the interactive features will be lost.

<report reportClass="org.panopticode.report.treemap.CoverageTreemap"
        panopticodeXmlFile="PANOPTICODE_FILE"
        outputFile="OUTPUT_FILE" />

Example

See build-example.xml inside the panopticode directory for an example of how it all comes together.