codepro.audit
This function is deprecated and has
been replaced by the
instantiations.audit
Ant Task in
CodePro AnalytiX Server
.
Description
An Ant task that performs a code audit. This is identical to the
Audit Code command available via the
Application Developer and Eclipse IDE user interfaces. This can be run
inside the Eclipse IDE or as a headless audit
with project defaults.
Attributes
The following is a list of the attributes supported for the
codepro.audit task.
Attribute |
Description |
Required |
classpath |
The classpath used for resources that exist outside of the projects
contained by the current Eclipse workspace. The classpath attribute is
a path-like
structure and can also be set via a nested
<classpath> element similar to the classpath
attribute in the
javac
Ant task.
Note: The classpath attribute relies on functionality that
exists in Eclipse 2.1, but not in Eclipse 2.0 / Application
Developer 5.0. If you want to use this, you will have to download and
install Eclipse 2.1. See the notes on the
Eclipse headless Ant environment.
|
No |
auditRuleSetName |
The name of the
audit
rule set that will be used to generate audit violations. If the
auditRuleSetFile attribute is specified (see below) then
the named audit rule set in the specified file is used, otherwise the
named audit rule set in the workspace is used. If no audit rule set
name is specified then either the first audit rule set in the file or
the default audit rule set in the workspace is used depending upon
whether or not the auditRuleSetFile attribute is specified.
|
No |
auditRuleSetFile |
The absolute or relative path to the file that contains the
audit
rule set to be used. If the auditRuleSetName attribute
is specified (see above) then the audit rule set located in the
specified file with the specified name is used, otherwise the first
audit rule set in the file is used. If the auditRuleSetFile
attribute is not specified, then an audit rule set from the workspace
is used. Either the export
preferences command or the
export
button on the audit preference page can be used to generate a file
containing audit rule sets.
|
No |
storageLocation |
A designation of the storage location in which the audit result set
will be stored. It can be either workspace (the default)
or project: followed by the name of a project.
|
No, default is workspace |
violationCountThreshold |
The maximum number of violations that can be found by the audit before the
audit is considered to fail, as well as the list of severities that are
included in the count. These values are described by an expression composed
of a "+" separated list of severity names ("high", "medium" and "low") and
an integer threshold value, with the list being separated from the threshold
by a greater than (">"). For example, if the audit should fail if
more than 200 high or medium level violations are found, the attribute
would be specified as:
violationCountThreshold="high+medium>200"
If not specified then the audit will not fail.
|
No |
resultProperty |
The base name used to compose the names of properties that will be given
values after an audit has been run. The following is a list of the
properties that will be set (where "result" is assumed to be the value of
this property):
result.exceededThreshold
"true" if the threshold specified by the
violationCountThreshold attribute is exceeded. The property
will not be set if the threshold is not exceeded or if the threshold is
not set.
result.resourceCount.total
- The number of resources that were audited.
result.violationCount.high
- The total number of high severity violations.
result.violationCount.low
- The total number of low severity violations.
result.violationCount.medium
- The total number of medium severity violations.
result.violationCount.total
- The total number of violations.
|
No |
deleteTempProject |
This attribute exists for debugging purposes only. If a
classpath attribute is specified, then the
codepro.audit ant task creates a temporary project for use
during the audit process, and deletes that project after the audit is
complete. If this attribute is set to "false"
then the temporary project will not be deleted.
|
No, default is true |
Deprecated Attributes
The following attributes are deprecated in favor of more flexible
mechanisms. While they are still currently supported, they should be
replaced by the newer mechanisms, as described for each attribute.
Attribute |
Description |
Required |
resultFile |
Deprecated: use the nested report element instead
The absolute or relative path to the file to which audit results will be
written. If not specified, then no audit results will be written to any
file. Regardless of whether or not the resultFile attribute
is specified, if the ant task is being executed inside the IDE user
interface, then the audit results will be available from the
Audit view.
|
No |
resultFormat |
Deprecated: use the nested report element instead
The format in which the audit results will be written. If not specified,
then the results will be written in a simple text format. Currently
supported formats include:
commaSeparatedData
csvSummary
html
tabSeparatedData
text
xml
|
No, default is text |
groupBy |
Deprecated: use the nested report element instead
The way in which the audit violations are grouped in the result file. If
not specified, then the results will be grouped by audit rule .
Currently supported groupings include:
audit rule
audit rule group
author
resource
severity
|
No, default is audit rule |
reportFilter |
Deprecated: use the nested report element instead
The filter used to restrict which violations are included in the report
that is generated. Only those violations whose severity level is included
in the given list will be included in the generated report. This attribute
is ignored if the report file is not specified. If this attribute is not
specified, all severities of violations will be included in the report
(assuming a report is generated).
|
No |
violationCountProperty |
Deprecated: use the resultProperty attribute instead
The base name used to compose the names of properties that will be set to
the total number of violations and to the number of violations of each
severity level by appending a period and the name of the severity level
(or "total" for the total number of violations) to the base name.
For example, if the property name were vCount and there were 4
high, 6 medium, and 10 low severity violations, the property named
vCount.total would be set to 20, and the properties named
vCount.high , vCount.medium , and
vCount.low ; would be set to 4, 6, and 10, respectively. If
not specified then no properties will be set to these values.
|
No |
exceededThresholdProperty |
Deprecated: use the resultProperty attribute instead
The name of the property that will be set to
"true" if the threshold specified by the
violationCountThreshold attribute is exceeded. The
property will not be set if the threshold is not exceeded. This
attribute is ignored if the threshold is not set. If this attribute is
not specified, but the violationCountThreshold attribute
is specified, any audit that exceeds the threshold will cause this
task to fail.
|
No |
Nested Elements
The following elements can be nested within the codepro.audit
task.
<fileSet>
The standard Ant
FileSet
structure is used to specify which files are to be audited. If you specify
files outside of the projects contained by the current Eclipse workspace,
then you must specify a classpath or those external files will be ignored
by the codepro.audit ant task.
<classpath>
The classpath used for resources that exist outside of the projects
contained by the current Eclipse workspace. The classpath element is
similar to the classpath attribute in the
javac
Ant task.
<report>
The report element
is used to generate a report based on the results of the audit. Multiple
reports will be generated if the report element is included
multiple times.
<seriesReport>
The seriesReport
element is used to generate a report based on the results of a series of
audits. Multiple reports will be generated if the seriesReport
element is included multiple times.
<mailAuthors>
The mailAuthors
element is used to send e-mail to the authors of the resources that contain
violations. The body of the e-mail is a report that is filtered to contain
only those violations associated with the declared author.
Additional Notes
Both the report and seriesReport elements can be
used to generate reports on the result of running an audit. If you want to
make those reports available to a small number of people, both can have a
mail element nested within them. But if you want to make the
reports available to a larger number of people it might be better to use
the optional
ftp
Ant task to copy the generated file to an accessible location such
as a corporate or departmental web site.
Examples
The following Ant task will use the audit rule set named
"MyAuditRuleSet" contained in the file named
"code_audit.pref" to audit the files in the directory structure
rooted at "../MyJavaProject/src". After the audit is complete,
an XML report will be generated to the file named
"code_audit_result.xml" with the violations grouped by audit
rule. In addition, the report will be e-mailed to the project manager.
<codepro.audit
auditRuleSetName="MyAuditRuleSet"
auditRuleSetFile="code_audit.pref">
<fileSet dir="../MyJavaProject/src"/>
<report
file="code_audit_result.xml"
format="xml"
groupBy="audit rule">
<mail
username="user"
password="password"
from="testManager@company.com"
tolist="projectManager@company.com"/>
</report>
</codepro.audit>
The following Ant task will perform the same audit as the previous, but
will generate an e-mail message for each of the authors whose code
contains high-severity violations.
<codepro.audit
auditRuleSetName="MyAuditRuleSet"
auditRuleSetFile="code_audit.pref">
<fileSet dir="../MyJavaProject/src"/>
<mailAuthors
addressBook="addressBook.xml"
defaultAddress="testManager@company.com"
from="testManager@company.com"
groupBy="audit rule"
filter="high"/>
</codepro.audit>
Eclipse 3.0 Usage
Under Eclipse 2.1 and earlier, Ant tasks are run in the same JRE as the
IDE and can make use of Eclipse libraries. Under Eclipse 3.0, Ant tasks
are normally run in a separate JRE and don't have access to Eclipse
libraries. The codepro.audit Ant task requires access to various
Eclipse libraries, and therefore cannot run in a separate JRE. In order to
use the codepro.audit Ant task within Eclipse, you need to select
the Run in the same JRE as the workspace option from the JRE
page of the Run Ant dialog.
|