Diagnose the problem

Typically, the tuning process begins with an inconvenience in the form of a false positive.

For example, you consistently notice that your analysis results list a specific issue type, for example, NPE.RET, that you don't consider to be an issue. The Klocwork traceback feature is a good place to start. The screenshot below is from Klocwork Desktop Java Plug-in for Eclipse:

When you examine the available Klocwork traceback information for the issue, you notice that there's a validation in the traceback or near it, but the issue is still being detected.

Use traceback to help you determine the criteria by which code paths are to be added or eliminated from the NPE.RET checker's consideration.

Other criteria to consider to reduce false positives are the identification of validation libraries, assertion libraries, termination libraries or exception libraries.

Once you identify the criteria, then you must communicate them to the engine in the form of a Java knowledge base file (.jkb).

Declare the criteria in a .jkb file

Java knowledge base files are how you educate the checker about your data-flow criteria. A simple text file with the .jkb extension is where you 'declare' your criteria to the checker by including the methods of interest and then marking them up using specific Java knowledge base (JKB) annotations to indicate to the checker how they should be handled.

The most common tuning annotations are @CheckTrue, @CheckFalse, and @Check for reducing false positives. The required tuning annotation, regardless of whether you are reducing false positives or detecting additional issues, is @Bind, which links the specified methods or all methods in a class (depending on where you place the binding in the file) to the specified checker.

When creating .jkb files to tune analysis, there's a great deal of flexibility in the number of .jkb files you can create. You can create one .jkb per class, which is how the examples and tutorials in this guide are set up.

You can create one .jkb just for validation, and one for security. You can also create a multi-sectional knowledge base for a whole project using a package statement as the transitional device.

Klocwork Desktop Java Plug-in for Eclipse and IntelliJ IDEA enables you to create a Java knowledge base file from the editor. The selected method is copied into the JKB file where you then add the appropriate JKB annotations. Once created, the JKB file is already contained in the project or workspace, thereby removing the need to import it.

For Eclipse, you can select multiple methods for your JKB file in the Outline view. In IntelliJ IDEA, you select multiple methods from the Structure view.

Once you identify the issue (checker) and the criteria you need to communicate to the checker to prevent it, you:

1. Create a text file with the .jkb extension.
2. In the text file, describe the method signature.
3. Add a knowledge base annotation, for example, @CheckTrue. For a high-level description of Java knowledge base records commonly used for tuning, see Knowledge base annotations.
4. Bind the record to the checker, for example, with the @Bind annotation.
5. Import the knowledge base into a project.
6. Test the knowledge base with kwcheck.
7. Edit the method and/or annotation as needed.
8. Add another method, annotate it, and bind the method to the checker.
9. Test until you are satisfied with your results.
10. Use and share your new knowledge base.

Before you create a knowledge base file, you need to decide if you're going to create one .jkb per class (which is the approach used in the tutorials and examples in this guide) or whether you want to create one .jkb for validation or security, etc.

You can also use a multi-sectional .jkb for a whole project in a multi-sectional knowledge base file. For more information, see 'Using multi-sectional knowledge bases' below.

To manually create (or edit) a knowledge base file:

1. Create a new text file with the extension .jkb.
2. Using the editor of your choice, add the method signatures you need to identify to the checker and then add annotations as described in Knowledge base annotations to indicate to the checker how each is to be handled. Each annotation is one line of the file.

Using multi-sectional knowledge bases

You can specify only one package declaration for a Java source file, and you cannot override imports after the imports block is finished. This works well for highly modular Java source code, but it does not fit well the purposes of the knowledge base, where sometimes you want to specify the knowledge base for a whole project or library.

You can use more than one package declaration in a .jkb file. These package declarations split the .jkb file into multiple sections with independent package and import declarations.

Example

package java.util;


import java.util.*;

interface Entry<K,V> {  
   @Source("return") K getKey();
}

package java.io; // Here starts another section

import java.net.URI;
import java.net.URL;

public class File {  
   @Source("return") int getPrefixLength();
}

import javax.swing.*; // Here starts another section

class About 
   @Source("return") JFrame getFrame();
}

To describe classes which are not in any package, use "package;" as shown here:

@BindAll("ERROR")


class AKB {    
   void a(@Sink String s);
}

package java.lang;

public class String {  
   @Source("return") java.lang.String trim();
}

package;

class BKB {    
   void b(@Sink String s);
}

To describe the method signature that the checker should consider in its analysis, for example identity validation:

1. Write the package declaration of the class containing the method of interest (or copy it from the real class).
2. Write or copy the declaration of the class or interface that contains the method of interest. The declaration has the following format:

   (modifiers)* ('class'|'interface') CLASS_NAME

3. Write or copy the signatures of the methods of interest inside your class declaration.

Example method signature description

Let's say we want to describe a few search methods from the javax.naming.directory DirContext. The method signature might look like the following:

package javax.naming.directory;


import javax.naming.*;

public class DirContext {  
   public NamingEnumeration<SearchResult> search(Name name, String filter, SearchControls cons)
      throws NamingException;

   public NamingEnumeration<SearchResult> search(String name, String filter, SearchControls cons) 
      throws NamingException;

}

The following annotations are those most commonly used to mark up your source for tuning Java analysis.

• @Check
• @CheckTrue
• @CheckFalse
• @Bind
• @BindAll

To make troubleshooting easier, it's best practice to:

• identify one method signature and add one annotation at a time, typically @Check, @CheckTrue, or @CheckFalse
• use @Bind to bind one or more methods to a specific checker
• test your knowledge base to determine if edits are needed
• identify the next signature method in the .jkb for the checker's consideration, annotate as you see fit, and re-test

You must use the @Bind (or @BindAll) annotation to bind knowledge base entries to specific checkers. Bindings are an integral part of tuning Java analysis with knowledge bases because they link the behavior you specify in the knowledge base with the checker you want to modify.

To apply your new configuration file to the integration build analysis, import it into a project or the projects_root. The file will be synchronized to connected desktops.

To apply your knowledge base file to a standalone desktop project, see Customizing your desktop analysis.