Java Developer Tools

Audit - Adding New Audit Rules

The Code Audit facility is designed to be easily enhanced using the standard Eclipse extension facilities.

General Procedure

The general procedure for adding a new audit rule is as follows:

  1. 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.
  2. 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).
  3. Import the "org.eclipse.core.runtime", "org.eclipse.jdt.core" and "com.instantiations.assist.eclipse.analysis" plugins within your plugin.xml file.
  4. 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.
  5. 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.
  6. Extend the com.instantiations.assist.eclipse.audit_rule extension point to define your new audit rule within the plugin.xml file.
  7. Optionally, define your own audit rule group using the com.instantiations.assist.eclipse.audit_rule_group extension point.
  8. Build your plugin and install it into your \eclipse\plugins directory.
  9. Shutdown and re-start the IDE.
  10. 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:

  1. 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.
  2. 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).
  3. 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.
  4. 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.
  5. 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).
  6. 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).
  7. Build your plugin and install it into your \eclipse\plugins directory.
  8. Shutdown and re-start the IDE.
  9. Open the "CodePro | Audit | Rules" preference page and make sure that your new audit rule now has its own editor.

Sample Projects

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:

  1. Unzip the sample projects into your workspace directory.
  2. Import the "SampleAuditRuleProject" and ""SampleAuditRuleEditorProject" projects into your workspace using the "File | Import | Existing Project into Workspace" command.
  3. 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".
  4. 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.
  5. 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)..
  6. Shutdown and re-start the IDE.
  7. Open the "CodePro | Audit | Rules" preference page and look for the "Sample Group | Sample" audit rule.

Audit Extension Points

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

Audit Rule Extension Point

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.

Audit Rule Group 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

Audit Rule Set Location Extension Point

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>

Audit Violation Result Writer Extension Point

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.

Code Audit Example

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.

Framework Changes Since v2.3.0

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:

  1. 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.*

  2. Change the superclass from "AbstractAuditRule" to "CompilationUnitAuditRule"

  3. Replace the method...

    public CodeAuditor createCodeAuditor(AuditContext context){
        return new SampleCodeAuditor(context);
    }

    with...

    public Analyzer createAnalyzer(AnalysisContext context) {
        return new SampleCodeAuditor(context, this);
    }

  4. Add "AnalysisItem item" to the argument list of the code auditor constructor. For example...

    public SampleCodeAuditor(AnalysisContext context, AnalysisItem item) {
        super(context, item);
    }

  5. Within calls to the AuditViolationImpl constructor, change references to "getCompilationUnit()"
    to "getContext().getCurrentTarget()"

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.