Inspector developer guide

Prerequisites

 A code review solution, either the bundle or a custom assembly shall be installed in your environment. See Hammurapi 5 Quick Start Guide for installation instructions.

Set up

• Create a project in your favorite Java IDE and add Mesopotamia, Hammurapi rules and Hammurapi jar files to the project build path.
• Start code review solution's database and web application.

Identify the problem

Write down in a plain human language what is the problem. In our sample project we’ll implement an inspector “If you have to compare with a string do not use degree.equals("1")), but rather "1".equals(degree)”

Identify a language construct to be inspected

From the inspector description above we see that we need to inspect equals() method call.

Create code snippets for testing

• Code snippet which violates the coding rule to be checked by the new inspector.
• Code snippet compliant with the rule.

Multiple levels of parsing

There are multiple levels of parsing of sources. E.g. there are three levels in the Java language module. First of all, character stream from source file is converted into token stream by a lexer. Then tokens are composed into an Abstract Syntax Tree (AST) by a parser. The AST is homogeneous, i.e. all nodes are instances of the same class. As the last parsing step, AST is transformed into a heterogeneous graph of objects where each language construct is represented by a separate Java class. These classes form a hierarchy which follows target language’s grammar production rules.

It is possible to write inspectors working with tokens, AST or language elements. While inspectors can work on tokens, AST, or language elements, most inspectors work with language elements because heterogeneity of the language elements graph allows to use method parameter type matching to indicate which language construct a particular inspector is “interested in”.

Syntax tree and token stream can be obtained from SourceUnit class. Consult Mesopotamia and Mesopotamia Java language module JavaDoc or source code for more information.

Visualize the violation to identify Term 269language element class/interface to be inspected

A picture is worth a thousand words. SourceUnit and LanguageElement classes have show() method. This method displays object and its children as a tree. To take a look at parsed source code structure create inspect() method as shown below.

 Then create a file called my-inspectors.xml with the following content.

Configure the code review solution in your environment to include the new inspector class into classpath and to use my-inspectors.xml inspector set. When you run a review, a Swind window will open showing structure of the source unit. show() method blocks the invoking thread while browser window is open. Close the browser to resume program execution.

In our example, after studying source unit structure and JavaDoc we come to conclusion that we need to write inspect method for MethodCall class. Modified inspector code will look like

This version of our inspector will show the browser window for each MethodCall instance encountered in the code being reviewed.

Implement inspector logic

Now we'll implement inspector logic.

A single method inspect() takes MethodCall instance. Code review runtime parses source files, creates language element instances and then passes those instances to compatible inspect() methods. I.e. if we had inspect(LanguageElement le) method we’d get all language elements for inspection; inspect(Object obj) would get all language elements and source units for inspection. Here we are getting only instances of MethodCall.

inspect() methods can throw any exceptions. Exceptions thrown by inspector are intercepted by the code review runtime and output to the report as warnings.

This inspector assumes that developers don’t write code like “A”.equals(“B”) and as such there is no need to check if the method provider is a String constant. A check like this, comparison operator on two constants, would be a task for another inspector.

In our case the inspector is not parameterizable. Parameterization can be easily added by providing appropriate setter methods. See DomConfigFactory and Hammurapi Rules documentation for more details.

You can now add more test cases, implement nuances. E.g. in our case we should, ideally, check if method argument is a reference to static final field, or enumeration member, which are as constant as literals.

Package

The final step is packaging for distribution. The package shall include:

• Compiled inspectors
• Third-party libraries used by inspectors
• Inspector set
• Documentation

Notes

Intermediate results and inspectors collaboration

Term 284Inspectors can work as a team using forward chaining. E.g. one inspector can infer intermediate Term 281conclusions, which then can be posted to other inspectors to draw final conclusions in the form of Term 283violations.

Language elements and source units are Attributable and inspectors can communicate by setting attributes of objects being inspected.

Finally, all inspectors can be looked up through the naming bus. As such one inspector can look up another inspector if needed.

Term 284Inspector vs. Term 273Loader

It is important to differentiate where to put some particular logic. Logic which is specific to the model, e.g. class hierarchy, resolving of variable references shall be in loaders. Inspectors shall contain only inspection logic, though it might be some times necessary to build sub-models. E.g. inspectors which check correct implementation of a pattern with multiple participants shall build a pattern model by resolving participating classes. Then each of participants can be checked for compliance with the pattern contract.