com.togethersoft.sca.plugin.audit
Interface IAuditRule

All Known Implementing Classes:

AuditRule

public interface IAuditRule

IAuditRule provides common interface for easy extension of audit plug-ins functionality.

An audit plug-in is a Sapient plug-in that performs a set of source code verifications called audits. To allow for adding new features, audit plug-ins are implemented as easily extensible audit containers, rather than being monolithic libraries.

When an audit plug-in is initialized, it searches the registry for the registered code analyzers (see IAnalyzerDescriptor). The plug-in builds the list of audits that have been chosen to run by the user.

In audit plug-ins, audits are represented by a code analyzer. Code analyzers are not audits themselves; they only contain information necessary to load and instantiate the described audit. This is the fully qualified of the class that implements the audit, and the jar library from which it can be loaded. The only specific requirement for audits is that they must implement the IAuditRule interface.

Once the plug-in has loaded the audits, it builds the internal representation of the examined source files (called the model). The model is shown to the audits using the Visitor design pattern. The audits act as visitors; they have a chance to examine the model elements by overriding the corresponding methods of the IAuditRule interface.

The main benefit of this mechanism is easy installation of new audits. New audits can be added by putting their XML manfiset files and jar libraries into the plug-in directory.

Currently there are three Sapient audit plug-ins: jlint, audit, and refactor. All of these can be extended using the mechanism described above.

To achieve higher performance, audits are divided into several groups. Audits from each group examine the particular kind of model elements. The following groups of model elements are defined:

• Declarations (for example, classes, fields, methods)
• Statements (for example, if, while, throw statements)
• Expressions (for example, arithmetic expressions, new object creations)
• Tuples (which provide access to the data flow analysis results)

An audit specifies groups to which it belongs by passing an integer mask to the AuditRule constructor. Note that an audit may be member of multiple groups. It indicates that by OR'ing the corresponding flags.

Audit rule implementations are expected to extend the AuditRule class that contains stubs for the check methods. In effect, implementation may override only those methods that are required to perform necessary actions.

Field Summary

static int	ALL_GRP Represents an audit rule that is a member of all the groups.
static int	DECLARATION_GRP Represents an audit rule which examines declarations.
static int	EXPRESSION_GRP Represents an audit rule which examines expressions.
static int	STATEMENT_GRP Represents an audit rule which examines statements.
static int	TUPLE_GRP Represents an audit rule which examines tuples.

Method Summary

