|Each time the menu item "Audit Code" is selected, the enabled audit rules in the default audit rule set will be run. This produces a audit violation result set, which is then displayed in the Audit view. A violation result set is the result of running a specific audit rule set on a collection of resources. The Audit view can manage multiple violation result sets simultaneously, but only one can be active and visible at one time.|
|An option is also provided to
dynamically audit code in specific
packages (specified by inclusion and exclusion patterns). When dynamic
auditing is turned on for a package, opening a class in that package will result in it
being automatically scanned for audit violations and the results added
to the Audit view (to the "Violations in Open Files" audit
violation set). Note that if the dynamic audit violation set is not
active, you would not see any dynamic audit results.
The dynamic code audit facility is invaluable to catching problems as the developer is writing code, rather than after the code is written. A single naming violation, for example, might be propagated through dozens of source files before a nightly build/audit would flag the problem. Dynamic audit flags the problem as it occurs as close to the actual event as possible. The cost to fix many coding problems is often in direct proportion to the time between when the problem was created and when it was caught. Dynamic code audit is the equivalent of having a personal code reviewer sitting on your shoulder all day silently making suggestions as necessary.
Audit rules can be locally disabled for one or more lines in a file. You may also establish project defaults that determine which files are included and excluded from the audit process and which audit rule sets are used for different packages or files.
The Audit view (shown in the picture above) contains a list of the audit rule violations that resulted from running those audit rules against the target elements. The name of each audit rule with a violation is shown at the root of the tree. Expanding any audit rule will show the list of individual violations (with their locations). Selected violations can be removed from the set and copied to the clipboard.
Each audit violation is shown with an icon indicating its severity level:
Double clicking on any violation will open up the corresponding compilation unit and position it at the specific violation. Annotations for each violation are shown in the Java Editor.
Audit rules can be locally disabled for one or more lines in a file.
Right-clicking on any violation, rule or resource with show the following menu:
The "Go to File" command will open up the corresponding compilation unit and position it at the specific violation.
The "Copy to Clipboard" item will allow you to capture the currently selected violations on the clipboard so that they can be pasted into e-mail messages, text documents, HTML documents, XML documents or even a spreadsheet application.
|The "Generate Report" item will allow you to save the currently visible
results to an HTML report. The results may be grouped by audit rule,
category (audit rule group), severity, resource or author.
A sample HTML report is shown below. The audit violations will be listed grouped by audit rule, category, severity or resource depending on the choice made in the audit view. Clicking on the links in the Details column of the report will jump to the violations and show them in context in teh actual source.
The "E-mail Report" item will allow you to e-mail the currently visible results as an HTML report. The results may be grouped by audit rule, category (audit rule group), severity, resource or author.
The "Export Violations" item allows you to save the currently visible results directly to a text file in simple text, tab separated, comma separated (full report or summary), HTML or XML format (holding down the Ctrl key will save only the violations that you have selected).
A sample XML report is shown below.
The "Explain" command will show an explanation of what caused the selected audit violation or a description of the selected audit rule. If their are any recommendations for fixing the problem, they will be shown as well.
The "Fix Violation" command will list any specific resolutions supplied by the audit facility. Clicking on a fix will cause it to be applied the selected violations. In some cases, ignoring the violation is the correct course of action, so several options for locally disabling the rule are also supplied. Note that some resolutions may be applied to multiple violations at one time while other may only be applied to a single violation at a time.
The "Disable Rule" command will disable the selected audit rules in the current audit set. Alternately, audit rules can be locally disabled for one or more lines in a file. The "Configure Rule" command will open up a dialog allowing you to configure the selected audit rule.
The "Create Task" command will create tasks out of any selected audit violations.
The "Remove Violations" command will remove the selected audit violations from the currently visible set of results.
Clicking on the Refresh button will cause the current set of results to be refreshed in case any of the violations may have changed or been fixed or any new violations created.
Clicking on the Filter button will open a dialog where you can select which violation severities should be visible in the audit view.
Clicking on the Remove Current Violation Set button will cause the currently visible set of results to be discarded. This operation cannot be undone. If the current violation set is still in process, this button will stop the process and discard any violations that have been found.
Clicking on the Remove All Violation Sets button will cause all of the sets of results to be discarded. This operation cannot be undone. If any of the current violation sets are still in process, this button will stop them and discard any violations that have been found.
Clicking on the arrow beside the Previous Violation Set button will cause a menu containing the most recently run audit violation results to be displayed. If there are additional sets of audit results available but not included on the menu, a menu item labeled "Other" will also be on the menu. Selecting one of the result sets from the list will make the audit view show the content of the selected result set.
Either clicking on the history icon for the Previous Violation Set button, or selecting "Other" from the drop-down menu, will cause a dialog to open in which you can select the result set that you would like to view. This dialog contains a complete list of all available result sets.
When dynamic auditing is in effect, a special "Violations in Open Files" audit set will be included in the list. If the "Violations in Open Files" violation set is not active, you would not see any dynamic audit results.
Result sets are not persisted beyond a single execution of the workbench.
The "Export" option can be used to export the currently selected result set to an XML file that can be loaded in later.
The "Import" option can be used to import a result set from an XML file.
The "Hide Violations" option hides the current result set so that no flags are shown in the editors.
Selecting the Show Explanation Pane menu item toggles the explanation pane on and off. When the explanation pane is visible, clicking on an audit rule or violation shows a detailed description of that item.
Adding New Audit Rules
The Code Audit facility defines an Eclipse extension point for adding new audit rules. See:
All of CodePro's audit rules are defined using this extension point.