How to describe Java code with annotations

Deprecated annotates application elements that are to be deprecated (phased out). Such elements should no longer be used. The compiler will warn you when a deprecated element is being accessed.

The following java.util.Date constructor demonstrates Deprecated:

@Deprecated
public Date(int year, int month, int date, int hrs, int min)
{
   // ... body of this constructor
}

Java 9 introduced a pair of elements into this annotation type:

• boolean forRemoval: Indicates whether the annotated element is subject to removal in a future version. The default value is false.
• String since: Returns the version in which the annotated element became deprecated. The version string is in the same format and namespace as the value of the @since javadoc tag. The default value is the empty string.

These elements are used to alert developers that parts of standard Java APIs are slated for removal in a future Java version and are being phased out, respectively. For example, Java 9 used the since element to identify the version in which java.io.FileInputStream’s and java.io.FileOutputStream’s void finalize() methods were first deprecated:

@Deprecated(since="9")
protected void finalize() throws IOException

Java 10 also used the forRemoval element to indicate that these API methods would be removed in a future Java version. These methods were removed in Java 12:

@Deprecated(since="9",forRemoval=true)
protected void finalize() throws IOException

Override

Override annotates subclass methods that override their superclass counterparts. The compiler reports an error when the subclass method doesn’t override the superclass method.

The following example demonstrates Override where the java.lang.Runnable interface’s public void run() method is overridden by an anonymous class:

Runnable r = new Runnable()
             {
                @Override
                public void run()
                {
                   // ... body of this method
                }
             };

SuppressWarnings

SuppressWarnings annotates application elements (and all elements contained in these application elements) where any of the named compiler warnings (e.g., unchecked) should be suppressed.

The following example uses SuppressWarnings to suppress an unchecked warning in the context of the (E[]) cast — I explain E[] and <E> in my next article:

public class Container<E>
{
   private E[] elements;
   // ...

   @SuppressWarnings("unchecked")
   public Container(int size)
   {
      // ...
      elements = (E[]) new Object[size];
   }
   // ...
}

Without the @SuppressWarnings("unchecked") annotation, the compiler would generate a warning about an unchecked cast; specifically, (E[]) casting from Object[] to E[].

You might be wondering why I annotated the constructor instead of the expression containing the cast. I did so because Java doesn’t allow annotations to be applied to expressions.

The E[] and <E> syntaxes in the previous example are associated with Java’s generics language feature. I will cover generics in a future Java 101 tutorial.

This story, "How to describe Java code with annotations" was originally published by JavaWorld.