Quick Start Guide

Maxence Vanbésien edited this page Jul 29, 2013 · 14 revisions

AST Validation Rules: Quick Start Guide

Prerequisites

Before continuing, it is very important to have an AST knowledge.

A good article can be read at http://www.eclipse.org/articles/article.php?file=Article-JavaCodeManipulation_AST/index.html

Moreover, the usage of the AST Tree View within Eclipse could be really helpful to understand AST structure & API. It can be downloaded at http://www.eclipse.org/jdt/ui/astview/index.php

AST Validation Rules Engine

The AST Validation Rules Engine is an implementation that will gather AST Rules (that rely on the AST Visitor pattern implementation) through Extension points, to execute them against Java source code.

This means that the engine itself will NOT contain any rule.

The source code can be checked out at : https://github.com/awltech/eclipse-ast-validation.git. The project is tycho-compliant, meaning that you will check out the parent project only, and you will require a maven import to install all the children project. Below, the list of projects and their meaning

About the source code...

  • net.atos.jdt.ast.validation.engine: Eclipse plugin containing the engine implementation. Processes an extension point to gather all client rules and execute them on Java source code
  • net.atos.jdt.ast.validation.feature: Eclipse feature (used for the packaging & installation of the application)
  • net.atos.jdt.ast.validation.parent: Parent project of the application. Contains all the others projects listed here.
  • net.atos.jdt.ast.validation.repository: Eclipse Update Site (used for the packaging & installation of the application)

As said above, the implementation itself is located in the net.atos.jdt.ast.validation.engine plugin, and this is what we'll concentrate on, from now on.

A few words about the rules...

A rule will be a Java class that inherits from the net.atos.jdt.ast.validation.engine.rules.AbstractASTRule

Roughly, this class is an AST Visitor (it extends the org.eclipse.jdt.core.dom.ASTVisitor) that proposes additional API such as

  • void addErrorMarker(ASTNode nodeToHighlight, String message)
  • void addInfoMarker(ASTNode nodeToHighlight, String message)
  • void addWarningMarker(ASTNode nodeToHighlight, String message)

This just means that, to implement a rule, you have to implement an AST Visitor, and each time you find a pattern that should lead to a specific message, you have to call one of the methods above.

Each rule will be stored within an internal class named ASTRulesRepository. It basically contains an ID, a Marker ID (used to identify the problem type such as "Maven Problem" or "Java Problem") and a context.

In Eclipse, a marker ID is not just a String... It is an object that needs to be defined in an Extension Point too. To prevent users from the need to create one, one default one has been put into the Engine, and is described as follows:

  • id: net.atos.jdt.ast.validation.engine.diagnostic
  • name: AST Validation Problem

This context is a class that extends the net.atos.jdt.ast.validation.engine.rules.AbstractProjectContext. It aims is at proposing a programmatic way to define condition based on the project that contains the validated source. This simply means that the clients subclassing this abstract class will have to implement the boolean validate(ICompilationUnit) method, and before each execution of a Rule Repository, this method will be executed to know whether the bag of rules should be applied.

... Just one trick about the AbstractASTRule implementation. Internally, the visit(CompilationUnit) method needed to be implemented for internal behaviour, and so, it has been made final. Now, if you'd like to do some check/computation on the CompilationUnit itself, you can use the visit2(CompilationUnit) method, called by the previous one.

A word about Java Building...

Typically, Java validation is performed on Java source when the Compilation Unit (i.e. the file that contains the source) is saved within Eclipse.

The have our rules executed on the same source, following the same process, an Eclipse project builder has been proposed to help with the manager & installation of builder. This builder can be used as it, and it will accept all the AST Rules Repositories. Its name is net.atos.jdt.ast.validation.engine.ASTValidableBuilder. Of course, this builder can be used for inheritance, meaning that you can define your own builder that focuses on your own rules.

Extension point schema

Please find below the extension point schema:

img1

TIP: This is here, when defining the Repository, that you can specify the internal problem marker identified by net.atos.jdt.ast.validation.engine.diagnostic

Contributing Rules

Now, this is over for the theoretical part. And we'll see, through an example, how to contribute rules to this engine.

As an example, we'll take one validation rule for validating that, in source code, we don't have try/catch blocks with empty catch block.

Creation of a new Eclipse plugin

At first, I will use the standard Eclipse wizards to create a new Eclipse plugin. Then, once created, I will edit the MANIFEST.MF file to update the dependencies. On the screenshot, the three last dependencies were added.

img2

Creation of a rule

To create a rule, I need to create a java class that inherits from net.atos.jdt.ast.validation.engine.rules.AbstractASTRule. Then, using the AST & AST Visitor APIs, I implement the pattern, as follows:

img3

Here, thanks to the AST Visitor pattern, you can remark that it is not up to you to look for catch clauses within the source code... This is why it is this powerful !

Contributing the rule

Now, we need to register the implementation into the runtime, and this is done by contributing to the extension point proposed by the engine.

So at first, in the MANIFEST editor we previously opened, I create an extension point contribution and a repository in it (doable via right click). Then by right clicking on the created repository, I can create a rule. When created, I fill the implementation field with the class I've created earlier.

img4

The rule is now referenced into my engine ! Easy, isn't it ?

Defining the custom marker

The screenshot below describes the extension point that needs to be contributed. The structure is always the same and can be, of course, reused. What is important is that, as displayed, you fill the ID & name attributes of the marker, with the one defined in the repository.

img5

... And now we can test !

In the forked eclipse, you can now add the builder instance within the .profile file, and clean the project to see the message appear in the problems view!

img6

Finally, as for the EMF Validation Framework, the default implementation comes with a Preference Page that allows the user to administrate the rules he has deployed in his workspace.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.