IBM Rational Software Analyzer IBM Rational Software Analyzer Writing custom rules This module covers the topic on how to write a custom rule for IBM Rational® Software Analyzer versions 7.0 and higher. Module objectives Module objectives Topics covered in this module: Rule Check Introduction to AST Nodes Parsing Nodes Writing the Rule Analyze Method Getting the Rational Software Analyzer Resource Getting the AST Nodes Doing the Work When you complete this module, you are now able to: Write a custom rule for Rational Software Analyzer This course covers eight topics. The first three topics provide you with information about a Rule Check, an introduction to AST Nodes and Parsing Nodes. The next few topics outline writing the rule, the Analyze Method, getting the Rational Software Analyzer resource, getting the AST Nodes and doing the work. When you complete this module, you will understand what an AST Node is and how it relates to Rational Software Analyzer. You will also be able to write a custom rule for Rational Software Analyzer. Rule check Rule check Rational Software Analyzer uses Eclipse technology for checking the rule. In order for Rational Software Analyzer to determine if a code file passes a rule or not, you need to parse it and verify its syntax. Eclipse handles the parsing of the code. Once it is parsed, you will write a Java™ class that will check those parsed code files. This will verify that is passes your requirements for the custom rule. This slide will cover three points. The first point lets you know that Rational Software Analyzer does not have its own code parser, rather is uses the existing Eclipse parsers. Secondly, Rational Software Analyzer uses the results of the parser pass to determine if a rule has passed or failed. And thirdly, you need to write your Java class to look for particular patterns in the code file to make a decision as to whether the file passes the rule. Introduction to AST nodes Introduction to AST nodes AST stands for Abstract Syntax Tree. It is the structure that Eclipse puts the syntax into after it is done parsing the file. These nodes are arranged into a tree. The nodes are assigned different types for different parts of the file. Expression – This generally is any line with an operator , for example =, +, - Name – This is a subclass of Express that defines the name of the variable Statement – This is what covers most every line. If and Else statements for example. Type – This covers primitive types like int, char and more complex ones like arrays. BodyDeclaration – This breaks down the contents of the Class, Method or other part that might have a body. This slide gives an Introduction to AST Nodes. Abstract Syntax Tree (AST) is the data structure that is the result of the Eclipse parser pass. The data structure itself is a product of the Eclipse project, but its purpose is to break code files down into a tree structure that represents the file fully. The tree will start at the highest, broadest scope and through the children of that top level node, create gradually narrower scoped nodes. These nodes will have different types for different parts of the code file, however everything that the parser encounters is represented somehow in this tree. Parsing nodes Parsing nodes Rational Software Analyzer uses the AST Nodes to define its rule checking behavior. By checking for particular patterns of nodes, Rational Software Analyzer is able to define the rule behavior. For example make sure that type nodes are always part of an expression node with a value nod. This can be used to make sure that all declarations are always initialized. When you define your class, you are defining a particular structure of AST Nodes that will encompass your rule Rational Software Analyzer uses this Abstract Syntax Tree to check its rule syntax. So when you are defining your rule for Rational Software Analyzer, what you are really doing is specifying a particular AST structure that will either be acceptable or unacceptable. So in fact checking the rule will involve traversing the tree and looking for a specific pattern. Writing the rule Create a new Java class in the plug-in project with the default values. Make sure that the class extends com.ibm.rsaz.analysis.codereview.java.AbstractCodeReviewRule Since your class is extending AbstractCodeReviewRule then your class must include the analyze method as required by that abstract class Writing the rule In the previous set of slides, you have set up the custom plug-in, but you did not create the Java class. You already have all the plug-in blocks in place, but you need to write the actual steps to check the code. The Java class needs to extend the AbstractCodeReviewRule object. This Rational Software Analyzer object contains the analyze method which is what Rational Software Analyzer will call to start the scan. Therefore you are putting all of your analysis code there. The analyze method 7 The analyze method passes in an AnalysisHistory object. This is where you append the history of your rule. So the first action you need to take is to get the history id, which is: String historyID = history.getHistoryId(); You will require historyID at the end of the method when you have determined there is actually something to report on The analyze method The analyze method will pass in an AnalysisHistory object. This will tell the analyze method what the previous history of the rule scan is. The first action you should always take when you are implementing the rule is to acquire the historyID, so you know where to put the results of this rule. You will reference this later on when you decide whether to add something to your history for this rule. Getting the Software Analyzer resource Getting the Software Analyzer resource You now know what the historyID is, but you need to get connected to the Rational Software Analyzer ‘stuff’. This is done by using the getProvider method like so: resource = (CodeReviewResource) getProvider().getProperty(historyId, CodeReviewProvider.RESOURCE_PROPERTY); The resource reference is your gateway to the Rational Software Analyzer methods API. You now have the historyID, but you need more from Rational Software Analyzer. You need to get access to the Rational Software Analyzer API and its associated objects. The way to do this is through the getProvider method. By using the syntax here you are able to get the Rational Software Analyzer CodeReviewResource object which is your window into all things Rational Software Analyzer. Getting the AST nodes Getting the AST nodes Now that you have your Rational Software Analyzer resource, you need to get into the actual algorithm to test your rule. Here is an example that will gather all the Declaration AST nodes in the code file: listDeclaration = resource.getTypedNodeList(resource.getResourceCompUnit(), CodeReviewVisitor.TYPE_IASTDeclaration); Check the JavaDoc for the full list of the possible AST Nodes that can be gathered from the resource. They will all be part of the CodeReviewVisitor object. The resource reference is set up and ready to go. The last thing you need to do is set up the code to check the pattern to verify if the rule passes or fails. First you need to collect the AST Nodes that are of interest to you. In the example here you are gathering an array of nodes of the ASTDeclaration type. From the array you can sift through looking for particular declaration nodes of interest. Doing the work Doing the work You have your collections and ASTNodes. All you need to do now is the actual work to determine the action of your rule. The ASTNodes are part of a full tree describing the statement. It can be broken down into its constituent parts. That is how to get to the parts you need for your rule. Now that all levels of the ASTNode are available and you are able to filter them, the implementation of the rule is up to you. At this point you have the arrays of AST Nodes. Now you have all the parts you need to start checking rules. By checking for particular patterns of nodes in the arrays you collect, you can decide what actions to take to determine the success or failure of your custom rule. Filtering nodes Filtering nodes The resource will return the collection of ASTNodes, but declaration is a fairly broad category. RSAR includes a method to filter the collection to only contain those nodes that you need. To use the filter, you first need to set up an array like so. IRuleFilter[] typeFilter = {new StructTypeRuleFilter(false), new UnionTypeRuleFilter(false) }; This particular filter array will look for and exclude those Declaration nodes of types Struct and Union. To run this filter against a collection, write something like: ASTHelper.satisfy(listDeclaration, typeFilter); As a result of this, the listDeclaration collection will now not contain Structs or Unions. Rational Software Analyzer provides an additional filter method on top of those provided through the ASTNode methods. The IRuleFilter allows not only the particular type of ASTNode to be filtered but it can get more specific implementations of the ASTNode. For example, both Struct and Union declarations are ASTDeclaration ASTNode types. Without iterating through the entire array of Declaration Nodes you do not know what implementations there were. By using the satisfy method with the IRuleFilter array you can check that the collection either inclusively or exclusively contains those particular nodes. Summary 12 Summary Rule Check Introduction to AST Nodes Parsing Nodes Writing the Rule The Analyze Method Getting the Rational Software Analyzer Resource Getting the AST Nodes Doing the Work This module provided an overview of writing custom rules in Rational Software Analyzer. You should now be familiar with knowing what an AST Node is and how it relates to Rational Software Analyzer. You are now able to write your own custom rule. Additional resources 13 Additional resources Additional resources on ibm.com http://www-01.ibm.com/software/awdtools/swanalyzer/enterprise/index.html http://www-01.ibm.com/software/awdtools/swanalyzer/enterprise/support/ http://www.ibm.com/developerworks/rational/library/08/0429_gutz1/index.html?S_TACT=105AGX54&S_CMP=B0612 Additional resources can be found on the ibm.com Web site and in the Whitepaper on “Static analysis IBM Rational Software Analyzer: Getting started”. Feedback Feedback Your feedback is valuable You can help improve the quality of IBM Education Assistant content to better meet your needs by providing feedback. Did you find this module useful? Did it help you solve a problem or answer a question? Do you have suggestions for improvements? Click to send e-mail feedback: mailto:iea@us.ibm.com?subject=Feedback_about_rsar_writing_custom_files.ppt This module is also available in PDF format at: ../rsar_writing_custom_files.pdf You can help improve the quality of IBM Education Assistant content by providing feedback. Trademarks