Audit - Adding New Audit Rules
The Code Audit facility is designed to be easily enhanced using the
standard Eclipse extension facilities.
The general procedure for adding a new audit rule is as follows:
- Create a new plugin project using the PDE plugin wizard (File | New
| Project | Plug-in Development | Plug-in Project). Detailed
instructions on how to create an Eclipse plugin can be found in the
"Tool Developer" section of the Eclipse on-line help.
- Make sure that the .classpath file of your project includes
classpath entries for the Eclipse core runtime (runtime.jar), the JDT
core (jdtcore.jar) and the analysis core (CodeProAnalysis.jar).
- Import the "org.eclipse.core.runtime", "org.eclipse.jdt.core"
and "com.instantiations.assist.eclipse.analysis" plugins
within your plugin.xml file.
- Create a new audit rule class that implements the com.instantiations.assist.eclipse.analysis.audit.core.AuditRule
interface. Extending the com.instantiations.assist.eclipse.analysis.audit.core.CompilationUnitAuditRule
class is an easy way to do this. A convenient Audit
Rule Wizard has been provided to simplify this task. An audit
rule example is also presented below.
- Compile your audit rule into a jar file that will be included in
your plugin (make sure to reference it as a runtime library within
your plugin.xml file). If your audit rule will need an associated
preference editor, make sure to include the <export
name="*"> tag within your runtime library definition.
- Extend the com.instantiations.assist.eclipse.audit_rule
extension point to define your new audit rule within the plugin.xml
file.
- Optionally, define your own audit rule group using the com.instantiations.assist.eclipse.audit_rule_group
extension point.
- Build your plugin and install it into your \eclipse\plugins
directory.
- Shutdown and re-start the IDE.
- Open the "CodePro | Audit | Rules" preference page and
look for your new audit rule.
If your audit rule needs an associated preference editor, do the
following:
- Create another new plugin project using the PDE plugin wizard (File
| New | Project | Plug-in Development | Plug-in Project). Since the
audit facility can also be used in a headless manner from an
Ant script, it is important that the UI portions of your audit rule
(e.g., the preference page) be contained in a separate plugin. That
will ensure that your basic audit rule will not have any UI
dependencies.
- Make sure that the .classpath file of your project includes
classpath entries for the Eclipse SWT library (swt.jar), the analysis core (CodeProAnalysis.jar) and the analysis UI (CodeProAnalysisUI.jar).
- Import the "org.eclipse.swt", "com.instantiations.assist.eclipse.analysis"
and "com.instantiations.assist.eclipse.analysis.ui" plugins
within your plugin.xml file. Also make sure to import your audit rule
plugin created above.
- Create a new audit rule editor class that implements the com.instantiations.assist.eclipse.analysis.ui.audit.editor.AuditRuleEditor
interface. Extending the com.instantiations.assist.eclipse.analysis.ui.audit.editor.BasicAuditRuleEditor
class is an easy way to do this. A convenient Audit
Rule Wizard has been provided to simplify this task.
- Compile your audit rule editor into a jar file that will be included
in your plugin (make sure to reference it as a runtime library within
your plugin.xml file).
- Reference your editor class using the "editor" attribute
within the audit rule definition you added to your audit rule
plugin.xml file (in the first project above). Since the editor class
exists in a separate plugin, you will need to reference it using its
fully qualified name (e.g., plugin name/fully qualified class name).
- Build your plugin and install it into your \eclipse\plugins
directory.
- Shutdown and re-start the IDE.
- Open the "CodePro | Audit | Rules" preference page and
make sure that your new audit rule now has its own editor.
Two sample audit rule
projects have been provided for your convenience. The first defines a
simple audit rule, and the second defines an audit rule editor. Feel free
to use them as you see fit. To use the samples, do the following:
- Unzip the sample
projects into your workspace directory.
- Import the "SampleAuditRuleProject" and ""SampleAuditRuleEditorProject"
projects into your workspace using the "File | Import | Existing
Project into Workspace" command.
- The .classpath file for each project is set up for Application Developer 5.1. If you are using Application Developer 5.0, rename the
".classpath20" files to ".classpath".
- Select the "build.xml" file in each project, right click
and select the "Run Ant..." command, and then choose the
"export" target to build each project.
- Unzip the resulting SampleAuditRulePlugin.zip and
SampleAuditRuleEditorPlugin.zip files into your Eclipse or
<websphere>\eclipse
directory (make sure to preserve the directory structure so that the
plugin files themselves end up in your Eclipse \plugins directory)..
- Shutdown and re-start the IDE.
- Open the "CodePro | Audit | Rules" preference page and
look for the "Sample Group | Sample" audit rule.
The Code Audit facility define several Eclipse extension points
for adding new audit rules. See:
<CODEPRO>\eclipse\plugins\com.instantiations.assist.eclipse.analysis_X.X.X\plugin.xml
The audit rule extension point allows new audit rules to
be added to the list of audit rules that can be run. It is supported by
the "auditRule" tag, which defines the following attributes:
id
A string used as a prefix to compose standard preference names.
name
The localized name of the audit rule. This is the name that will be
displayed in the user interface.
description
The localized description of the audit rule. This is the description
that will be displayed in the user interface.
class
The name of the class that implements the audit rule. The specified
class must implement the interface com.instantiations.assist.eclipse.analysis.audit.core.AuditRule.
Extending the com.instantiations.assist.eclipse.analysis.audit.core.AbstractAuditRule
class is an easy way to do this. An example of a rule may be found here.
group
The id of the audit rule group to which this audit rule belongs. All
audit rules must belong to exactly one group. Audit rule groups are
defined by a separate extension
point, described below.
editor
(optional) The name of the class that implements the subportion of
the Audit preference dialog page that allows the user to customize the
behavior of the audit rule. The specified class must implement the
interface com.instantiations.assist.eclipse.analysis.ui.audit.editor.AuditRuleEditor.
An example of an audit rule editor may be found here.
violation
When run, each audit rule can generate multiple types of violations.
Each violation that can be generated by a rule is described by the
"violation" tag, which is a child of the "auditRule"
tag. Each "auditRule" tag can have one or more
"violation" tags. The "violation" tag defines the
following attributes:
id
A string used to identify the violation. The identifiers must be
unique across all violations, not just within the violations for a
single audit rule.
description
The localized description of the violation. This is the description
that will be displayed in the user interface.
explanation
The localized explanation of the audit rule. This is the text that
will be displayed in the user interface when the user asks for an
explanation. It should be concise, but complete.
For example
<extension point="com.instantiations.assist.eclipse.audit_rule">
<auditRule
id="com.xyz.audit.myAuditRule"
name="%myAuditRuleName"
description="%myAuditRuleDescription"
class="com.xyz.audit.MyAuditRule"
group="com.xyz.audit.myAuditRuleGroup"
editor="com.xyz.audit.MyAuditRuleEditor"/>
<violation
id="com.xyz.audit.myAuditRule.myViolation"
description="%myAuditRule.myViolationDescription"
explanation="%myAuditRule.myViolationExplanation"/>
</auditRule>
</extension>
All of CodePro's audit rules are defined using this extension point.
The audit rule group extension point allows new audit
rule groups to be added to the list of groups that can be associated with
audit rules. It is supported by the "auditRuleGroup" tag, which
defines the following attributes:
id
The identifier used to associate audit rules with this group.
name
The localized name of the group. This is the name that will be
presented to the user within the user interface.
description
The localized description of the audit rule group. This is the
description that will be displayed in the user interface.
For example:
- <extension point="com.instantiations.assist.eclipse.audit_rule_group">
- <auditRuleGroup
- id="com.xyz.audit.myAuditRuleGroup"
- name="%myAuditRuleGroupName"
- description="%myAuditRuleGroupDescription"/>
- </extension>
The product predefines many audit rule groups that you may reuse, if you are so
inclined.
EJB |
com.instantiations.assist.eclipse.auditGroup.ejb |
Exception Usage |
com.instantiations.assist.eclipse.auditGroup.exceptionUsage |
Formatting |
com.instantiations.assist.eclipse.auditGroup.formatting |
Inheritance |
com.instantiations.assist.eclipse.auditGroup.inheritance |
Import Usage |
com.instantiations.assist.eclipse.auditGroup.importUsage |
Internationalization |
com.instantiations.assist.eclipse.auditGroup.internationalization |
Javadoc Conventions |
com.instantiations.assist.eclipse.auditGroup.javadocConventions |
Miscellaneous |
com.instantiations.assist.eclipse.auditGroup.miscellaneous |
Modifier Usage |
com.instantiations.assist.eclipse.auditGroup.modifierUsage |
Naming Conventions |
com.instantiations.assist.eclipse.auditGroup.namingConventions |
Performance |
com.instantiations.assist.eclipse.auditGroup.performance |
Possible Errors |
com.instantiations.assist.eclipse.auditGroup.possibleErrors |
Potential Refactoring |
com.instantiations.assist.eclipse.auditGroup.potentialRefactoring |
Program Complexity |
com.instantiations.assist.eclipse.auditGroup.programComplexity |
Semantic Errors |
com.instantiations.assist.eclipse.auditGroup.semanticErrors |
Style |
com.instantiations.assist.eclipse.auditGroup.style |
The audit rule set location extension point allows new
audit rule sets to be read in at Eclipse startup time. These rule sets
automatically become locked so the user can make no changes to them. It is
supported by the "ruleSetLocation" tag, which defines the
following attributes:
directory
The path name of the directory in which rule set files will be
found. Either fully qualified or relative to the Eclipse plugin
directory.
For example:
- <extension point="com.instantiations.assist.eclipse.audit_rule_set_location">
- <ruleSetLocation directory="myPlugin/myRuleSets"/>
- </extension>
The Audit Violation Result Writer extension point allows new
result writers to be added to the list of result writers that can be used
to format audit results.
id
The identifier for the result writer.
name
The human readable name for the result writer.
class
The fully qualified name of the class that implements the com.instantiations.assist.eclipse.analysis.audit.core.AuditResultWriter
interface.
For example:
- <extension point="com.instantiations.assist.eclipse.analysis.audit_result_writer">
- <writer
- id="com.xyz.audit.MyAuditResultWriter"
- name="%myAuditResultWriterName"
- fileExtension="rep"
- class="com.xyz.audit.MyAuditResultWriter"/>
- </extension>
Here are examples of the audit result writers provided with CodePro. You can
use these as templates to create your own custom reports.
A simple example of an audit rule is the AddMethodToInterfaceAuditRule.java
class. The code for the violation testing itself is very simple and
requires nothing beyond knowledge of the Eclipse AST model (which is well
commented and comes with full source).
The audit rule is contributed to the system via a standard Eclipse
extension point, The following is the snippet from our code audit plugin.xml
file that defines this rule:
- <auditRule
- id="com.instantiations.assist.eclipse.audit.addMethodToInterface"
- name="%addMethodToInterfaceName"
- description="%addMethodToInterfaceDescription"
- class="com.instantiations.assist.eclipse.analysis.audit.rule.AddMethodToInterfaceAuditRule"
- group="com.instantiations.assist.eclipse.auditGroup.potentialRefactoring"
- editor="com.instantiations.assist.eclipse.analysis.ui.audit.editor.AddMethodToInterfaceAuditRuleEditor">
- <violation
- id="com.instantiations.assist.eclipse.audit.addMethodToInterface.addMethod"
- description="%addMethodToInterface.addMethodDescription"
- explanation="%addMethodToInterface.addMethodExplanation"/>
- </auditRule>
Each audit "rule" may define one or more audit violations (in
this case, there is just one). Each rule defines its ID, name, description
(which shows up in the audit pref page), implementing
class, audit rule group (you can define your own groups via another
extension point), editor class (in
case the rule has any user-settable properties exposed in the preference
dialog), and its list of violations. Each violation defines its ID,
description (which shows up in the audit view or
as hover help in an editor) and explanation text (basically a more
detailed version of the description text that is shown when the user asks
for an explanation of the rule).
The strings are all externalized in a plugin.properties file.
The following is a snippet from that file that provides that actual
strings used for this rule:
- addMethodToInterfaceName = Add Method to Interface
- addMethodToInterfaceDescription = \
- <b>Summary</b>\n\
- \n\
- Identify properties that can be added to an
interface.\n\
- \n\
- <b>Description</b>\n\
- \n\
- This audit rule finds methods in concrete
classes that can be \
- added to their corresponding interfaces. If a
class is named Foo \
- and has a "bar" property with getBar()
and setBar() methods, the \
- corresponding interface, IFoo, will be checked
to see if it defines \
- the getter and setter method.
- addMethodToInterface.addMethodDescription = \
- The {0}() method should be added to the {1}
interface.
- addMethodToInterface.addMethodExplanation = \
- The {0}() method is not defined by the {1}
interface and \
- should be added.
Note that the description text supports simple HTML formatting. The
violation description and explanation text can be parameterized with
strings passed by the violation itself (in this case, the name of the
method and the name of the interface - you will see these passed as
arguments in the implementing class).
Some additional sample audit rules that can act as templates for any new
audit rules that you create include:
A convenient Audit Rule Wizard has
also been provided to simplify the task of creating new audit rules.
In order to enhance the Code Audit framework to support file types
other than .java, several major changes have been made to the code
auditing framework that will necessitate changes be made to any audit rule
written to the v2.3.0 spec or earlier. To convert an audit rule from the
earlier spec to the new spec, do the following:
- Import the following packages (replacing the current imports):
- com.instantiations.assist.eclipse.analysis.audit.core.*
- com.instantiations.assist.eclipse.analysis.audit.rule.*
- com.instantiations.assist.eclipse.analysis.engine.core.*
- Change the superclass from "AbstractAuditRule" to
"CompilationUnitAuditRule"
- Replace the method...
public CodeAuditor
createCodeAuditor(AuditContext context){
return new SampleCodeAuditor(context);
}
with...
public Analyzer
createAnalyzer(AnalysisContext context) {
return new SampleCodeAuditor(context, this);
}
- Add "AnalysisItem item" to the argument list of the code
auditor constructor. For example...
public
SampleCodeAuditor(AnalysisContext context, AnalysisItem item) {
super(context, item);
}
- Within calls to the AuditViolationImpl constructor, change
references to "getCompilationUnit()"
to "getContext().getCurrentTarget()"
|