This guide will help you executing a custom rule analysis in Kiuwan Analyzer. If you need more information on programming a rule, please check the Getting Started with rule development page. 

You can also find usefull and step-to-step guide on how to develop and run custom rules in the following posts of Kiuwan Blog

1. Rules development (I): Where do we start?
2. Rules development (II): basis for implementation
3. Rules development (III): debugging custom rules
4. Rules development (IV): Basic API – navigating through the AST
5. Rules development (V): Query API
6. How to create new zero-code Kiuwan rules

Prerequisites

First of all, you will need a suitable Kiuwan account for developing rules. 

Once you have a Kiuwan account, proceed to download Kiuwan Local Analyzer. If you have already downloaded the analyzer, but you cannot find a development folder, please upgrade or reinstall the Kiuwan Local Analyzer.

The same prerequisites that apply to Kiuwan Local Analyzer apply to Kiuwan Rule Developer, please check them out before continuing to the next section.

All in all, you will need two tools for rule development:

• Kiuwan Rule Developer. This is included with the latest Kiuwan Local Analyzer.
• A code editor you feel comfortable with. This can be your favourite IDE, like Eclipse, iDEA or a text editor like Vi or Emacs.

Preparing your IDE

The rules that kiuwan executes are created using the Java language. A kiuwan rule is composed by:

• A rule definition: an XML file where the rule metadata is kept.
• The rule source code: that contains the Java code that will be executed when running the rule.

In this section we will create a Java project in Eclipse that will contain both parts of the rule. We will use for this guide Eclipse Luna Standard, but you can use any Eclipse version or any other IDE or editor you like following an equivalent process:

1. Create a new Java project choosing File → New → Java Project...
   1. Choose a name for your project.
   2. Set the Java execution environment to JavaSE-1.6.
2. Click Next. We will now configure the project libraries needed to create kiuwan rules.
   1. Go to the Libraries tab.
   2. Click the "Add external JARs..." button.
   3. Go to the folder where you installed Kiuwan Local Analyzer (AGENT_HOME) and click on the lib.engine subfolder.
   4. Choose the analyzer.jar and the spring.jar files.
   5. Once the jar files are added to the libraries, click on the analyzer.jar drop down icon so the jar configuration can be seen.
   6. Select the "Javadoc location" entry and click "Edit...".
   7. Click the "Javadoc in archive" and then the "External file" radio buttons.
   8. Click on the "Browse..." button and look for the AGENT_HOME/development/doc/javadoc/analyzer-javadoc.zip file and click the "Open" and then the "OK" buttons.
   9. Click the "Finish" button in the New Java Project wizard to end the project configuration.
3. Once the project has been created, create a new folder called "definitions" under the new project. We will use this folder to store the rule definitions created by Kiuwan Rule Developer.

Step	Screenshot
1.
2.
3.

This is all what we need in the IDE part. Now we will launch Kiuwan Rule Developer and work simultaneously with both tools to create rules.

Kiuwan Rule Developer

Kiuwan Rule Developer is a GUI tool that will help you to create, run and edit rules that can be executed in a Kiuwan analysis.

Once you have installed or upgraded Kiuwan Local Analyzer, follow this steps to run Kiuwan Rule Developer:

• In Windows, double click the script located in AGENT_HOME/development/rdev.cmd.
• In Unix OS, execute the AGENT_HOME/development/rdev.sh script.

You will be asked for your Kiuwan account username and password to enter Kiuwan Rule Developer. 

Kiuwan Rule Developer user interface is divided in three areas:

1. Top left: source code area: contains the source code the loaded rule will be run against.
2. Top right: AST (Abstract Syntax Tree) area: where the tree describing the parsed source code will be shown.
3. Bottom: the execution panels: where you can load, create and execute rules, xpath expressions and groovy scripts.

Wiring Kiuwan Rule Developer with your IDE

The first thing we will do is configure Kiuwan Rule Developer to synchronize with an IDE. In this case, we will use the Eclipse project we have created before.

