The Elements of an Audit

Overview

To perform an audit, the Audit framework applies a set of analyzers, defined by a profile, to a set of documents and collects the resulting measurements and violations into a result model. To begin an audit, Audit builds a tree of constructs. The constructs are the workspaces, projects, files, and (in the case of Java files), classes, methods, fields, statements, and so on that contain or are contained by the documents. After building the tree, Audit walks it, depth-first, from the root (the Workspaces object), "visiting" each construct as it goes. Each analyzer can supply visitor methods for any construct type it wishes; when the framework visits a construct, it invokes the visitor method in each analyzer that best matches the construct type (if any). The visitor methods can do anything they want, but typically they either collect information for later use by some other visitor method, or report measurements or violations into the result model.

Profiles and Analyzers

A profile is a named, persistent set of analyzer classes. An analyzer class is a concrete subclass of {@link oracle.jdeveloper.audit.analyzer.Analyzer Analyzer}. An instance of an analyzer subclass defines the rules and/or metrics that are the subject of its analysis, the properties that configure it, and the visitor methods that actually do the analysis.

Rules and Properties

The view of a profile that Audit presents to users is one of rules with properties, with no hint of analyzers: Screen Shot of Audit Profile Panel In this view,

Audit builds this view by iterating through the analyzers in the profile, getting from each analyzer the rules which it analyzes, and organizing them by their categories. The rules are themselves beans with properties, a couple of which are used by Audit. An analyzer can add extra properties to rules it defines, allowing the user to configure its analysis. User changes to property values are saved with the profile.

Visitor Methods

An analyzer also defines visitor methods. A visitor method is named either enter or exit, has two parameters, and the type of the first is {@link oracle.jdeveloper.audit.analyzer.AuditContext AuditContext}. The type of the second, the construct type, can be anything, but the method will never be called unless Audit actually traverses a construct that is an instance of the type. When called, the visitor method will typically either collect information for use by another visitor method later in the audit, or analyze collected information and report rule violations or measurements. Reporting is done through the AuditContext object passed to the visitor method. More details on the processing typical of visitor methods can be found in here.

Documents and Constructs

Audit builds a tree of constructs from the documents to be audited. A typical document is a source file containing Java, XML, or some other kind of structured text. These documents have an associated object model that represents the structured text as a network (usually a tree) of objects. For Java documents, the JDeveloper IDE provides the {@link oracle.jdeveloper.jot JOT}; for generic XML documents, it provides the {@link org.w3c.dom DOM}; for EJB deployment descriptors, it provides the {@link oracle.jdeveloper.xml.j2ee.ejb ejb-jar.xml binding}, and so forth. The objects in these trees are the constructs that can be visited by Audit, given a suitable document model. By default, Audit in JDeveloper 9.0.5 provides a document model only for Java source documents.

Nodes

The IDE deals with document types through its {@link oracle.ide.model.NodeFactory NodeFactory}. The node factory maps each document to a document-specific subclass of {@link oracle.ide.model.Node Node}: for example, in JDeveloper it maps Java source documents to {@link oracle.jdeveloper.model.JavaSourceNode JavaSourceNode}. Usually, the Node subclass gives access to the corresponding object model.

Document Adapters

Audit deals with the NodeFactory and the various Node classes and object models by using an adapter class, specific to the document type, for each document. The adapter class provides Audit with a standard interface to the document and to the constructs in the object model for the document. More details on creating document models can be found here.

Result Model

Audit collects the results of an Audit, violations and measurements, in an {@link oracle.jdeveloper.audit.service.AuditModel AuditModel}. This is essentially a tree table model of the audited constructs, violations, and measurements. Usually only code that invokes Audit programmatically will use the AuditModel and usually not even then.

Fixes

When an analyzer creates a rule, it can define fixes to be applied to source code that violates that rule. A fix is an object that defines a single (possibly complex) source transformation targeted to a specific location in a source file. At minimum, a fix must be able to apply itself to its targeted location. Ideally, however, a fix should also be able to determine if it is still applicable, since the source code can change between the time the violation is detected and the time the user attempts to apply the fix. More details on creating fixes can be found here.