@Nullable : Java Glossary

The most common convention is you describe returns by putting the @Nullable/@NotNull before everything in the method declaration, e.g. before the public. You describe parameters by putting the @Nullable/@NotNull before everything in the parameter e.g. before the final.

import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
...
// placementof @Nullable and @NotNull
@NotNull private String expand( @NotNull File targetFile,
                               @Nullable String image)
                              {
                              ...
                              }

If your code violates the annotations, you will be warned to add specific code for null checking, possibly an assert or if ( var != null ) perhaps overly conservatively. If you don’t fix it, the code will still run, but could possibly throw a NullPointerException.

If you am passing in a value to one method that requires � @NotNull parameters, and that value was obtained by another method whose return value is marked @NotNull, you need not write an explicit null check. That saves you coding and reduces the need for overly conservative defensive programming.

Of course you are not obligated to mark every return, parameter and variable with an annotation. The unmarked ones you deal with at run time with a NullPointerException and/or with explicit null-checking code.

This sounds simple enough but there are quite a number of steps and complications to getting it to work:

1. The @Nullable and @NotNull annotations are an open source feature of the IntelliJ IDE (Integrated Development Environment), not a feature of the Java language. Annotations in general are of course built into Java. JetBrains have offered them to Oracle to include in standard Java, but Oracle has not yet accepted them.
2. You have to configure the feature to work in IntelliJ. You must configure J:\Program Files (x86)\JetBrains\IntelliJ IDEA 10.5.2\redist\annotations.jar as one of the libraries accessible to your module. This will only apply to your 1.5+ targets.
   1. In the project panel, click the name of your project. This is the tricky part. You must click the project, not the module to configure the module.
   2. Click Module Settings.
   3. Click Project.
   4. On the left, click modules.
   5. Click the name of one of your modules from the middle column.
   6. Click Dependencies
   7. Click add.
   8. Click Single-entry module library
   9. Navigate to J:\Program Files (x86)\JetBrains\IntelliJ IDEA 10.5.2\redist\annotations.jar
   10. Click OK.
   11. Click OK.
3. Strange as it sounds to the novice programmer, but it is also possible to store your annotations separately from the source code, though the IntelliJ IDE will display them as if they were embedded. This ability in not peculiar to IntelliJ. log4j,� SLF4J, XStream, Spring, mysql-connector-j, commons-lang, junit… all store information about he code separately from the source code, many using the annotation mechanism. JSR-305 on Annotations for Software Defect Detection is nothing but annotation.
4. To make the annotations available to your JDK (Java Development Kit) used by IntelliJ to compile your code (as distinct from the JRE (Java Runtime Environment) it uses to run the IDE), or to let ANT (A Neat Tool) compile outside IntelliJ, you will need to install annotations.jar in your own various ext directories. Theoretically you don’t need to put in all of them, but I find it simpler to do so.
   where to look for ext directories :

   • in C:\Program Files\java\jre7\lib\ext in JRE 1.7.0 on your local hard disk.
   • in J:\Program Files\java\jdk1.7.0_04\jre\lib\ext in JDK 1.7.0 on your local hard disk.
   • in C:\Program Files\java\jre6\lib\ext in the older JRE 1.6.0 on your local hard disk.
   • in J:\Program Files\java\jdk1.6.0_32\jre\lib\ext in the older JDK 1.6.0 on your local hard disk.

5. At this point all will work fine, except that if you reorganize your imports the following lines will disappear:

   // Disappearing imports for @NotNull and @Nullable
   import org.jetbrains.annotations.NotNull;
   import org.jetbrains.annotations.Nullable

   What you have to do now is configure the auto-import function to ignore these imports:

   1. Click File.
   2. Click Settings.
   3. Click +Editor.
   4. Click Auto Import.
   5. Under Exclude from import and completion, click Add.
   6. Type org.jetbrains.annotations.NotNull
   7. Click Add again.
   8. Type org.jetbrains.annotations.Nullable
   9. Click OK.
6. If you give your code to other people, their compiler won’t understand the annotations. What do you do to allow others to deal with your annotations? In general javac.exe just ignores annotations it does not recognise. Thus others will need your J:\Program Files (x86)\JetBrains\IntelliJ IDEA 10.5.2\redist\annotations.jar. You would have to bundle it with your source code distributions. They need to install annotations.jar in their JDK ext directories e.g.
   where to look for ext directories :

   • in C:\Program Files\java\jre7\lib\ext in JRE 1.7.0 on your local hard disk.
   • in J:\Program Files\java\jdk1.7.0_04\jre\lib\ext in JDK 1.7.0 on your local hard disk.
   • in C:\Program Files\java\jre6\lib\ext in the older JRE 1.6.0 on your local hard disk.
   • in J:\Program Files\java\jdk1.6.0_32\jre\lib\ext in the older JDK 1.6.0 on your local hard disk.
7. Now insert some imports and annotations in your source code, and build.

Classpath Method

1. Type the @Nullable or @NotNull annotations in your source code.
2. Hit alt+enter to invoke quick fix and select Add 'annotations.jar' to classpath or Add Maven dependency if it’s a Maven project.
3. Click OK to the dialog and continue working.
4. I suspect you still have to do some of the above steps in the long method.

Puzzles

• Does the IntelliJ IDE evaluate the annotations or does Javac? or both?
• What is the best way to stop the imports from disappearing?
• What do you have to do so other people who do not own IntelliJ can build?
• Can people without IntelliJ use the annotations? If so, will they be evaluated or ignored?