JavancssAntTask.html

<html>

<head>
    <meta http-equiv="Content-Language" content="en-us">
    <title>JavaNCSS Ant Task User Manual</title>
</head>

<body>
    <h2><a name="javancss">JavaNCSS Ant Task</a></h2>
    <h3>Description</h3>

    <p>Checks some basic code metrics and generates a report.

    <p>This task wraps the JavaNCSS library for determining code metrics. The
    library determines several code metrics such as class counts, non-commented
    source statements (NCSS), cyclomatic complexity numbers (CCN), and javadoc
    statements. These counts are subtotaled per function, class, and package.

    <p>This task can generate a report (in plain text or XML format) and allows
    you to place minimum and maximum thresholds on each metric. All metrics
    are included for completeness, however some will be more useful than others.

    <p>Note on use: Several empirical studies have shown that more complexity
    leads to more defects. The metrics calculated by this task can be used to
    focus review and indicate opportunities for refactoring. Such a proactive
    approach to development will increase quality through design improvements,
    easier testing, and reduction of defects.

    <p>The ant verbose option will cause information on each object checked to
    be displayed.  The default package is indicated by a "." in messages.

    <p>The set of files to be adjusted can be refined with the
    <i>includes</i>, <i>includesfile</i>, <i>excludes</i>,
    <i>excludesfile</i> and <i>defaultexcludes</i>
    attributes. Patterns provided through the <i>includes</i> or
    <i>includesfile</i> attributes specify files to be
    included. Patterns provided through the <i>exclude</i> or
    <i>excludesfile</i> attribute specify files to be
    excluded. Additionally, default exclusions can be specified with
    the <i>defaultexcludes</i> attribute. See the section on directory based
    tasks for details of file inclusion/exclusion patterns and their usage.

    <p>This task forms an implicit FileSet
    and supports all attributes of <code>&lt;fileset&gt;</code>
    (<code>dir</code> becomes <code>srcdir</code>) as well as the nested
    <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and
    <code>&lt;patternset&gt;</code> elements.</p>

    <p>This Ant task for JavaNCSS has been written by <i><a href="mailto:sjernigan@iname.com">Steve Jernigan</a></i> with support from
    <i><a href="mailto:Phillip.Wells@DRKW.com">Phillip Wells</a></i> and
    is located at SourceForge: <a href="http://sourceforge.net/projects/javancss2ant/">http://sourceforge.net/projects/javancss2ant/</a>.<br>
    The home page of JavaNCSS is located at: <a href="http://www.kclee.de/clemens/java/javancss/">http://www.kclee.de/clemens/java/javancss/</a>.

    <h3>Parameters</h3>
    <p>There are three kinds of parameter: those related to report generation,
    those related to threshold checking and those common to both.

    <p><b>Common parameters</b></p>
    <table border="1" cellpadding="2" cellspacing="0">
        <tr>
            <td valign="top"><b>Attribute</b></td>
            <td valign="top"><b>Description</b></td>
            <td align="center" valign="top"><b>Required</b></td>
        </tr>
        <tr>
            <td valign="top">srcdir</td>
            <td valign="top">The location of the Java source files to be
            analysed.</td>
            <td valign="top" align="center">Yes</td>
        </tr>
        <tr>
            <td valign="top">includes</td>
            <td valign="top">comma separated list of patterns of files that must
            be included. All files are included when omitted.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">includesfile</td>
            <td valign="top">the name of a file. Each line of this file is
            taken to be an include pattern</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">excludes</td>
            <td valign="top">comma separated list of patterns of files that must
            be excluded. No files (except default excludes) are excluded when
            omitted.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">excludesfile</td>
            <td valign="top">the name of a file. Each line of this file is
            taken to be an exclude pattern</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">defaultexcludes</td>
            <td valign="top">indicates whether default excludes should be used
            or not (&quot;yes&quot;/&quot;no&quot;). Default excludes are used
            when omitted.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">abortOnFail</td>
            <td valign="top">If true, the build will be terminated if a threshold
            is exceeded. If false, only a warning message is printed. Default is
            false.</td>
            <td valign="top" align="center">No</td>
        </tr>
    </table>

    <p><b>Report generation parameters</b></p>
    <table border="1" cellpadding="2" cellspacing="0">
        <tr>
            <td valign="top"><b>Attribute</b></td>
            <td valign="top"><b>Description</b></td>
            <td align="center" valign="top"><b>Required</b></td>
        </tr>
        <tr>
            <td valign="top">generateReport</td>
            <td valign="top">Whether a report should be generated. Default is
            false. When set to true, the report will be created in the location
            specified by 'outputfile', or to the standard output if this parameter
            is not set.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">outputfile</td>
            <td valign="top">The fully-specified path of the report to be created
            by this task. If omitted and 'generateReport' is set to 'true' the
            report will be sent to the standard output.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">format</td>
            <td valign="top">The format of the report. Allowable values are
            'plain' and 'xml'. 'plain' is the default.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">packageMetrics</td>
            <td valign="top">Whether metrics data for each package should be
            included in the report . Default is true.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">classMetrics</td>
            <td valign="top">Whether metrics data for each class/interface should
            be included in the report . Default is true.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">functionMetrics</td>
            <td valign="top">Whether metrics data for each function should be
            included in the report . Default is true.</td>
            <td valign="top" align="center">No</td>
        </tr>
    </table>

    <p><b>Threshold checking parameters</b></p>
    <table border="1" cellpadding="2" cellspacing="0">
        <tr>
            <td valign="top"><b>Attribute</b></td>
            <td valign="top"><b>Description</b></td>
            <td align="center" valign="top"><b>Required</b></td>
        </tr>
        <tr>
            <td valign="top">classPerPkgMax</td>
            <td valign="top">Set the maximum threshold for the classs per package
            metric. This is an integer option.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">classPerPkgMin</td>
            <td valign="top">Set the minimum threshold for the classes per package
            metric. This is an integer option.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">ncssPerPkgMax</td>
            <td valign="top">Set the maximum threshold for the NCSS per package
            metric. This is an integer option.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">ncssPerPkgMin</td>
            <td valign="top">Set the minimum threshold for the NCSS per package
            metric. This is an integer option.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">funcPerPkgMax</td>
            <td valign="top">Set the maximum threshold for the functions per
            package metric. This is an integer option.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">funcPerPkgMin</td>
            <td valign="top">Set the minimum threshold for the functions per
            package metric. This is an integer option.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">classPerClassMax</td>
            <td valign="top">Set the maximum threshold for the inner classes per
            class metric. This is an integer option.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">classPerClassMin</td>
            <td valign="top">Set the minimum threshold for the inner classes per
            class metric. This is an integer option.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">funcPerClassMax</td>
            <td valign="top">Set the maximum threshold for the functions per
            class metric. This is an integer option.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">funcPerClassMin</td>
            <td valign="top">Set the minimum threshold for the functions per
            class metric. This is an integer option.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">ncssPerClassMax</td>
            <td valign="top">Set the maximum threshold for the NCSS per class
            metric. This is an integer option.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">ncssPerClassMin</td>
            <td valign="top">Set the minimum threshold for the NCSS per class
            metric. This is an integer option.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">jvdcPerClassMax</td>
            <td valign="top">Set the maximum threshold for the javadoc statements
            per class metric. This is an integer option.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">jvdcPerClassMin</td>
            <td valign="top">Set the minimum threshold for the javadoc statements
            per class metric. This is an integer option.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">jvdcPerFuncMax</td>
            <td valign="top">Set the maximum threshold for the javadoc statements
            per function metric. This is an integer option.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">jvdcPerFuncMin</td>
            <td valign="top">Set the minimum threshold for the javadoc statements
            per function metric. This is an integer option.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">ccnPerFuncMax</td>
            <td valign="top">Set the maximum threshold for the CCN per function
            metric. This is an integer option.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">ccnPerFuncMin</td>
            <td valign="top">Set the minimum threshold for the CNN per function
            metric. This is an integer option.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">ncssPerFuncMax</td>
            <td valign="top">Set the maximum threshold for the NCSS per function
            metric. This is an integer option.</td>
            <td valign="top" align="center">No</td>
        </tr>
        <tr>
            <td valign="top">ncssPerFuncMin</td>
            <td valign="top">Set the minimum threshold for the NCSS per function
            metric. This is an integer option.</td>
            <td valign="top" align="center">No</td>
        </tr>
    </table>

    <h3>Examples</h3>
    <pre>   &lt;taskdef name="javancss"
            classname="javancss.JavancssAntTask"
            classpath="${CLASSPATH}"/&gt;

   &lt;javancss srcdir=&quot;${build.src}&quot;
            abortOnFail=&quot;false&quot; ccnPerFuncMax=&quot;10&quot;
            includes=&quot;**/*.java&quot;/&gt;
    </pre>

    <p>Checks for functions with a greater than 10 CCN from
    the java source files and prints a warning message for each
    instance. Even if a function exceeds the threshold, the
    build is allowed to continue.
    </p>

    <pre>   &lt;taskdef name="javancss"
            classname="javancss.JavancssAntTask"
            classpath="${CLASSPATH}"/&gt;

   &lt;javancss srcdir=&quot;${build.src}&quot;
            generateReport=&quot;true&quot;
            outputfile=&quot;${test.results.root}/javancss_metrics.xml&quot;
            format=&quot;xml&quot;/&gt;
    </pre>

    <p>Creates an XML-format report called javancss_metrics.xml in the directory
    specified by <code>${test.results.root}</code> on all source files in the
    directory specified by <code>${build.src}</code>. No thresholds are checked.
    </p>

    <hr><p align="center">Copyright &copy; 2001-2002 Steve Jernigan &lt;sjernigan@iname.com&gt;, distributed under the GNU General Public License (GPL).</p></body>
</html>