Documentation
Usage
Command Line
After you have installed it, you can use it like any other
command. Be aware that the command line jcsc tool can not be
used to scan a whole folder recursively; for that you have to use the
JCSC Ant task. If you use the -r flag, JCSC looks first into
the JCSC_HOME/rules folder, if it is not found there it tries to find
it
using the absolute path.
jcsc
[option] <file>|stream
Replace jcsc with
either jcsc.bat or jcsc.sh depending on your
platform
with the option being:
-h : show the help
-r <rule> :the rule file is read from the file system
-j <rule> :the rule file is read from the jcsc.jar file
Example Output
$ jcsc -r jcsc.jcsc.xml
JCSCTask.java
Violations:
JCSCTask.java:55:100:line is too long 0..80 characters are
allowed:LineLength:3
JCSCTask.java:56:92:line is too long 0..80 characters are
allowed:LineLength:3
JCSCTask.java:147:50:conditional expression (?:) are not
allowed:ConditionalExpression:3
JCSCTask.java:158:55:conditional expression (?:) are not
allowed:ConditionalExpression:3
JCSCTask.java:169:56:conditional expression (?:) are not
allowed:ConditionalExpression:3
JCSCTask.java:262:86:line is too long 0..80 characters are
allowed:LineLength:3
JCSCTask.java:290:81:line is too long 0..80 characters are
allowed:LineLength:3
JCSCTask.java:334:91:line is too long 0..80 characters are
allowed:LineLength:3
JCSCTask.java:218:empty
catch block, this is normally an error:EmptyCatchBlock:3
JCSCTask.java:225:empty finally block, this is
normally an error:EmptyFinallyBlock:3
JCSCTask.java:229:method return 'boolean' and
starts with 'get' it should start with 'is' or
'has':RegExpPrefixForMethodReturningboolen:3
JCSCTask.java:231:A space after statement keyword
'while' is mandatory:SpaceAfterStatementKeywoard:3
JCSCTask.java:231:statement following 'while' is
not in '{' ... '}' which is source of many
errors:BraceAroundSingleLineStatement:3
JCSCTask.java:340:96:line
is too long 0..80 characters are allowed:LineLength:3
JCSCTask.java:346:91:line is too long 0..80 characters are
allowed:LineLength:3
[...]
JCSCTask.java:1070:15:conditional expression (?:) are not
allowed:ConditionalExpression:3
JCSCTask.java:1077:15:conditional expression (?:) are not
allowed:ConditionalExpression:3
46 violation(s) found
Metrics:
84:37:JCSCTask.setRules():NCSS-2:CCN-1
94:35:JCSCTask.setFile():NCSS-4:CCN-1
107:51:JCSCTask.setStartpackage():NCSS-4:CCN-2
122:59:JCSCTask.setResultsformatter():NCSS-2:CCN-1
133:37:JCSCTask.setDestdir():NCSS-3:CCN-1
145:39:JCSCTask.setWorstCount():NCSS-2:CCN-1
156:40:JCSCTask.setStartDate():NCSS-2:CCN-1
167:41:JCSCTask.setFailValue():NCSS-2:CCN-1
176:37:JCSCTask.addFileSet():NCSS-3:CCN-1
187:30:JCSCTask.getFiles():NCSS-18:CCN-5
228:24:JCSCTask.execute():NCSS-7:CCN-2
244:40:JCSCTask.getFile():NCSS-5:CCN-3
257:43:JCSCTask.checkForTooManyViolations():NCSS-3:CCN-3
267:32:JCSCTask.parameterCheck():NCSS-23:CCN-10
327:37:JCSCTask.batchParameterCheck():NCSS-13:CCN-4
354:53:JCSCTask.throwExceptionIfError():NCSS-3:CCN-3
368:40:JCSCTask.executeFile():NCSS-6:CCN-3
391:44:JCSCTask.executeFiles():NCSS-7:CCN-2
409:49:JCSCTask.parseSingleFileFromBatch():NCSS-11:CCN-3
435:53:JCSCTask.convertAuthors2String():NCSS-8:CCN-3
458:40:JCSCTask.parseSingleFile():NCSS-10:CCN-2
483:33:JCSCTask.isFileSetSet():NCSS-2:CCN-1
495:42:JCSCTask.isResultsFormatterSet():NCSS-2:CCN-1
506:38:JCSCTask.isStartPackageSet():NCSS-2:CCN-1
518:33:JCSCTask.isDestDirSet():NCSS-2:CCN-1
529:35:JCSCTask.isStartDateSet():NCSS-2:CCN-1
540:35:JCSCTask.isFailValueSet():NCSS-2:CCN-1
545:51:JCSCTask.createResultsFormatter():NCSS-9:CCN-3
568:25:JCSCTask.getRules():NCSS-10:CCN-3
599:48:JCSCTask.getOutputFileName():NCSS-8:CCN-1
619:45:JCSCTask.getPackageName():NCSS-7:CCN-1
638:43:JCSCTask.getClassName():NCSS-5:CCN-1
647:34:JCSCTask.convertDate2Long():NCSS-13:CCN-1
670:26:JCSCTask.getPackageMap():NCSS-2:CCN-1
682:50:JCSCTask.add2PackageMap():NCSS-19:CCN-2
720:66:JCSCTask.add2IndexMap():NCSS-9:CCN-2
745:76:JCSCTask.add2ViolationsMap():NCSS-2:CCN-1
755:52:JCSCTask.writeConsoleOverview():NCSS-10:CCN-1
838:55:JCSCTask.Comparator.compare():NCSS-4:CCN-1
775:26:JCSCTask.writeXML():NCSS-56:CCN-5
873:41:JCSCTask.writePackageOverviewXml():NCSS-23:CCN-3
919:34:JCSCTask.writeOverviewXml():NCSS-21:CCN-2
953:68:JCSCTask.writeWorstClassesXml():NCSS-10:CCN-2
971:32:JCSCTask.getPackageCount():NCSS-2:CCN-1
976:30:JCSCTask.getClassCount():NCSS-7:CCN-2
991:31:JCSCTask.getMethodCount():NCSS-7:CCN-2
1006:34:JCSCTask.getViolationCount():NCSS-7:CCN-2
1021:29:JCSCTask.getNCSSCount():NCSS-7:CCN-2
1036:38:JCSCTask.getUnitTestClassCount():NCSS-7:CCN-2
1051:33:JCSCTask.getUnitTestCount():NCSS-7:CCN-2
1066:49:JCSCTask.calculateAvgViolationsPerNcss():NCSS-2:CCN-1
1073:50:JCSCTask.calculateAvgViolationsPerClass():NCSS-2:CCN-1
Total NCSS count : 449
Total Methods count : 52
Unit Test Class count : 0
Unit Tests count : 0
Rules Editor
Just run the ruleseditor script in the JCSC_HOME/bin folder.
Per default you read the default settings which are stored in the
jar file. You can modify these and save them into a file. Also you can
open an existing file, either from within the UI or by passing the
rules
file name as an argument.
Ant
If you are familar with Ant then read this. Otherwise checkout the Ant
website at http://jakarta.apache.org/ant/
Example Output
See example 2 from the 'this'
link above.
$ ant -buildfile jcsc.xml all
/cygdrive/e/jakarta-ant-1.5/lib/xml-apis.jar:/cygdrive/e/jakarta-ant-1.5/lib/xercesImpl.jar:/cygdriv
e/e/jakarta-ant-1.5/lib/optional.jar:/cygdrive/e/jakarta-ant-1.5/lib/gnu-regexp.jar:/cygdrive/e/jaka
rta-ant-1.5/lib/ant.jar:/cygdrive/e/jakarta-ant-1.5/lib/JCSC.jar:/cygdrive/e/jaxp-1.1/jaxp.jar:/cygd
rive/e/jaxp-1.1/crimson.jar:/cygdrive/e/jaxp-1.1/xalan.ja:/cygdrive/e/jakarta-ant/lib/ant.jar:/cygdr
ive/e/jakarta-ant/lib/jakarta-ant-1.4.1-optional.jar:/cygdrive/c/java/jdk1.3/lib/tools.jar
e:\jakarta-ant-1.5\lib\xml-apis.jar;e:\jakarta-ant-1.5\lib\xercesImpl.jar;e:\jakarta-ant-1.5\lib\opt
ional.jar;e:\jakarta-ant-1.5\lib\gnu-regexp.jar;e:\jakarta-ant-1.5\lib\ant.jar;e:\jakarta-ant-1.5\li
b\JCSC.jar;e:\jaxp-1.1\jaxp.jar;e:\jaxp-1.1\crimson.jar;e:\jaxp-1.1\xalan.ja;e:\jakarta-ant\lib\ant.
jar;e:\jakarta-ant\lib\jakarta-ant-1.4.1-optional.jar
Buildfile: jcsc.xml
all:
[jcsc] Package
Count:
10
[jcsc] Class
Count:
26
[jcsc] Methods
Count:
281
[jcsc] Total Violations Count : 153
[jcsc] Avg Violations per Class: 5.8846154
[jcsc] Total NCSS
Count: 3430
[jcsc] Avg Violations per NCSS:
0.044606414
[jcsc] Unit Test Class
Count: 2
[jcsc] Unit Tests
Count: 83
BUILD SUCCESSFUL
The resulting XML files can be found in the folder specified by the Ant
task. The XML can be viewed via XSL compliant browsers.Tested with
Mozilla 1+ and IE6. IE needs to have the SP1 in order to work
correctly. If you have problems and not IE SP1 then open your IE
browser and choose Tools->Windows Update from the menu.
The
web page guides you how to do the update.
Metrics
NCSS is an acronym for Non Commenting Source
Statements. This number represents pure functionality code lines in a
source file. Comparing this number and the violations count, the
quality
can be eassier assest. (for more informations on this topic go here)
CCN is an acronym for Cyclomatic Complexity Number.
This number indicates the number in how many branches the flow is split.
Each method has a CCN of 1 per default. (for more information on this
topic go here)
Rules
The rules for checking a stored in a XML file. This XML
is easy to read:
01 <jcsc version="__0.95__" date="2003-06-18 09:01:13">
02 <rules>
03 <rule name="CFProRegExp" category="Field" enabled="true">
04
<type>regexp</type>
05
<value>s[A-Z0-9][\w\d]*</value>
06
<severity>3</severity>
07 </rule>
08 <rule name="NestedTypeBlockPlaceRule"
category="General" enabled="true">
09
<type>multichoice</type>
10
<choices>
11
<choice>Beginning of Class</choice>
12
<choice>End of Class</choice>
13
</choices>
14
<value>End of Class</value>
15
<severity>3</severity>
16 </rule>
17
...
18 </rules>
19 </jcsc>
Line 01: start of the JCSC rules file showing the version of
JCSC and the timestamp when it was saved for the last time
Line 02: starting of the rules block
Line 03: start of a rule showing the name (maps to the key on the
Ruleseditor UI) the category it belongs to and whether it is
enabled
Line 04: shows the type; in this case a regular expression
Line 05: shows the value of the specified type
Line 06: shows the severity; each rule can have a severity from 1-5
with 1=lowest and 5=highest
Line 07: end of rule
Line 08: start of a rule
Line 09: show the type; in this case multichoice (ie combo box) this
rule requires a block of choices
Line 10: start of choices block
Line 11: choice
Line 12: choice
Line 13: end of choices block
Line 14: shows the value which has to be on of the choices block
Line 15: shows the severity
Line 16: end of rule
Line 17: more rules
Line 18: end of rules block
Line 19: end of JCSC rules file
Allowed types (Lines 04,09)
are:
- regexp: value is a
regexp string
- regexp-multinline:
value is a regexp string spanning several lines
- integer: value is a
integer number
- boolean: values are
either true or false
- multichoice: value
is on of the choices
You can place your own rules into the jcsc.jar
file and access them with the -j
option.
Update
General
There are multiple ways to update you current JCSC installation, here
is one:
- rename the JCSC folder to which JCSC_HOME
points to oldJCSC
- download the latest version
- expand it to the location JCSC_HOME is pointing
- move custom files from oldJCSC to JCSC
- backup or delete oldJCSC folder
Rules File
0.97 to 0.98
One rule 'ApplyJavaDocRulesInnerClass'
has been added. Open your existing rules files (*.jcsc.xml), define the new
rule in the JavaDoc tab and save it. This adds the new rule to the
rules XML file.
0.96 to 0.97
No changes to the rules file.
0.95 to 0.96
The <priority>/</priority>
tag has been renamed to <severity>
ie. </severity>. In
your rules XML files replace all occurences of <priority> with <severity> and </priority> with </severity>.
0.94 to 0.95
In the JCSC_HOME/bin folder is a convert
script. Run this to convert the .jcsc
properties file into a .jcsc.xml
file.
Usage for Win: convert.bat
<old>.jcsc
Usage for Nix: convert.sh
<old>.jcsc
A <old>.jcsc.xml usable for JCSC
0.95will be created
0.93 to 0.94
Open the existing one and set the new rules and save them.
0.92 to 0.93
The best thing to do is the following:
- Diff (with any diff program) the old JCSC_HOME/rules/jcsc.jcsc
file with the new one (i.e version 0.92 with 0.93); this gives you an
overview about what rules have been added and which have been moved or
modified.
- Using this knowledge you then can modify your own .jcsc
file.
- Sorry for this painfull process -- a migration tool would
be nice ;)
Last updated on
2005-07-01 18::12
|
JCSC
