a form of metadata. It provides data about a program that is not part of the program itself. Annotations have no direct effect on the operation of the code they annotate. Annotations were first introduced in the Java language with the third edition of the Java Language Specification and first implemented in Java 5. Annotations are Annotations have a number of uses, among them: — Annotations can be used by the compiler to detect errors or suppress warnings. Information for the compiler — Software tools can process annotation information to generate code, XML files, and so on. Compile-time and deployment-time processing — Some annotations are available to be examined at runtime. Runtime processing Using annotations, we are able to add metadata information to our source code — build or deployment information, configuration properties, compilation behavior or quality checks. Here I’m going to explain where annotations can be used, how to apply annotations, what predefined annotation types are available in the Java Platform, Standard Edition (Java SE API). Annotations Basics Annotations always appears before the annotated piece of code and by convention, usually in its own line, indented at the same level. Annotations may apply to packages, types (classes, interfaces, enums and annotation types), variables (class, instance and local variables — including that defined in a for or while loop), constructors, methods and parameters. In its simplest form, an annotation looks like the following: @Entity The at sign character (@) indicates to the compiler that what follows is an annotation. In the following example, the annotation’s name is Override: @Override myAnnotationUsageMethod() { ... } void The annotation can include , which can be named or unnamed, and there are values for those elements: elements ( name = , date = ) { ... } @Author "Roland Hewage" "2019/04/18" () class MyClass For example they can be used in a method as follows: (value = ) { ... } @SuppressWarnings "unchecked" void myMethod () Annotations may include elements that are just name-value pairs separated by commas. Allowed types are primitives, strings, enums, class, annotations and arrays of these types : and the default value cannot be null (name = , created = , revision = , reviewers = { , }) {…} @Author "Roland" "2019/04/18" 3 "WSO2" "Shankar" public class SimpleAnnotationsTest When the annotation has only one element and its name is , it can be omitted: value (value = ) { ... } @SuppressWarnings "unchecked" void myMethod () or ( ) { ... } @SuppressWarnings "unchecked" void myMethod () If the annotation has no elements, then the parentheses can be omitted, as shown in the previous @Override example. { ... } @Override void myAnnotationUsageMethod () It is also possible to use multiple annotations on the same declaration: (name = ) { ... } @Author "Roland Hewage" @EBook class MyClass If the annotations have the same type, then this is called a repeating annotation: (name = ) (name = ) { ... } @Author "Roland Hewage" @Author "Rosy Buhat" class MyClass are supported as of the Java SE 8 release. Repeating annotations The annotation type can be one of the types that are defined in the java.lang or java.lang.annotation packages of the Java SE API. In the previous examples, Override and SuppressWarnings are . It is also possible to define your own annotation type. The Author and Ebook annotations in the previous example are custom annotation types. predefined Java annotations Annotations may define default values for some or all of their elements. Elements with default values can be omitted from an annotation declaration. For example, assuming the Annotation Type Author defines default values for revision (default is 1) and reviewers (default is an empty String array), the following two annotation declarations are equivalent: (name = , created = , revision = , reviewers = {}) {…} @Author "Roland" "2018/04/18" 1 class public SimpleAnnotationsTest () is equal to, (name = , created = ) {…} @Author "Roland" // defaults are revision 1 "2018/04/18" // and no reviewers class public SimpleAnnotationsTest () Where Annotations Can Be Used Annotations can be applied to declarations: declarations of classes, fields, methods, and other program elements. When used on a declaration, each annotation often appears, by convention, on its own line. As of the Java SE 8 release, annotations can also be applied to the of types. Here are some examples: use Class instance creation expression: MyObject(); new @Interned Type cast: myString = ( String) str; @NonNull implements clause: { ... } < > @ <@ > class UnmodifiableList T implements Readonly List Readonly T Thrown exception declaration: { ... } @Critical TemperatureException void monitorTemperature () throws This form of annotation is called a . type annotation Declaring an Annotation Type Many annotations replace comments in code. Suppose that a developer traditionally starts the body of every class with comments providing important information: { } public class Generation3List extends Generation2List // Author: Roland Hewaage // Date: 2018/04/18 // Current revision: 6 // Last modified: 2019/04/18 // By: Roland Hewage // Reviewers: Alice, Bill, Cindy // class code goes here To add this same metadata with an annotation, you must first define the . The syntax for doing this is: annotation type ClassPreamble { ; ; ; ; ; String[] reviewers() {}; } @interface String author () String date () 1 int currentRevision () default String "N/A" lastModified () default String "N/A" lastModifiedBy () default // Note use of array default The annotation type definition looks similar to an interface definition where the keyword interface is preceded by the at sign (@) (@ = AT, as in annotation type). Annotation types are a form of interface. The body of the previous annotation definition contains declarations, which look a lot like methods. Note that they can define optional default values. annotation type element After the annotation type is defined, you can use annotations of that type, with the values filled in, like this: ( author = , date = , currentRevision = , lastModified = , lastModifiedBy = , reviewers = { , , } ) { } @ClassPreamble "Roxana Chatu" "2018/06/23" 6 "2018/09/12" "Roly Ross" // Note array notation "Alice" "Bob" "Cindy" public class Generation3List extends Generation2List // class code goes here To make the information in @ClassPreamble appear in Javadoc-generated documentation, you must annotate the @ClassPreamble definition with the @Documentedannotation: java.lang.annotation.*; ClassPreamble { } // import this to use @Documented import @Documented @interface // Annotation element definitions Predefined Annotation Types A set of annotation types are predefined in the Java SE API. Some annotation types are used by the Java compiler, and some apply to other annotations. Annotation Types Used by the Java Language The predefined annotation types defined in java.lang are @Deprecated, @Override, and @SuppressWarnings. 1. @Deprecated annotation indicates that the marked element is and should no longer be used. The compiler generates a warning whenever a program uses a method, class, or field with the @Deprecated annotation. When an element is deprecated, it should also be documented using the Javadoc @deprecated tag, as shown in the following example. @Deprecated deprecated The use of the at sign (@) in both Javadoc comments and in annotations is not coincidental: they are related conceptually. Also, note that the Javadoc tag starts with a lowercase and the annotation starts with an uppercase . d D { } // Javadoc comment follows /** * * explanation of why it was deprecated */ @deprecated @Deprecated static void deprecatedMethod () 2. @Override annotation informs the compiler that the element is meant to override an element declared in a superclass. @Override { } // mark method as a superclass method // that has been overridden @Override int overriddenMethod () While it is not required to use this annotation when overriding a method, it helps to prevent errors. If a method marked with @Override fails to correctly override a method in one of its superclasses, the compiler generates an error. 3. @SuppressWarnings annotation tells the compiler to suppress specific warnings that it would otherwise generate. In the following example, a deprecated method is used, and the compiler usually generates a warning. In this case, however, the annotation causes the warning to be suppressed. @SuppressWarnings ( ) { objectOne.deprecatedMethod(); } // use a deprecated method and tell // compiler not to generate a warning @SuppressWarnings "deprecation" void useDeprecatedMethod () // deprecation warning // - suppressed Every compiler warning belongs to a category. The Java Language Specification lists two categories: deprecation and unchecked. The unchecked warning can occur when interfacing with legacy code written before the advent of . To suppress multiple categories of warnings, use the following syntax: generics ({ , }) @SuppressWarnings "unchecked" "deprecation" 4. @SafeVarargs annotation, when applied to a method or constructor, asserts that the code does not perform potentially unsafe operations on its varargs parameter. When this annotation type is used, unchecked warnings relating to varargs usage are suppressed. @SafeVarargs 5. @FunctionalInterface annotation, introduced in Java SE 8, indicates that the type declaration is intended to be a functional interface, as defined by the Java Language Specification. @FunctionalInterface Since the introduction of annotations, many libraries and frameworks have incorporated annotations into their newer releases. With annotations used in place with source code, these libraries and frameworks have reduced, even removed, the needs for configuration files. Brilliant examples can be seen in: Java Enterprise Edition and its main components — Enterprise JavaBeans, Java Persistence API or Web Services API’s Spring Framework — used thoroughly for configuration, dependency injection and inversion of control in the core framework and in other Spring projects Seam, Weld, Guice Apache Struts 2 Annotations That Apply to Other Annotations Annotations that apply to other annotations are called . There are several meta-annotation types defined in java.lang.annotation. meta-annotations 1. @Retention annotation specifies how the marked annotation is stored: @Retention RetentionPolicy.SOURCE – The marked annotation is retained only in the source level and is ignored by the compiler. RetentionPolicy.CLASS – The marked annotation is retained by the compiler at compile time, but is ignored by the Java Virtual Machine (JVM). RetentionPolicy.RUNTIME – The marked annotation is retained by the JVM so it can be used by the runtime environment. 2. @Documented annotation indicates that whenever the specified annotation is used those elements should be documented using the Javadoc tool. (By default, annotations are not included in Javadoc.) @Documented 3. @Target annotation marks another annotation to restrict what kind of Java elements the annotation can be applied to. A target annotation specifies one of the following element types as its value: @Target ElementType.ANNOTATION_TYPE can be applied to an annotation type. ElementType.CONSTRUCTOR can be applied to a constructor. ElementType.FIELD can be applied to a field or property. ElementType.LOCAL_VARIABLE can be applied to a local variable. ElementType.METHOD can be applied to a method-level annotation. ElementType.PACKAGE can be applied to a package declaration. ElementType.PARAMETER can be applied to the parameters of a method. ElementType.TYPE can be applied to any element of a class. 4. @Inherited annotation indicates that the annotation type can be inherited from the super class. (This is not true by default.) When the user queries the annotation type and the class has no annotation for this type, the class' superclass is queried for the annotation type. This annotation applies only to class declarations. @Inherited 5. @Repeatable annotation, introduced in Java SE 8, indicates that the marked annotation can be applied more than once to the same declaration or type use. @Repeatable
