In this topic:
Java knowledge base (JKB) Java knowledge base tuning workflow diagram Creating a JKB file Editing a JKB file Tuning Java analysis in Eclipse Create a Java Knowledge Base file in Eclipse Example: Tuning in Eclipse Tuning Java analysis in IntelliJ IDEA Walk-through: Handling an NPE.RET false positive Troubleshooting JKB annotation errors Tutorials - Tuning Java analysis

Tuning Java analysis

A knowledge base file is the mechanism used to customize specific checkers by providing Java Path checkers with more context about your code system in order to:

reduce false positives in Klocwork analysis results, or
increase the reporting of specific issues of concern

Using a Java knowledge base file (.jkb), you 'mark up' your source to provide these checkers with the context they need to:

evaluate the validity of a particular issue along specified code paths to reduce false positives, or
identify code paths that need to be taken into consideration to detect issues of interest that were previously undetected (false negatives).

Java Path knowledge base files are written in JKB format, which is a Java-like declarative language for knowledge base specification.

To reduce false positives, the traceback feature in Klocwork analysis results helps you pinpoint the source to include in your .jkb file in order to achieve your objective.

Tuning to reduce false positives is by far the most common tuning scenario. Tuning to reduce false negatives is more of an extensibility activity. For more information about creating your own Java Path checkers, see Creating Java Path checkers.

Note: Tuning is available only for Java Path checkers.

For your tuning changes to take effect, you need to run a full build analysis.

Tuning Java analysis through knowledge bases

Java knowledge base (JKB)

A Java knowledge base (.jkb) file is the mechanism that tunes specified Klocwork issue checkers to reduce false positives (or less commonly false negatives) in your Java analysis results.

You'll also come across JKB files when you create your own Java Path checker.

The JKB file contains code paths that should be added to or eliminated from the checker's consideration.

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

Once you identify the criteria, then you must communicate them to the engine using a JKB file that contains:

the methods of interest to you
JKB annotations that indicate how these items are to be handled; for example:
@Bind (to specify which checker should be tuned)
@Check, @CheckTrue, @CheckFalse, and @Wipe (to specify data validation to reduce false positives)
@Source, @Sink, and @Prop (to report more issues)

Note: Since the JKB file can be created from your project workspace, you don't have to import it.

For more information about annotations, see Java knowledge base reference.

Java knowledge base tuning workflow diagram

Creating a JKB file

Click the issue in the Klocwork for Java view to see it highlighted in source code. (You can also use traceback information in the lower right to highlight methods of interest).
Point the cursor to the desired method and click the light-bulb icon or click <Alt+Enter>.
Select Add to Klocwork Knowledge Base or Add to Klocwork Knowledge Base (show dialog). The dialog helps you select methods you want to annotate and the types of annotations (or entries) you will use. If you don't use the dialog, you can add annotations manually.
Tip: You can also right-click a method in the Structure view.

A default_tuning.jkb file is created in your project or workspace with the selected method appended to the end of the file, ready for you to manually add the necessary annotations.
Tip: Use <Ctrl+click> or <Shift+click> to add multiple methods at a time.
Add information to the Configure Klocwork Knowledge Base Entry dialog:
1. Enter the checker code if it's not already entered (if you accessed the editor by clicking an issue in the Klocwork for Java view, then the checker code is automatically populated). The value entered here is automatically entered for the @Bind annotation.
2. Select the type of KB entry. See Java knowledge base reference for details.
3. Select the method to annotate.
Rerun the analysis to test your JKB file.

Editing a JKB file

You can edit a JKB file from within your project (without having to export and import it) in either of the following ways:

follow the instructions for creating a JKB file above. If a JKB file already exists in the project, it is opened and your newly selected method is appended to the existing file.
access the configuration settings by selecting File > Settings > Project Settings > Klocwork for Java. Click Edit next to the knowledge base section. If more than one JKB file exists for the project, a dialog prompts you to select one.

Tuning Java analysis in Eclipse

This article shows you how to tune the analysis to your source code within Eclipse. To learn why or when to customize your analysis, see

Customizing your desktop analysis.

For general tuning information, see

Tuning Java analysis.

Create a Java Knowledge Base file in Eclipse

You can add methods to the Java Knowledge Base (JKB) file from the editor, the Package Explorer or the Outline view.

To create a JKB file for a project instead of a workspace, you must first enable project-specific settings (right-click the project, click Properties > Klocwork and select Enable project specific settings).
Double-click an issue in the Klocwork Issues view to see the issue highlighted in the source code display. (You can also use traceback information in the Klocwork Details view to highlight methods of interest.)
Right-click the method in the editor and select Klocwork > Add to Knowledge Base.
Add the appropriate JKB annotation and save the file.
Re-run the Klocwork analysis to test your JKB file.

Example: Tuning in Eclipse

In the example below, NPE.RET is detected where null comes from the get() and is dereferenced at o.toString(). Klocwork doesn't recognize the call to assertNotNull as the validation method.

Traceback provides more information about the issue and can help you better identify the method(s) of interest.

Image:NPE.RET_traceback_Eclipse_J.png

To tune NPE.RET in Eclipse:

Double-click assertNotNull, right-click it and select Klocwork > Add to Klocwork Knowledge Base.
We need to add:
- an @Bind annotation to identify the issue type we are tuning
- an @Check annotation to describe the method as the check

package junit.framework;
  @Bind("NPE.RET")
 public class Assert {
   public static void assertNotNull(@Check java.lang.Object object);
}

Next step: Re-run the analysis by selecting the project and clicking . NPE.RET is no longer detected.

Tuning Java analysis in IntelliJ IDEA

This article explains how you can tune the Klocwork analysis from IntelliJ IDEA. To learn more about when and why to tune the analysis, see Customizing your desktop analysis.

Walk-through: Handling an NPE.RET false positive

In the example below, NPE.RET is detected where null comes from the 'get()' and is dereferenced at 'o.toString()'. NPE.RET is detected because Klocwork doesn't recognize the call to 'assertNotNull' as the validation method.

Traceback provides more information about the issue and can help identify the method(s) of interest:

To deal with this false positive, we add two Java Knowledge Base annotations: @Bind and @Check.

Select assertNotNull in the editor.
Click the icon or click <Alt+Enter> to add the method to the JKB file.

The JKB file is created and named default_tuning.jkb. Appended to the bottom of the file is the method selected in the previous step.
We need to add:
- @Bind annotation to identify the checker we are tuning
- @Check annotation to describe the method as the check
package junit.framework;

@Bind("NPE.RET")

public class Assert

public static void assertNotNull(@Check java.lang.Object object);

}
Rerun the analysis. Click . NPE.RET should no longer be detected.

Troubleshooting JKB annotation errors

If you see the error message, "Build contains errors", double-click the message line to open the build log in the editor. (You may need to use the horizontal scroll bar to see the detailed message in the build log).

Build log messages identify JKB annotation errors. For example, "Trying to create a record not bound to a defect" indicates that the @Bind annotation is missing or improperly placed. For more information about annotations, see Java knowledge base reference.

Tutorials - Tuning Java analysis

Tutorials 1 to 3 demonstrate the most common reason for tuning, that is, to reduce the detection of false positives. These three tutorials include:

the addition of validation routines to correct a detected issue
the specification of these validations using @CheckTrue, @CheckFalse, and @Check in the knowledge base (.jkb) file to reduce the reporting of the issue

Tutorial 4 demonstrates the least common scenario, that is, tuning a checker to find more issues than originally reported. @Source, @Sink, and @Prop are the knowledge base annotations used in this tutorial to detect a runtime exception that was otherwise going unreported.