void	checkArrayCreationExpression(com.togethersoft.sca.plugin.audit.AstArrayCreationExpression expr) Examines an array creation expression.
void	checkArrayInitializer(com.togethersoft.sca.plugin.audit.AstArrayInitializer expr) Examines an array initializer expression.
void	checkArrayReference(com.togethersoft.sca.plugin.audit.AstArrayReference expr) Examines an array reference expression.
void	checkAssertStatement(com.togethersoft.sca.plugin.audit.AstAssertStatement stmt) Examines an assertion statement.
void	checkAssignmentExpression(com.togethersoft.sca.plugin.audit.AstAssignmentExpression expr) Examines an assignment expression.
void	checkBasicBlock(com.togethersoft.sca.plugin.audit.IBasicBlock block) Examines the results of control flow analysis.
void	checkBinaryExpression(com.togethersoft.sca.plugin.audit.AstBinaryExpression expr) Examines a binary expression.
void	checkBreakStatement(com.togethersoft.sca.plugin.audit.AstBreakStatement stmt) Examines a break statement.
void	checkCastExpression(com.togethersoft.sca.plugin.audit.AstCastExpression expr) Examines a type cast expression.
void	checkCompilationUnit(com.togethersoft.sca.plugin.audit.AstCompilationUnit decl) Examines a compilation unit (source file).
void	checkCompoundStatement(com.togethersoft.sca.plugin.audit.AstCompoundStatement stmt) Examines a compound statement.
void	checkConditionalExpression(com.togethersoft.sca.plugin.audit.AstConditionalExpression expr) Examines a conditional expression.
void	checkConstructorInvocation(com.togethersoft.sca.plugin.audit.AstConstructorInvocation expr) Examines an explicit constructor invocation.
void	checkContinueStatement(com.togethersoft.sca.plugin.audit.AstContinueStatement stmt) Examines a continue statement.
void	checkDeclarationStatement(com.togethersoft.sca.plugin.audit.AstDeclarationStatement stmt) Examines a declaration statement.
void	checkDoStatement(com.togethersoft.sca.plugin.audit.AstDoStatement stmt) Examines a do loop statement.
void	checkEmptyStatement(com.togethersoft.sca.plugin.audit.AstEmptyStatement stmt) Examines an empty statement.
void	checkExpressionStatement(com.togethersoft.sca.plugin.audit.AstExpressionStatement stmt) Examines an expression statement.
void	checkField(com.togethersoft.sca.plugin.audit.AstField decl) Examines a field.
void	checkField(com.togethersoft.sca.dataflow.IField field, com.togethersoft.sca.plugin.audit.AstField ast) Examines a field.
void	checkFieldReference(com.togethersoft.sca.plugin.audit.AstFieldReference expr) Examines a field reference expression.
void	checkForStatement(com.togethersoft.sca.plugin.audit.AstForStatement stmt) Examines a for loop statement.
void	checkIfStatement(com.togethersoft.sca.plugin.audit.AstIfStatement stmt) Examines an if statement.
void	checkInitializer(com.togethersoft.sca.plugin.audit.AstInitializer decl) Examines a class initializer.
void	checkLifetime(com.togethersoft.sca.plugin.audit.ITupleSet[][] webs) Examined lifetime of a local variable.
void	checkLiteral(com.togethersoft.sca.plugin.audit.AstLiteral expr) Examines a literal.
void	checkLoop(com.togethersoft.sca.plugin.audit.IJavaLoop loop) Examines a loop.
void	checkMethod(com.togethersoft.sca.plugin.audit.AstMethod method) Examines a method.
void	checkMethod(com.togethersoft.sca.dataflow.IMethod method, com.togethersoft.sca.plugin.audit.AstMethod ast) Examines a method.
void	checkMethodCallExpression(com.togethersoft.sca.plugin.audit.AstMethodCallExpression expr) Examines a method call expression.
void	checkModel(com.togethersoft.sca.plugin.audit.AstModel model) Examines a model (whole project).
void	checkObjectCreationExpression(com.togethersoft.sca.plugin.audit.AstObjectCreationExpression expr) Examines an object creation expression.
void	checkParenthesizedExpression(com.togethersoft.sca.plugin.audit.AstParenthesizedExpression expr) Examines a parenthesized expression.
void	checkReturnStatement(com.togethersoft.sca.plugin.audit.AstReturnStatement stmt) Examines a return statement.
void	checkSimpleReference(com.togethersoft.sca.plugin.audit.AstSimpleReference expr) Examines a simple name expression.
void	checkSuperExpression(com.togethersoft.sca.plugin.audit.AstSuperExpression expr) Examines super expression.
void	checkSwitchStatement(com.togethersoft.sca.plugin.audit.AstSwitchStatement stmt) Examines a switch statement.
void	checkSynchronizedStatement(com.togethersoft.sca.plugin.audit.AstSynchronizedStatement stmt) Examines a synchronized statement.
void	checkThisExpression(com.togethersoft.sca.plugin.audit.AstThisExpression expr) Examines a this expression.
void	checkThrowStatement(com.togethersoft.sca.plugin.audit.AstThrowStatement stmt) Examines a throw statement.
void	checkTryStatement(com.togethersoft.sca.plugin.audit.AstTryStatement stmt) Examines a try statement.
void	checkTuple(com.togethersoft.sca.plugin.audit.ITuple tuple, com.togethersoft.sca.plugin.audit.IVal[] operands, com.togethersoft.sca.dataflow.values.IValueDomain[] values, com.togethersoft.sca.dataflow.values.IValueDomain result) Examines the results of data flow analysis.
void	checkType(com.togethersoft.sca.plugin.audit.AstType decl) Examines a class or an interface.
void	checkTypeExpression(com.togethersoft.sca.plugin.audit.AstTypeExpression expr) Examines a type expression.
void	checkUnaryExpression(com.togethersoft.sca.plugin.audit.AstUnaryExpression expr) Examines a unary expression.
void	checkVariable(com.togethersoft.sca.plugin.audit.AstVariable decl) Examines a variable or method parameter.
void	checkWhileStatement(com.togethersoft.sca.plugin.audit.AstWhileStatement stmt) Examines a while loop statement.
void	enterPackage(com.togethersoft.sca.plugin.audit.AstPackage pkg) enterPackage is the first method called during package examination.
com.togethersoft.sca.core.IAnalyzerDescriptor	getAnalyzer() Returns the analyzer that produced this message.
java.lang.String	getExplainMessage(com.togethersoft.sca.plugin.audit.AstObject ast, java.lang.String messageId, java.lang.Object[] values) Returns the formatted explain text of this message in HTML format
java.util.ResourceBundle	getResourceBundle() Method getResourceBundle return ResourceBundle by default return value is null.
java.lang.String	getSeverity() Returns the severity of messages generated by this rule.
com.togethersoft.sca.core.plugin.audit.AutoFix	getSuppressionFix(com.togethersoft.sca.core.plugin.audit.IAuditMessage msg) Returns a fix that will suppress the given message during subsequent audit executions.
void	leaveCompoundStatement(com.togethersoft.sca.plugin.audit.AstCompoundStatement stmt) Called when all the statements contained in the block have been examined.
void	leaveMethod(com.togethersoft.sca.plugin.audit.AstMethod method) leaveMethod is called when the body of the method has been examined.
void	leavePackage(com.togethersoft.sca.plugin.audit.AstPackage pkg) leavePackage is the last method called during package examination.
boolean	requiresDataFlowAnalysis() If this audit requires data flow analysis

