Finding and annotating code returning null

Last Updated on Monday, 06 September 2010 18:19 Written by jarnotator Sunday, 05 September 2010 07:42

Since version 1.0 the jarnotator (jar annotator) static analysis tool features return null; detection. Meaning that it analyzes bytecode for this pattern and annotates the method with the jsr-305 @javax.annotation.CheckForNull annotation. The excellent static analysis tool findbugs (TM) uses these annotations and can report possible NullPointerException-s.

Consider the code snippet below. A fairly innocent piece of code at first sight. Yet the author chose to return null in case the file can not be found. Of course, the javadoc mentions this fact but then again who really has read all the javadoc for all the methods he or she uses?

/**    
* Return FileInputStream for given fileName    
* @param fileName of the file to be opened    
* @return null if file not found    
*/    
protected  FileInputStream openFileInputStream(String fileName) {
        try {
            return new FileInputStream(fileName);
       } catch (FileNotFoundException e) {
            // Ouch, that will take the user by surprise.
            // Because who really reads the java doc? Very bad practice!!!
            return null;
        }    
}

So what is the solution to this problem? Possibly jsr-305, Annotations for Software Defect Detection. jsr-305 proposes to tighten the contract of an API by applying a set of annotations. Some of these annotations relate to nullness. These annotations can be used to add constraint to interface being implemented as well as the way the API is used. Which brings us back to our code snippet.

The author decided to return null when the file can not be found. It is up to the user of this method to check the return value for null before using it. The @javax.annotation.CheckForNull annotation proposed by jsr-305 is intended for this kind of scenario. By adding the annotation on the method (line 6), as illustrated below, we made it possible for tools like findbugs(TM) to take into account this constraint are report any violation. In other words this allows you to enforce the contract specified by the annotations.

But there are a few obstacles to the adoption of jsr-305.  First of all it is somewhat tedious to add these annotations. Adding jsr-305 annotation to new code is straightforward. But retroactively annotating existing code is a painstaking and therefore time consuming job. A second problem is what could be described as the propagation of constraints within your code base. Indeed, jsr-305 annotations can also be applied to method parameters. One can for example specify, as illustrated below, that the fileName parameter of our method should not be null. This relieves our code from having to perform a null-check. But herein lurks a problem similar to obtaining const-correctness in C++. To be of any use the constraint imposed by our code should be propagated up the call-chain as much as possible. This again is a tedious thing to do.

jarnotator was developed to tackle this problem. The current version, 1.2 at the time of this writing, focusses solely on the use of @javax.annotation.CheckForNull. It automatically annotates the bytecode of methods returning null with @javax.annotation.CheckForNull. As will be illustrated in another document, It can propagate the @javax.annotation.CheckForNull constraint up in the class hierarchy as well as onto implemented interfaces. Annotations placed in the bytecode are used by findbugs(TM) and help you avoid some pitfalls. Better still, you can run jarnotator on third party libraries as well. In doing so you can protect your code from nasty surprise in the for of undocumented null return values.

jarnotator can be used standalone, as an Ant task or a maven plugin.

/**
* Return FileInputStream for given fileName
* @param fileName of the file to be opened
* @return null if file not found
*/
@javax.annotation.CheckForNull
protected  FileInputStream openFileInputStream(@javax.annotation.Nonnull String fileName) {
      try {
          return new FileInputStream(fileName);
      } catch (FileNotFoundException e) {
          // Ouch, that will take the user by surprise.
          // Because who really reads the java doc? Very bad practice!!!
         return null;
        }
}