## JCSC

### Description

Parses one file (single file mode) or a whole package tree of java files (batch mode) using Fileset with the JCSC (Java Coding Standard Checker). .
When run in batch mode the result can be viewed with a browser(tested with IE6+ with SP1 and Mozilla1+). The L&F is similar to that of JavaDoc. Start the`index.html` in the `destdir`.

### Installation

Since JCSC uses the GPL it is/will not be distributed with Ant. Place the JCSC.jar and gnu-regexp.jar (V 1.1.4+) in the ANT_HOM/lib folder and add this line to your build.xml file. JCSCTask requires Ant 1.5+.

> `<taskdef name="jcsc" classname="rj.tools.jcsc.ant.JCSCTask"/>
> `

If you want to view the resulting XML files with a browser, you need to set the <copyassociatedfiles> to yes.

### Parameters

Attribute | Description | Required
file | the file to be parsed; fully qualified path | Yes, when in single file mode.
rules | Specifies the rules files being used; fully qualified path | No, otherwise default.jcsc is used
destdir | The folder where to place the results; fully qualified path | Yes, when in batch mode
worstcount | The generated XML shows a list of the worst classes. The x classes which do have the most violations; integer The default is 15. | No, a value of '-1' keeps the default
resultsformatter | The formatter which prints out the results. There are 2 formatters available: rj.tools.jcsc.XMLResultsformatter - default for batch mode rj.tools.jcsc.ConsoleResultsformatter - default for single file mode | No
violationssorter | Ther sorter for sorting the violations. There are 3 formatter available rj.tools.jcsc.sorter.OccurenceSorter - default rj.tools.jcsc.sorter.RulekeySorter rj.tools.jcsc.sorter.SeveritySorter | No
startdate | Only files which are newer then startdate are parsed; String Format YYYY-MM-DD HH:MM:SS | No, a value of "" means not set
failvalue | If the violations/NCSS gets higher or equals then build fails; double | No, a value of "" means not set
failseverity | If found violations severity is higher or equals then the build fails; integer | No, a value of "" means not set
failproperty | When this attribute is set, JCSC will not cause a 'Build Failed' condition but create a property with the name of the failproperty value and set it to true; String | No; a value of "" means not set
ignoretestseverity | Ignores violations in Unit-Test classes having a lower or equalt then ignoretestseverity; integer | No, a value of "" not set
copyassociatedfiles | copy the associated files (example html, XSL, index.html) to the <destdir>; boolean | No, only used when in batch mode
jcschome | The home folder if the JCSC installation. | Yes, if copyassociatedfiles is set

### Parameters specified as nested elements

#### fileset

FileSets are used to get the list of java files from a whole java source package tree for batch processing.

### Examples

Example 1

    <target name="one">
      <jcsc file="c:/cygwin/home/jcsc/src/rj/tools/jcsc/ui/RulesPanel.java"
            resultsformatter="rj.tools.jcsc.formatter.XMLResultsFormatter"/>
    </target>

Parses the RulesPanel.java file and shows the result in XML format using the `default.jcsc` rules.

Example 2

    ...
    <!-- read the environment variables into env property -->
    <property environment="env"/>
    ...

    <target name="all">
      <jcsc rules="c:/cygwin/home/jcsc/rules/company.jcsc"
            destdir="c:/results/jcsc/"
            worstcount="20"
    	startdate="2003-01-01 00:00:00"
            failvalue="0.05"
            failseverity="5"
            copyassociatedfiles="true"
            jcschome=${env.JCSC_HOME}>
        <fileset dir="L:/java/src"
                 includes="**/*.java"/>
      </jcsc>
    </target>

Parses a whole package tree in batch mode. company.jcsc is used as rules. The resulting XML, XSL and HTML files are put into `c:/results/jcsc`. The worst 20 classes are displayed on the web page. The files are all `.java` files starting at `L:/java/src`. Only files which have been created after Jan 1st 2003 midnight are considered. If the violations/NCSS ratio is higher then 0.05 (1 violations per 20 NCSS) or a violation of severity '5' has been found, the build fails.

Example 3

    ...
    <!-- read the environment variables into env property -->
    <property environment="env"/>
    ...

    <target name="all">
      <jcsc rules="c:/cygwin/home/jcsc/rules/company.jcsc"
            destdir="c:/results/jcsc/"
            worstcount="10"
    	violationssorter="rj.tools.jcsc.sorter.SeveritySorter"
    	ignoretestseverity="4"
            jcschome=${env.JCSC_HOME}>
        <fileset dir="L:/java/src"
                 includes="**/*.java"/>
      </jcsc>
    </target>

Parses a whole package tree in batch mode. company.jcsc is used as rules. The resulting XML, XSL and HTML files are put into `c:/results/jcsc`. The worst 10 classes are displayed on the web page. The files are all `.java` files starting at `L:/java/src`. The found violations are sorted by severity and violations with a severity of 4 or less are ignored in Unit-Test classes.

Example 4

    ...
    <!-- read the environment variables into env property -->
    <property environment="env"/>
    ...

    <target name="jcsc.run">
      <jcsc rules="c:/cygwin/home/jcsc/rules/company.jcsc"
            destdir="c:/results/jcsc/"
            worstcount="20"
    	startdate="2003-01-01 00:00:00"
            failvalue="0.05"
            failseverity="5"
            failproperty="jcsc.failed"
            copyassociatedfiles="true"
            jcschome=${env.JCSC_HOME}>
        <fileset dir="L:/java/src"
                 includes="**/*.java"/>
      </jcsc>

      <!-- here you could execute further steps; which will always be executed -->

    </target>

    <target name="jcsc.test"
            depends="jcsc.run"
            description="runs JCSC and tests if it failed">
        <fail if="${jcsc.failed}"
              message="JCSC failed -- VIO/NCSS ratio too high (max. 0.05)"/>
    </target>

This example is copied from Example 2, however it has one addtional attribute failproperty. In case that the JCSC should fail because of either failvalue or failseverity the build will not fail immediately. A property jcsc.failed is created with value true. This property can be used to make decissions about further actions. Using the examples above, jcsc.run will never fail but jcsc.test will if the failproperty was set -- that way you can between running JCSC and failing execute additional steps.

### Note:

It is recommended to only use the XMLResultsformatter when working in batch mode.

Copyright © 1999-2004 Ralph Jocham