Field Detail

ALL_GRP

public static final int ALL_GRP

Represents an audit rule that is a member of all the groups.

DECLARATION_GRP

public static final int DECLARATION_GRP

Represents an audit rule which examines declarations.

EXPRESSION_GRP

public static final int EXPRESSION_GRP

Represents an audit rule which examines expressions.

STATEMENT_GRP

public static final int STATEMENT_GRP

Represents an audit rule which examines statements.

TUPLE_GRP

public static final int TUPLE_GRP

Represents an audit rule which examines tuples.

Method Detail

checkArrayCreationExpression

public void checkArrayCreationExpression(com.togethersoft.sca.plugin.audit.AstArrayCreationExpression expr)

Examines an array creation expression.

Group: expressions.

checkArrayInitializer

public void checkArrayInitializer(com.togethersoft.sca.plugin.audit.AstArrayInitializer expr)

Examines an array initializer expression.

Group: expressions.

checkArrayReference

public void checkArrayReference(com.togethersoft.sca.plugin.audit.AstArrayReference expr)

Examines an array reference expression.

Group: expressions.

checkAssertStatement

public void checkAssertStatement(com.togethersoft.sca.plugin.audit.AstAssertStatement stmt)

Examines an assertion statement.

Group: statements.

checkAssignmentExpression

public void checkAssignmentExpression(com.togethersoft.sca.plugin.audit.AstAssignmentExpression expr)

Examines an assignment expression.

Group: expressions.

checkBasicBlock

public void checkBasicBlock(com.togethersoft.sca.plugin.audit.IBasicBlock block)

Examines the results of control flow analysis.

Group: statements.

checkBinaryExpression

public void checkBinaryExpression(com.togethersoft.sca.plugin.audit.AstBinaryExpression expr)

Examines a binary expression.

Group: expressions.

checkBreakStatement

public void checkBreakStatement(com.togethersoft.sca.plugin.audit.AstBreakStatement stmt)

Examines a break statement.

Group: statements.

checkCastExpression

public void checkCastExpression(com.togethersoft.sca.plugin.audit.AstCastExpression expr)

Examines a type cast expression.

Group: expressions.

checkCompilationUnit

public void checkCompilationUnit(com.togethersoft.sca.plugin.audit.AstCompilationUnit decl)

Examines a compilation unit (source file).

Group: declarations.

checkCompoundStatement

public void checkCompoundStatement(com.togethersoft.sca.plugin.audit.AstCompoundStatement stmt)

Examines a compound statement.

Group: statements.

checkConditionalExpression

