Skip to content

JSR 305, Nonnull and Guava Preconditions

by on October 31, 2012

JSR 305 is a proposal for Annotations for Software Defect Detection. Meanwhile widely spread are the annotations like @Nonnull and @Nullable which you will also find in one of my favorite libraries: Guava – Google Core Libraries for Java 1.6+.

While at designing an API from scratch I feel very comfortable with using these annotations when having an IDE which supports code inspections respecting these annotations. I have tested it with IntelliJ Idea but I am sure other IDEs can do it as well as Idea.

When using such annotated methods or fields my IDE does a great job telling me when using a value which is annotated as @Nullable and when I forgot to check for null. And what is even more: I can tell the customers of my API about the contract of my API:

  • Method doThat(...) expects nonnull-parameters.
  • Method doThis(...) might return null values.
  • Method doAnythingElse(...) guarantees to always return nonnull-values.

Discussion:

While this approach looks fine at first glance many projects don’t want to enforce dependents on that API to be forced to the transitive dependency to the annotations. But Guava shows a way around this: They define the dependency with scope provided. I do some more (while not having evaluated what is the best solution) to also mark the dependency as optional. So my dependency looks like this:

<dependency>
  <groupId>com.google.code.findbugs</groupId>
  <artifactId>jsr305</artifactId>
  <scope>provided</scope>
  <optional>true</optional>
</dependency>

Of course the version is managed somewhere else…

Is this all you need to do?

No: While a static code analysis will tell you about problems, the Java compiler will silently ignore possible problems. That’s where I am used to Guava’s Preconditions. So a typical method looks like this:

@Nonnull
Object getThat(@Nonnull Object in) {
  Preconditions.checkNotNull(in, "in must not be null.");
  ...
}

Now it becomes valuable. Especially using static import you will only have some short lines of argument checkers and with the annotations you assist developers in actually preventing these exceptions to raise as their IDE might assist them.

Discussion:

Preconditions.checkNotNull(...) throws a NullPointerException if the checked argument is null. This infringes coding conventions in some projects where it is forbidden to raise NullPointerExceptions manually.

Conclusion

I like at least these two JSR305 Annotations very much. They assist in writing easy to use APIs not trying to guess or having to browse the sourcecode to understand if it can deal with null values or not. There are a lot more annotations but I think only those annotations make sense which are well supported by your IDE. Otherwise you will have no direct benefit from it despite that it is mentioned in the Javadoc.

From → Dev

Leave a Comment

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s