1. Click on the "Configure IDE" button on the bottom right of Kiuwan Rule Developer
2. In the Build Folder field, type or look for the folder where Eclipse builds the project, in our case, /krd/kiuwan-rules/bin
3. In the Sources Folder field, type or look for the folder where Eclipse stores the source code, in our case, /krd/kiuwan-rules/src
4. In the Definitions Folder field, type or look for the folder we have created to store the rule definitions, in our case, /krd/kiuwan-rules/definitions

Creating a rule

Once the IDE and Kiuwan Rule Developer are wired, we can create a new rule definition.

1. Click on the "New" button. The new rule dialog will appear.
2. We will create a rule to check the usage of System.out.print* methods in Java language, so we fill the fields conveniently.
   1. Fill the "Definition" fields with values that fit the rule purpose.
   2. Fill the "Code examples" text areas with an example of the violation the rule will detect and how to fix it.
3. Once the fields are filled, click the "Save" button.

Step	Screenshot
2a.
2b.
3.

After saving the rule, two files will be created:

• The base source code of the rule, located in the previously configured build folder.
• The rule definition file, located in the previously configured definitions folder.

Once the new rule dialog is closed, Kiuwan Rule Developer will be prepared to execute your rule's implementation. But we first need to create that implementation.

Editing the rule template

Back to Eclipse, you should refresh to project contents to see the files created by Kiuwan Rule Developer.

In our example, Kiuwan Rule Developer has created the following files:

• The rule base code: src/com/mycompany/kiuwan/rules/java/CheckSystemOut.java
• The rule definition: definitions/COM.MYCOMPANY.JAVA.CHECKSYSTEMOUT.rule.xml

If you open the rule base code file, you will see the basic rule template. This is where you should add the code to detect the violations you want to find in your Java code. For more information on this topic, check the Getting Started with rule development guide.

In our example, we want to detect the uses of System.out.print(String) and System.out.println(String) in Java code. So this will be the source code for our rule:

Eclipse compiles the rules as we save changes in the file (you should have the "Build automatically" option turned on, under the Project menu), so we already have a .class file in the build folder that Kiuwan Rule Developer can execute.

Executing the rule in Kiuwan Rule Developer

Switch back to Kiuwan Rule Developer.

We will need a source code to test the rule against. We will copy the code example we entered when we created the rule in the new rule dialog:

1. Copy or write down the source code in the "Test source code" tab.
2. Click on the "Generate AST" button to parse the file and create an Abstract Syntax Tree.
3. Click on the "Execute" button to see the results of applying the rule to the test code.

As you can see in the previous screenshot, the "Rule execution results" tab will be automatically selected with the results of applying the rule to the test source code. In our example, one violation will be detected in line 4. This line uses one of the methods the rule looks for.

You can modify the rule in your IDE and execute it in Kiuwan Rule Editor as many times as you need until you are satisfied with your rule's implementation. Kiuwan Rule Editor automatically detects changes in the compiled code, as long as you have correctly configured your IDE as we did in the previous sections.

Debugging the rule in your IDE

Kiuwan Rule Developer allows you to remotely debug the rule you are editing in your IDE while it is being executed.

If you want to debug your rules, you should launch Kiuwan Rule Developer in debug mode. To do so, open a console and type:

Windows:

> AGENT_HOME/bin/agent --development debugPort=4444

Unix:

> AGENT_HOME/bin/agent.sh --development debugPort=4444

This will launch Kiuwan Rule Developer and wait for a remote debug tool to be attached on the specified port (in the previous examples, port is 4444).

Note that the application will not be launched until the remote debug tool is detected by the process. Make sure the specified debug port matches the one configured in your remote debug tool. If the attachment is successful, you will see a red label indicating the current debugging port in the bottom left of the Rule Developer window:

Uploading a rule to Kiuwan Quality Models Manager

Once we are happy with our rule, the next step is to upload the rule definition to Kiuwan.

