Whether you are an experienced KIUWAN user or you just got your account and have already made your first analysis, you may have noticed that, even with the large number of rules available for configuring your own quality model, there may be specific conditions and situations you might want to have into account for the project to analyze. If that is your case, you are in luck, because KIUWAN provides support for the definition, creation and analysis of custom rules.
In the series of post we begin today, we will review the entire process of creating custom rules, from setting up the development environment to executing our rules in KIUWAN, through specific examples of implementations that will help us to understand how to solve problems that arise during rules development and applying the utilities and tools we have available with the product.
First of all, we will need a KIUWAN account that has support for custom rules development. Check out the page to see the possibilities.
Once we have created our account, we download KIUWAN Local Analyzer. Intending not to make a long tutorial, we will omit explanations about downloading and using the analyzer. There is documentation available about this matter.
With KIUWAN local analyzer already downloaded, we will have access to KIUWAN Rule Developer tool, necessary to our rules development. Apart from this, we will need a code editor, any. Hereinafter, we will make the examples based on Eclipse, but the process is similar for any other IDE.
Setting up the IDE
A KIUWAN rule consist of two parts:
- Rule definition: a XML file with the needed metadata for the rule.
- Rule source code: implemented in Java, it is a class that contains the functionality that is executed when performing an analysis with the rule.
Then, in the IDE, we will create a new Java development project, establishing the run time environment in JavaSE-1.6. In the project classpath, we should include analyzer.jar and spring.jar libraries, which will be found in AGENT_HOME/lib.engine. We will also have the javadoc for the jar analyzer.jar in the path AGENT_HOME/development/doc/javadoc/analyzer-javadoc.zip. With the project inicially set, we have to establish a definitions directory, where the rules definitions created in KIUWAN Rule Developer will be stored.
Kiuwan Rule Developer
Kiuwan Rule Developer is a GUI tool that helps us to create, run and edit rules that can be integrated in KIUWAN analyzer. Executing it is very simple:
- In Windows, double click the file AGENT_HOME/development/rdev.cmd
- In Unix OS, run the script AGENT_HOME/development/rdev.sh
We should access our KIUWAN account.
The KIUWAN Rule Developer user interface is divided into three areas:
- Source code area (1): contains the source code the rule must analyze.
- Abstract Syntax Tree (2): where appears the tree describing the parsed source code.
- Execution panels (3): sections from where we can upload, create and execute rules, as well as xpath expressions or groovy scripts.
Linking KIUWAN Rule Developer to our IDE
We should set KIUWAN Rule Developer to synchronize it with our IDE, using the project we created before. Thus, simply click the ‘Configure IDE’ button and establish the paths for each requested field.
- “Build folder”: where our IDE builds the project.
- “Sources folder”: project source code.
- “Definitions folder”: directory we had previously created to store the rules definitions.
Creating a rule
With KIUWAN Rule Developer linked to the project defined in the IDE, we can start to create the definition of the first rule. In the execution panel called ‘Rule’, there is the ‘New’ button, which will open up a dialog box for the new rule. We should fill each field with the information that defines and describes the rule we want to implement, and give examples of both source code which represents a rule violation and what to do to avoid it.
After saving the changes, we will have two new files: the basic structure of the rule source code and the definition thereof, both located in the directories we had previously established.
Editing the rule template
Back to our IDE and updating it to visualize the new files, we will be able to take a look at what KIUWAN Rule Developer have generated: a .java file for the rule implementation and a .xml file with the necessary metadata for its execution.
The .java file will be the template generated for the rule and the element we should edit to add the source code that detects and notifies the rule violations. This section will be seen in depth in successive posts.
Once edited and saved the changes in the rule, if we have the IDE properly configured, it will generate the .class file associated in the ‘build’ directory we had indicated in previous steps.
Executing the rule in KIUWAN Rule Developer
Back to KIUWAN Rule Developer, now we need some source code on which we can test that our rule works and detects the violations correctly. The simpliest thing to do is using the same code example indicated when defining the rule metadata. We will place this information in the tool source code area and, after selecting the example specific language, we will click on the ‘Build AST’ button, generating the AST tree, which represents the code we are using as a test.
As before we were editing the specific metadata for our rule, that will be the rule currently loaded in the tool. So that, with one click on ‘Execute’, KIUWAN Rule Developer will automatically execute the rule we had previously compiled on the test code, showing the results obtained in ‘Rule execution results’ view.
We will be able to modify the rule implementation from the IDE and execute it in KIUWAN Rule Developer as many times as we need to obtain the desired results.
Uploading the rule in KIUWAN Quality Models Manager
Once we have ensured that the rule detects the cases we want, the next step is upload its definition. After accessing our KIUWAN account, we click on settings icon (on the top-right corner of the page) and we look for the ‘Quality Model Manager’ option. We have to create a new model (New model, Create from scratch) and then, from ‘Rules’ section, we click on ‘Install rule definitions’. At this point, we should upload the definition KIUWAN Rule Developer had generated in ‘definitions’ directory. After that, we should select the created quality model, add the new rule and click on ‘install’ to proceed with the installation of the rule in our library and in our quality model.
With the quality model already published, we will be able to associate it to one of our applications through settings icon, in the ‘Application Management’ option. We select the application we want to analyze and we establish the quality model that contains our custom rule from the drop down menu of ‘Quality Parameters’ section.
Running the custom rule analysis from KIUWAN Local Analyzer
For KIUWAN Local Analyzer to run an analysis on our application with the quality model and the rule we have created, we need the IDE to generate a .jar packaging our rule compiled file. That .jar must be placed in AGENT_HOME/lib.custom directory.
With all this, we are ready for the analysis. Following the documentation available for KIUWAN Local Analyzer, we will establish the project and the quality model and then the analysis will be run. We will be able to see its results in our KIUWAN account once the analysis is complete. Accessing ‘Defects’ section, we will be able to see the errors issued by our custom rule, developed using KIUWAN Rule Developer.
We have already reviewed the integration process of a custom rule in our analyzer, from setting up the development environment to running the analysis. Now we have to go into rules development itself: the implementation of those Java classes that represent the rules and run the checks to detect and report rule violations.
Along with local analyzer support, there is a very complete API usable for implementing rules. We will see it in detail in successive posts, so keep visiting us!