public void checkConditionalExpression(com.togethersoft.sca.plugin.audit.AstConditionalExpression expr)

Examines a conditional expression.

Group: expressions.

checkConstructorInvocation

public void checkConstructorInvocation(com.togethersoft.sca.plugin.audit.AstConstructorInvocation expr)

Examines an explicit constructor invocation.

Group: expressions.

checkContinueStatement

public void checkContinueStatement(com.togethersoft.sca.plugin.audit.AstContinueStatement stmt)

Examines a continue statement.

Group: statements.

checkDeclarationStatement

public void checkDeclarationStatement(com.togethersoft.sca.plugin.audit.AstDeclarationStatement stmt)

Examines a declaration statement.

Group: statements.

checkDoStatement

public void checkDoStatement(com.togethersoft.sca.plugin.audit.AstDoStatement stmt)

Examines a do loop statement.

Group: statements.

checkEmptyStatement

public void checkEmptyStatement(com.togethersoft.sca.plugin.audit.AstEmptyStatement stmt)

Examines an empty statement.

Group: statements.

checkExpressionStatement

public void checkExpressionStatement(com.togethersoft.sca.plugin.audit.AstExpressionStatement stmt)

Examines an expression statement.

Group: statements.

checkField

public void checkField(com.togethersoft.sca.plugin.audit.AstField decl)

Examines a field.

Group: declarations.

checkField

public void checkField(com.togethersoft.sca.dataflow.IField field,
                       com.togethersoft.sca.plugin.audit.AstField ast)

Examines a field. Group: declarations.

checkFieldReference

public void checkFieldReference(com.togethersoft.sca.plugin.audit.AstFieldReference expr)

Examines a field reference expression.

Group: expressions.

checkForStatement

public void checkForStatement(com.togethersoft.sca.plugin.audit.AstForStatement stmt)

Examines a for loop statement.

Group: statements.

checkIfStatement

public void checkIfStatement(com.togethersoft.sca.plugin.audit.AstIfStatement stmt)

Examines an if statement.

Group: statements.

checkInitializer

public void checkInitializer(com.togethersoft.sca.plugin.audit.AstInitializer decl)

Examines a class initializer.

Group: declarations.

checkLifetime

public void checkLifetime(com.togethersoft.sca.plugin.audit.ITupleSet[][] webs)

Examined lifetime of a local variable. Group: expressions.

checkLiteral

public void checkLiteral(com.togethersoft.sca.plugin.audit.AstLiteral expr)

Examines a literal.

Group: expressions.

checkLoop

public void checkLoop(com.togethersoft.sca.plugin.audit.IJavaLoop loop)

Examines a loop. It may be used for finding infinite and never executed loops.

Group: statements.

checkMethod

public void checkMethod(com.togethersoft.sca.plugin.audit.AstMethod method)

Examines a method.

Group: declarations.

checkMethod

public void checkMethod(com.togethersoft.sca.dataflow.IMethod method,
                        com.togethersoft.sca.plugin.audit.AstMethod ast)

Examines a method. Group: declarations.

checkMethodCallExpression

public void checkMethodCallExpression(com.togethersoft.sca.plugin.audit.AstMethodCallExpression expr)

Examines a method call expression.

Group: expressions.

checkModel

public void checkModel(com.togethersoft.sca.plugin.audit.AstModel model)

Examines a model (whole project).

Group: declarations.

checkObjectCreationExpression

public void checkObjectCreationExpression(com.togethersoft.sca.plugin.audit.AstObjectCreationExpression expr)

Examines an object creation expression.

Group: expressions.

checkParenthesizedExpression

public void checkParenthesizedExpression(com.togethersoft.sca.plugin.audit.AstParenthesizedExpression expr)

Examines a parenthesized expression.

Group: expressions.

checkReturnStatement

public void checkReturnStatement(com.togethersoft.sca.plugin.audit.AstReturnStatement stmt)

Examines a return statement.

Group: statements.

checkSimpleReference

public void checkSimpleReference(com.togethersoft.sca.plugin.audit.AstSimpleReference expr)

Examines a simple name expression.

Group: expressions.

checkSuperExpression

public void checkSuperExpression(com.togethersoft.sca.plugin.audit.AstSuperExpression expr)

