Java custom functions

When creating checkers with custom functions, use the --kast-library option of kwcreatechecker. This will generate a MyFunc.java file to contain your plug-in source, and a plugin_functions.xml file to register the custom functions contained in the jar.

Add your source to the MyFunc.java file

Each custom Java function should be implemented as a separate class, extending one of three abstract classes: CustomIntFunction, CustomBoolFunction or CustomTreeFunction. Every such class should have an associated name, which corresponds to the function name in the KAST expression. When calling a custom function in a KAST expression, you can either specify a single argument of type 'tree' or specify no arguments at all. In the latter case, the current node will be processed.

• If you need an integer custom function, define a new class that extends com.klocwork.jxpath.CustomIntFunction abstract class overriding its method:

  public long evaluate(com.klocwork.javaapi.jtree.TreeNode node);

• If you need a boolean custom function, define a new class that extends com.klocwork.jxpath.CustomBoolFunction abstract class overriding its method:

  public boolean evaluate(com.klocwork.javaapi.jtree.TreeNode node);

• If you need a custom function that returns a value of type 'tree', define a new class that extends com.klocwork.jxpath.CustomTreeFunction abstract class overriding its method:

  public com.klocwork.javaapi.jtree.TreeNode evaluate(com.klocwork.javaapi.jtree.TreeNode node);

Your custom function should be implemented in this 'evaluate' method. AST nodes can be accessed using classes from the com.klocwork.javaapi package.

plugin_functions.xml file

Classes implementing custom functions should be packed into one or several jars (plug-ins). Each jar must have a plugin_functions.xml file at the top level of its inner file hierarchy. This file registers all custom functions contained in the corresponding jar.

The plugin_functions.xml file has the following format:

<plugin> <function name="name1" class="class1"/> <function name="name2" class="class2"/> ... </plugin>

Here name1, name2, etc. are the names used to refer to the custom function in the KAST expression, while class1, class2, etc. are fully qualified names of associated classes. For example:

<plugin> <function name="isAssignment" class="com.klocwork.plug-ins.IsAssignment"/> <function name="isShift" class="com.klocwork.plug-ins.IsShift"/> <function name="getMostLeftArg" class="com.klocwork.plug-ins.GetMostLeftArg"/> </plugin>

Test your KAST expressions

KAST expressions containing custom functions must be tested using kwjava. Checker Studio does not support custom functions.

Use the --xpath-library option to specify the name of the library that contains the functions.

The example below specifies the text file containing the KAST expression and the library name:

kwjava --xpath-file myJKAST.txt --xpath-library "myJKASTCustomFunctions.so" Testcase.java

Build the checker

To build the checker library from the checker directory (<CHECKER.CODE>), run:

ant install

This generates a <CHECKER.CODE>.zip file.

Desktop testing

Once the jars are generated, they should be placed into your <User_install>/plugins directory, where you can test them locally before they are formally deployed.

What's next?

The checker now can be deployed to the Klocwork server, in which case it will be made available to all Klocwork connected desktops when they synchronize with the server. It can also be deployed to individual desktop installations.

To learn how, see:

• Deploying custom checkers