Java: Using Predefined Annotations - dummies

Java: Using Predefined Annotations

By John Paul Mueller

The kinds and content of annotations in Java, like comments, are limited only by your imagination. Yes, Java provides some predefined annotations, but you can also create annotations that describe program elements in any way you want. The idea is that you describe how an annotation should work, provide data for it, and the compiler takes care of the rest.

Annotations always begin with the @ (at) symbol. So, when you see @Documented, you know that you’re seeing an annotation. The following sections tell you more about predefined and custom annotations.

A predefined annotation is one that exists as part of Java. You find these annotations in the java.lang.annotation package. To use them, you add import java.lang.annotation.*; to the beginning of your application. The following list provides an overview of the predefined annotations:

  • @Deprecated: Sometimes an element — a class, method, field, or other programming feature — is superseded by a newer element or is simply no longer needed.

    When this happens, you mark the element as deprecated so that developers know they need to update their code and stop using that particular element. Adding the @Deprecated annotation outputs the deprecated status of the element in the documentation generated by Javadoc (a utility that is used to create documentation automatically based on the content of your code files).

  • @Documented: Any time you mark an element as documented, the Javadoc utility outputs it to the documentation file it creates based on the source file content.

  • @FunctionalInterface: Specifies that the interface is a functional interface used for anonymous classes and lambda expressions.

  • @Inherited: Classes can inherit characteristics from a parent class. By default, this includes functionality such as methods but doesn’t include the parent class’s annotations. Using the @Inherited annotation tells Java to apply the parent class annotations to the subclass as well.

  • @Override: Specifies that a child class element is overriding a superclass (parent class) element. If this annotation is present and the superclass lacks an element of the same name, the compiler outputs an error so that you know something is wrong with the override.

  • @Repeatable: Most annotations are applied only once to a particular element. However, in some cases you need to apply the annotation more than once. This annotation tells Java that it’s acceptable to apply the annotation to a particular element more than one time.

  • @Retention: An annotation can affect only the source code; the source code and compiler; or the source code, compiler, and JVM. This annotation defines what effect another annotation should have. For example, you may need only a documentation-specific annotation to affect the source code and compiler.

  • @SafeVarargs: It’s possible to perform operations that aren’t safe on the arguments passed to a method or constructor. This annotation says that the code doesn’t do anything unsafe and therefore doesn’t require all the usual checks. Reducing the number of checks makes the application run faster.

  • @SuppressWarnings: The Java compiler outputs a wealth of warnings to signal potential problems. For example, if you try to use a deprecated method in your code, the compiler outputs a warning message about it. This annotation tells the compiler not to output such warnings for the affected element.

  • @Target: When you create your own annotations, it can be helpful to tell the compiler that these annotations should affect only a specific element type. For example, if you create an author block that is meant to appear only at the package level, then you can limit the annotation to just that element type by using the @Target annotation.