Examines super expression.

Group: expressions.

checkSwitchStatement

public void checkSwitchStatement(com.togethersoft.sca.plugin.audit.AstSwitchStatement stmt)

Examines a switch statement.

Group: statements.

checkSynchronizedStatement

public void checkSynchronizedStatement(com.togethersoft.sca.plugin.audit.AstSynchronizedStatement stmt)

Examines a synchronized statement.

Group: statements.

checkThisExpression

public void checkThisExpression(com.togethersoft.sca.plugin.audit.AstThisExpression expr)

Examines a this expression.

Group: expressions.

checkThrowStatement

public void checkThrowStatement(com.togethersoft.sca.plugin.audit.AstThrowStatement stmt)

Examines a throw statement.

Group: statements.

checkTryStatement

public void checkTryStatement(com.togethersoft.sca.plugin.audit.AstTryStatement stmt)

Examines a try statement.

Group: statements.

checkTuple

public void checkTuple(com.togethersoft.sca.plugin.audit.ITuple tuple,
                       com.togethersoft.sca.plugin.audit.IVal[] operands,
                       com.togethersoft.sca.dataflow.values.IValueDomain[] values,
                       com.togethersoft.sca.dataflow.values.IValueDomain result)

Examines the results of data flow analysis.

Group: tuples.

checkType

public void checkType(com.togethersoft.sca.plugin.audit.AstType decl)

Examines a class or an interface.

Group: declarations.

checkTypeExpression

public void checkTypeExpression(com.togethersoft.sca.plugin.audit.AstTypeExpression expr)

Examines a type expression.

Group: expressions.

checkUnaryExpression

public void checkUnaryExpression(com.togethersoft.sca.plugin.audit.AstUnaryExpression expr)

Examines a unary expression.

Group: expressions.

checkVariable

public void checkVariable(com.togethersoft.sca.plugin.audit.AstVariable decl)

Examines a variable or method parameter.

Group: declarations.

checkWhileStatement

public void checkWhileStatement(com.togethersoft.sca.plugin.audit.AstWhileStatement stmt)

Examines a while loop statement.

Group: statements.

enterPackage

public void enterPackage(com.togethersoft.sca.plugin.audit.AstPackage pkg)

enterPackage is the first method called during package examination.

Group: declarations.

getAnalyzer

public com.togethersoft.sca.core.IAnalyzerDescriptor getAnalyzer()

Returns the analyzer that produced this message.

getExplainMessage

public java.lang.String getExplainMessage(com.togethersoft.sca.plugin.audit.AstObject ast,
                                          java.lang.String messageId,
                                          java.lang.Object[] values)

Returns the formatted explain text of this message in HTML format

Returns:

String the formatted message

getResourceBundle

public java.util.ResourceBundle getResourceBundle()

Method getResourceBundle return ResourceBundle by default return value is null.

Returns:

ResourceBundle property file with localized Audit messages

getSeverity

public java.lang.String getSeverity()

Returns the severity of messages generated by this rule. Returns an empty string if the severity was not specified.

getSuppressionFix

public com.togethersoft.sca.core.plugin.audit.AutoFix getSuppressionFix(com.togethersoft.sca.core.plugin.audit.IAuditMessage msg)

Returns a fix that will suppress the given message during subsequent audit executions. Returns null if suppression fix cannot be created. When run, the suppression fix will insert a special comment before the associated code fragment, for example:

     void f(int a) {
         int z = 0;
         // $SUP-AP$ $SUP-EVNU$ $SUP-ONE$
         a += z;
     }
 

leaveCompoundStatement

public void leaveCompoundStatement(com.togethersoft.sca.plugin.audit.AstCompoundStatement stmt)

Called when all the statements contained in the block have been examined.

leaveMethod

public void leaveMethod(com.togethersoft.sca.plugin.audit.AstMethod method)

leaveMethod is called when the body of the method has been examined.

Group: declarations.

leavePackage

public void leavePackage(com.togethersoft.sca.plugin.audit.AstPackage pkg)

leavePackage is the last method called during package examination.

Group: declarations.

requiresDataFlowAnalysis

public boolean requiresDataFlowAnalysis()

If this audit requires data flow analysis

Returns:

boolean