Using null annotations for fields (currently beta) in Eclipse JDT Juno

It is common knowledge by now that Eclipse Juno's JDT shipped with support for null annotations for inter-procedural null analysis. This was very well-received and the work made it to several blogs about the 10 most interesting Eclipse Juno features. While this is only applicable to local variables/method parameters for now, I had also blogged about null analysis support for fields while we worked on it. However, due to the sheer complexity of dealing with problems such as aliasing, concurrency, etc with fields and the current infrastructure's limitations in dealing with these issues comprehensively, we had to withdraw this feature. Because of this, Juno did not come with null annotations support for fields.

However, the good news is that along with the Juno release, the JDT team, with all due credits to Stephan Herrmann, also released a public beta version of null annotations support for fields. Please visit the null analysis beta wiki page to learn about installation and usage of this feature. As Stephan puts it in his post on DZone, "feedback to this experimental solution should help us to decide what will be JDT's final solution regarding null analysis for fields". So, please start using it if you've upgraded to Eclipse Juno. If not, what are you waiting for? ;)

Null analysis for fields in Eclipse JDT withdrawn for Juno

Null analysis for fields with Eclipse JDT , introduced in Juno M5, has been withdrawn and will not be available in the Juno release. Only Juno M5 will contain this feature. The reason for withdrawal is the fact that becuase of implementation constraints, it could not support analysis for alien field references i.e. non-static fields of objects other than 'this'. We will rework the implementation and come back with a full fledged support for fields, including annotations to support null analysis for fields. See https://bugs.eclipse.org/bugs/show_bug.cgi?id=247564#c176 for more details.

Apologies to those who were looking forward to a complete null annotations support for fields as well. We are considering making the current implementation of the feature available as a plugin patch. I will keep you posted.

Also, even when using annotations for method return and parameters, be careful in dealing with fields because we don't warn there. Eg:

class A{
     Object o = null;
     void goo(@NonNull Object param) {}
     @NonNull Object foo() {
            goo(this.o);
            return this.o;
       }
}

Null Analysis for Fields with Eclipse JDT

It is common knowledge that Eclipse has an intra-procedural null analysis capability, augmented recently with null annotations for inter-procedural analysis in Juno M4. However, a big flaw and pain point till now was that the anlsysis would only work for local variables/parameters, and NOT for fields! Strange, innit? Well, a bunch of problems with handling fields prevented the initial null analysis implementation to be generic enough to handle fields as well. Access from different threads, through different objects, initialization of even final fields in different constructors were some of the roadblocks because of which this work was put on the backburner. However, even though we haven't found a holy grail to tackle these problems, we've come out with atleast a basic implementation of null analysis for fields! Rejoice!

A. The Problem
Prior to Juno M5, the following code snippet would raise null warnings only on the local variable, but not on the field.

B. The Solution
See the Juno M5 new and noteworthy page for the new null analysis for fields.
Note that for non-constant fields, we only raise "potential NPE" warnings even if the field has been assigned null or compared against null because we assume that there's always a chance of another thread modifying it between the assignment/comaparison and the actual reference. So consider the following snippet

C. Not quite there yet?
There are a few limitations with the current null analysis for fields:

• Yet to be done for final fields that are initialized at the time of declaration. This will be done with the fix for bug 237236 soon.
• The analysis only works for non-static fields of the current object or static fields of the current type ONLY. That means, in the following code snippet. you get null warnings on direct access of field1 or access via "this", but not if field1 is accessed via another object 'test'.

class Test{
   public Object field1;
   void foo(Test test) {
      if (field1 == null) { 
         System.out.println( field1 .toString());  // "potential" NPE warning
     } else {
        // do something
     }
     System.out.println(field1.toString());  // Potential NPE warning here

     if (this.field1 == null) { 
         System.out.println( this.field1 .toString());  // "potential" NPE warning
     } else {
        // do something
     }
     System.out.println(this.field1.toString());  // Potential NPE warning here
    // access through object 'test' will raise no warnings. See below

     if (test.field1 == null) { 
         System.out.println( test.field1 .toString());  // no warning
     } else {
        // do something
     }
     System.out.println(test.field1.toString());  // no warning


  }
}

This is a limitation of the current code analysis infrastructure and we hope to address this sometime soon. The soon to be released null annotations support for fields will greatly assuage this problem in the short term.

Please do start using this new feature. Even with its limitations, its quite useful and we've found a long list of unsafe code patterns in the Eclipse SDK itself. Deepak's post here presents one such example

Apart from this, Juno M5 has more interesting items. See my previous post on pre-built indexes, Stephan's post on Resource leak warnings and the Juno M5 new and noteworthy page for more.

