Overview

New custom Cobol coding rules can be added into Sonar. There are two different ways to achieve it:

• Writing an XPath rule directly via the web interface
• Writing a plugin that is a small Java piece of code

The COBOL plugin parses the source code, creates an Abstract Syntax Tree (AST) and then walks through the entire tree. A check can subscribe to be notified every time a type of node is visited. As soon as the check is notified, it can navigate the tree around the node and log violations if necessary.

Writing an XPath Rule

New Cobol coding rules can be defined directly via the Sonar web interface using XPath. See complete documentation here.

The SSLR Cobol Toolkit can be downloaded here.

Writing a Plugin

Writing new COBOL checks is a six-step process:

• Create a standard Sonar plugin.
• Attach this Sonar plugin to the Sonar COBOL plugin (see the pom.xml file of the provided sample project).
• Create as many custom COBOL checks as required by extending com.sonarsource.api.ast.COBOLAstCheck and add them to the previous checks repository.
• Generate a Sonar plugin jar file.
• Place this jar file in the extensions/plugins directory.
• Restart the Sonar server.

Template

To get started, you can use a simple sample project as a template. This is a straightforward check. This check will basically log a violation on every file at line 5. There are only three prerequisites to get it working:

• Install Maven.
• Build the project by running mvn install. This will generate a Sonar plugin jar file in the target directory.
• Add your newly created jar into the /extensions/plugins directory of the Sonar server and restart Sonar.

If you now look at the quality profiles, you will find the new check. Don’t forget to activate it! Run an analysis, and you will find that a violation was logged on line 5 of every file.

Subscribing to a NodeType

Very often when writing a check, you will want to subscribe to a NodeType. A NodeType can be either a rule of the grammar or a keyword of the language. As an example, here is the code of the implementation of the “Avoid using Merge statement” check:

public class MergeStatementUsageCheck extends CobolAstCheck {

  public void init() {
    subscribeTo(getCobolGrammar().mergeStatement);
  }

  public void visitNode(AstNode node) {
    log("Avoid using MERGE statement.", node);
  }
}

Note that CICS and SQL grammars can be accessed using getCicsGrammar() and getSqlGrammar().

Check Lifecycle

A check can optionally override six methods inherited from the COBOLAstCheck abstract class. Those methods are called sequentially in the following order:

• public void init() {…}: This method is called only once and should be used to subscribe to one or more NodeType(s).
• public void visitFile(AstNode astNode) {…}: This method is called on each file before starting the parsing.
• public void visitNode(AstNode astNode) {…}: This method is called when an AstNode matches a subscribed NodeType (see Subscribing to a NodeType) and before analyzing its content.
• …
• public void leaveNode(AstNode astNode) {…}: This method is called when a nAstNode matches a desired NodeType (see Subscribing to a NodeType) and after analyzing its content.
• public void leaveFile(AstNode astNode) {…}: This method is called before exiting a file.
• public void destroy() {…}: This method is called before shutting down the check.

The different kind of log(…) methods, used to log a violation, should be called only inside the visitFile(…), visitNode(…), leaveNode(…) and leaveFile(…) methods. Indeed, the file context isn’t known when the init() and destroy() methods are called, so the violation can’t be associated to a file.

More advanced features are documented in the API Javadoc.

Navigating the AST (Abstract Syntax Tree) with the SSLR COBOL Toolkit

When starting to write a new COBOL check, the main difficulty is to understand the COBOL AST in order to know which NodeType(s) need to be visited. This can be achieved by using the SSLR COBOL Toolkit, a Swing application that enables loading a COBOL file and displaying its representation as an Abstract Syntax Tree.

Each node in the AST is a COBOL grammar rule and each leaf in the AST is a COBOL token. Let’s say you want to visit the node ‘ifStatement’. In this case, the init() method of your COBOL check must contain the following statement: “subscribeTo(getCOBOLGrammar().ifStatement);”.