annotations : Java Glossary

The Basics

These @annotations not Javadoc comment tags! They are part of the program proper.

@Retention(RetentionPolicy.RUNTIME) means the following annotation should be retained in the class files.

@Target(ElementType.METHOD) means the following annotation only applies to methods in the class, not the whole class.

@Documents means the following annotation should show up in the Javadoc.

Now that you have defined it, you can annotate any class with it, which embeds the copyright notice in the class file, with otherwise changing the class file. It does not add any methods or fields to your class, though it is sometimes possible to get at the information through the java.lang.annotation package methods. Here is how you use it:

@SuppressWarnings

In Java version 1.5, Oracle introduced an annotation called @SuppressWarnings. Unfortunately, it is ignored prior to JDK (Java Development Kit) 1.5.0_06. You just insert the annotation prior to a class or method declaration telling which sort of warning you want suppressed. Further, you are not permitted to use them if you have -target 1.4 or earlier, not even @SuppressWarnings. You use them like this:

As well as classes and methods, @SuppressWarnings also applicable to enum, interface, constructor, field, parameter and local variable declarations.

Annotations do not inherit.

Here are the sorts of warning you can suppress:

Some of the options above are for Eclipse only, however, Javac will quietly ignore them.

@Override

There is no override keyword to warn the compiler your method is intended to override a method in the base class. However, since Java version 1.5 or later, there is an @Override annotation. @Override serves as documentation for the reader and a double check in the compiler. The compiler will warn you if your method is not overriding properly, usually because the two method names are not spelled exactly the same way. Note it is @Overridewith capital O and double r, not @overide. Don’t confuse the @Override annotation with the unofficial @override Javadoc command. Here is how you would use the @Override annotation to indicate that a method is overriding another in the base class. Note it is not inside the Javadoc comment!

/**
 * Get String presentation for this Thing object.
 * @return human readable summary of fields in Thing object.
 */
@Override
public String toString()
   {
   return desc + " " + quantity + " " + losses;
   }

Checker-Framework

The university of Washington has put out a huge library of annotations called Checker-Framework. It is not built into Javac as I was first lead to believe. You must install it first in a rather daunting procedure. It works with ANT, Maven, IntelliJ, Eclipse and others, but not NetBeans.

It supports fake enums, using fenums, enums checked only at compile time, implemented with ordinary ints and hence backward compatible with code written before the invention of enums using @Fenum.

It checks your regex and format string syntax at compile time with @Regex and @Format.

It handles consistency of units of measure, but not automatic conversion of units, with annotations such as: @Area, @Current, @Length (@m, @mm, @km ), @Luminance, @Mass, @Speed, @Substance, @Temperature and @Time. You could spend weeks exploring the smorgasbord of tools included.

Learning More