Stay tuned!

Inter-procedural Null analysis using annotations in Eclipse JDT

The JDT team is extremely excited with the release of the new annotation based null analysis. Before writing anything about it I want to thank Stephan Herrmann (JDT committer from Germany) for all the hard work he has put in on this feature! Feel free to drop him a word of appreciation on stephan AT cs.tu-berlin.de

What is JDT's annotation based null analysis?
To give a bit of a background, you must've noticed that JDT java compiler does some static analysis and based on that warns if you deference a variable that has been analysed to be (potentially) null at runtime, or compare a variable against null when its nullness at runtime can be determined at compile time.

[See line numbers to locate error messages]

However, the warnings are only generated for local variables inside a method. There's no way to find out the change of nullness due to a method call, or for parameters of a method. Consider the example on the left. o1 is a parameter and since we don't know how foo(..) will be called and what value will be passed to o1, we can't do any analysis on it unless its state definitely changes inside foo(..). Also note that even though o1 is assigned return value of method  bar(), which returns null, the compiler cannot figure that out during static analysis and assumes the return value of bar() to be an unknown value.

Null annotations offer a solution here. They are a way of enforcing null contracts in your code to make sure you catch such (potential) NPE's before they occur at runtime and become a stop-ship bug for your product.


How do I use null annotations?
JDT now comes bundled with a JAR (org.eclipse.jdt.annotation) containing null annotations. The types of annotations offered are:
NonNull annotation
Default is @org.eclipse.jdt.annotation.NonNull -

• when this annotation occurs on a return type, it enforces a non null return value for a method.
• when this annotation occurs on a method parameter, it enforces a non null value to be passed to the method call and that only a non null value can be assigned to this parameter inside the method.

Nullable annotation
Default is @org.eclipse.jdt.annotation.Nullable-

• when this annotation occurs on a method return type or parameter, it says that the returned value can be null, and so can be the argument.

NonNullByDefault annotation
Default is @org.eclipse.jdt.annotation.NonNullByDefault-

• This can be applied to a package (in package-info.java), class or method to enforce nullability for all enclosed elements. The annotation alone enforces non nullability of enclosed method return value and parameter values.
• If applied with a an argument i.e. NonNullBeDefault (false), it will cancel out any global default for the particular element.

To use these annotations in your project, right click Project>Build Path>Add External Archives and browse to org.eclipse.jdt.annotation JAR in the "plugins" directory of your eclipse install location. (We are working on the UI for this.)

One can also use their own annotation types as null annotations. Just make sure they are on the project's buildpath.

To enable null annotation based analysis and specify the annotation names, navigate to Preferences>Java>Compiler>Errors/Warning>Null analysis.

(Note also the "use non-null as default" option, which you can use to set a universal (workspace/project level) default to be applied to all method return types and parameters.)







What new errors/warnings should I expect to see with null annotations enabled?
As seen in the above dialog, there are two kind of diagnostics of primary importance - violation of null specification and potential violation of null specification. In addition to these the existing null analysis gets enhanced, and now for annotated method parameters a null state is available inside a method.

Violation of null spec is issued in cases when:
1. You pass a null value as an argument to a method whose corresponding parameter is annotated with @NonNull
2. You assign a @NonNull annotated parameter a null value.
3. You return a null value in a method that is annotated with @NonNull
4. You inherit a method annotated with @NonNull but now loosen the contract by annotating child method as @Nullable.
5. You inherit a method with a parameter annotated with @Null but now tighten the contract by annotating child method's corresponding parameter as @NonNull.

[See line numbers to locate error messages]

Potential violation of null spec is issued when:

1. You pass a value evaluated to be null on some execution path as an argument to a method whose corresponding parameter is annotated with @NonNull
2. You assign a @NonNull annotated parameter a value ascertained to be null on some execution path.
3. You return a possibly null value in a method that is annotated with @NonNull.

[See line numbers to locate error messages]

Insufficient null info is issued when there's not sufficient information to evaluate a given value to be (possibly) null and that value is passed as an argument, assigned to a parameter or returned from a method.

[See line numbers to locate error messages]

Redundant null annotation is issued when an annotation has the same effect as one applied already in an enclosing element.

[See line numbers to locate error messages]

Note that this is a work in progress and we will continue to polish the same for the Juno release. We're also working on ways to help people use this functionality easily (eg.: Support for nullity profiles for libraries and Quick fixes for null annotations. ) .
For a sneak preview of this feature, drop in at the EclipseCon 2012 tutorial - How To Train the JDT Dragon. If you find any issues while testing this feature, please open a bug. I hope you're as excited as we are about this cool new feature!