1. Access https://www.kiuwan.com and log in to your Kiuwan account.
2. Go to Model Management module (click on the menu at top right of the screen) .
3. Create en empty quality model (New model, Create from scratch).
4. Go to the "Rules" section and click on the "Install rule definitions" menu option.
   1. Click the "Upload" button and select the rule definition that Kiuwan Rule Developer has created in the definitions folder.
   2. Click "Next" and click on the quality model you have just created to add your rule to it.
   3. Click on the "Install" button to proceed.
5. Your rule will be installed into your library and will be added to the new quality model.
6. Publish the quality model so you can assign it to one of your applications for analysis.
7. Click on the configuration icon (top right of the screen) and click on the Application management option.
   1. Select the application you will analyze with the new quality model that contains your custom rule.
   2. Open the drop down menu in the Quality parameters section and select the quality model you have created in step 3.

Step	Screenshot
3.
4.
4.a.
4.b.
4.c.
5.

After following the previous steps, everything should be prepared to run a new analysis with Kiuwan Local Analyzer.

Executing a custom rule analysis with Kiuwan Local Analyzer

Once your application has assigned the new quality model, we have to create a package with our rule so Kiuwan Local Analyzer can execute it.

1. In Eclipse, right-click on the rules project and choose Export... Java → JAR File.
2. Browse for the lib.custom folder under the Kiuwan Local Analyzer folder and write a name for your rules jar archive. For example: AGENT_HOME/lib.custom/my-kiuwan-rules.jar
3. Click "Finish" button to export your rules project.

Now everything should be prepared to launch your analysis.

The next step is to run Kiuwan Local Analyzer and analyze your application. If you need more information on this topic, please read the Kiuwan Local Analyzer page.

We will use a test application made of two Java classes. One with a rule violation, one with no violations. We will call this application "Test application".

Follow this steps to analyze the application in Kiuwan Local Analyzer:

1. Run Kiuwan Local Analyzer by double clicking in the AGENT_HOME/kiuwan.cmd script in Windows or by running the AGENT_HOME/kiuwan.sh script in Unix OS.
2. Log in with your Kiuwan account.
3. Select the application you want to analyze with your custom rules. In our case, this will be "Test application".
4. Select the source code you want to analyze and click "Next" button.
5. Click on "Analyze" button. You will see in the status bar (bottom of the window) that Kiuwan Local Analyzer first downloads the quality model associated with the selected application, in our example, "My company quality model" and, then, analyzes the source code you have previously configured.
6. Click on "View results" button to access Kiuwan site and see the results.

Step	Screenshot
3. and 4.
6.

Viewing the analysis results

Once the analisis is done, you can check the results by clicking on "View results" button. A browser will be open and Kiuwan web page will appear with the results of the analysis.

If you access the "Defects" section, you should see a defect emitted by your own custom rule you have just created using Kiuwan Rule Developer:

Summary

In this quick start guide we have seen how to create, modify, pack, install and execute a custom rule for Kiuwan. We can summarize the needed steps in the following list:

1. IDE: create a project and configure it to be used with Kiuwan Rule Editor.
2. Kiuwan Rule Developer: wire with your IDE.
3. Kiuwan Rule Developer: create a custom Kiuwan rule.
4. IDE: implement your custom rule from the automatically created template.
5. Kiuwan Rule Developer: execute and check the results of your custom rule.
6. Kiuwan: install your custom rule and use it in a quality model.
7. IDE: pack your custom rule code and deploy it to Kiuwan Local Analyzer.
8. Kiuwan Local Analyzer: execute an analysis of your application.
9. Kiuwan: view the results of analyzing your application with your custom rule. 

What's next?

The following steps you should follow are:

• Read the Getting Started with rule development guide.
• Read the Rule Development Manual, found under the AGENT_HOME/development/doc folder.
• Check the rule examples included under the AGENT_HOME/development/doc/samples folder.

Happy custom analyzing!