Java annotation

As a voice annotation element is referred to in the context of the Java programming language, which allows the integration of metadata in the source code. This element was defined in JSR 175 and introduced with the release of Java 5.0.

Annotations begin with an @ sign. This is followed by her name ended up. Optionally can be followed by a comma-separated parameter list that is enclosed in parentheses. For example, marks the annotation in the following code snippet, the Class A as obsolete ( deprecated ):

@ Deprecated public class A { } An Annotation Processor is a compiler plugin that annotations can evaluate at compile time in order to suppress warnings and error messages or to trigger or to generate additional source code or other files. However, Annotated Code he can not change. Annotations, where provided, can also be evaluated at runtime using Reflection.

Annotations are used among other things in the Java EE environment to classes to expand information that had to be deposited before Java 5 in separate files. Prominent examples are home and local interfaces and deployment descriptors.

A previous technique for embedding metadata in Java source code is to use special Javadoc comments. These were evaluated by means of so-called doclets. A frequently employed tool for this method is XDoclet. This technique can still be used even after the introduction of the annotations.

Pre-defined annotation

In Java SE 5.0, seven predefined annotation types available in the packages (package) java.lang or are java.lang.annotation. They will all be evaluated (in contrast to most annotations) by the compiler. More can be created by programmers.

It is additionally recommended to attach a Javadoc comment, which shows how the item is to be replaced. The following example illustrates this:

/ **   * @ Deprecated Class A was replaced with version 10.3 of the aneu class.   * / @ Deprecated public class A { } @ Override With this type of a method can be identified, which overrides the method of its superclass. The compiler then ensures that the upper class contains this method and returns an error if this is not the case. example:

Public class A {      public void someMethod () { } }   public class B extends A {      @ Override      public void someMethod () { } } @ SuppressWarnings When using this annotation type, the compiler suppresses certain warnings. The annotation is to pass an array of strings that contain to be suppressed warnings. In the following example, the compiler is instructed to suppress deprecated warning for the class EineDeprecatedKlasse:

Public class A {      @ SuppressWarnings ( {" deprecation "} )      public void someMethod () {          EineDeprecatedKlasse b = new EineDeprecatedKlasse ();      } } In the package java.lang.annotation - these are only used for the definition of annotations. @ Documented This annotation is used as a meta- annotation: An annotation of this type sets for a newly created annotation that he is considered by Javadoc in generating the documentation. @ Inherited This annotation is used when programming an annotation. This can be determined that it is inherited together with a class. If this annotation then, for example, applied to a particular class, it applies to all classes that inherit from this. @ retention This type is used when programming an annotation. It indicates when you can access them yourself. There are three possible values ​​for an annotation of this type which are included in the enumeration java.lang.annotation.RetentionPolicy: CLASS The annotation is compiled with the class and is thus present in the. Class file. However, it can not be read out during the lifetime of an application. This is the default value. RUNTIME The annotation can be read during the lifetime of an application using the Reflection mechanism. SOURCE The annotation is removed from the source code before compiling. Accordingly, it is not available at runtime of a program. @ target This annotation is used when programming an annotation. This will determine which elements of a program, they may be applied. The possible values ​​for an annotation of this type are listed in the enumeration java.lang.annotation.ElementType. TYPE The annotation can only be applied to classes, interfaces or enumerations. FIELD The annotation can only be applied to fields. METHOD The annotation can only be applied to methods. Constructors are excluded. PARAMETERS The annotation can only be applied to parameters of methods and constructors. CONSTRUCTOR The annotation can only be applied to constructors. local_variable The annotation can only be applied to local variables. ANNOTATION_TYPE The annotation can only be applied to annotations. PACKAGE The annotation can only be applied to packets. Define your own annotations

Annotations are special interfaces; their names are therefore written by convention, with an initial capital letter. In their agreement is facing interface the @ character. Expand the interface implicitly java.lang.annotation.Annotation. You may not extend other interfaces (ie extends is prohibited) and are not generic. Their methods are parameterless and non- generic. As a result, types (return type) Only the following types are allowed:

• Primitive types
• Enumerated types ( enum)
• Annotation
• String
• Class
• Fields ( arrays) from these types

They also throw any exceptions and may not use recursion.

Many annotations contain any methods. An example would be:

@ interface provisionally { } Other annotations include ( as usual for interfaces ) methods, but only with the result types listed above. If an annotation contains only one method, her name is by convention value:

@ interface Test { boolean value (); / / True is not released until } or

Authors @ interface { String [ ] value (); / / Names of the authors } or

@ interface Customer { Person [ ] value (); } which person has to be defined as an enumerated type ( enum) or annotation, for example:

@ interface Person { String name (); int age (); } With the agreement of annotations the standard annotations are often used java.lang.annotation from the package. Particular attention will be given with @ retention, how long the annotation should be kept: only in the source code ( SOURCE) in the stored class file (CLASS ) or in the loaded class ( RUNTIME ). @ Target describes, for which program elements, the annotation may be used. For example, all Annotationsvereinbarungen in the package java.lang.annotation with annotations

@ Documented @ Retention ( value = RUNTIME ) @ Target ( value = ANNOTATION_TYPE ) provided. This they will all javadoc evaluated in the bytecode with loaded and can be evaluated at runtime; Also they may be used only for annotation.

Using own annotations

@ provisionally class Class { void method (); } One annotation with only one method named value must be a constant value in parentheses are indicated by the result type of this method:

@ Test (true) public void method ( ) { ...} If the result type is an array, is an array literal can be used:

@ Authors ( {" Solymosi ," " Gruda "} ) String book = " Algorithms and Data Structures with Java" If the array contains no elements, ({ }) must be specified. However, if the array contains only one element, the braces can be omitted:

@ Authors ( " Solymosi " ) String other = book "Programming in Scala " One annotation with multiple methods must each of its methods in parentheses are assigned a constant value:

@ Person ( name = " Andreas Solymosi ", age = 56) Account account = new Account (); The ability to specify the value that is named, is also annotated with a method ( is unnecessary, however, serves more than readability ):

@ Test (value = true) A complex (nested ) annotation must be applied nested:

@ Customer ( @ person ( name = " Andreas Solymosi ," age = 56) ) class Company { ...} In the agreement, the annotation default values ​​are defined for the methods; then the appropriate value may be omitted from use. Since annotations are interfaces, they can themselves be marked with annotations:

@ Authors ( " Solymosi " ) public @ interface Test { boolean value ( ) default false; / / Does not necessarily mean value } Evaluation of annotations

If the annotations are loaded with the bytecode of the class, they can be evaluated with the help of reflection. For example, to determine if an annotation has been specified or not:

If it has been determined that the annotation is present, then you can read its value, for example, whether the method is in the test state yet or not:

Boolean imTestzustand = Klasse.class.getMethod ( " method ", new Class [] { }).. done notation ( Test.class ) value ();

Here, if the annotation is not present ) the exception is thrown NullPointerException done by notation (. From a complex annotation of its elements must be selected individually:

Person customer = Unternehmen.class.getAnnotation ( Kunden.class );

Annotation packages

The Java Language Specification also allows for the annotation of packages, for example, to provide documentation for a package. Per package a package declaration may be annotated maximum. If a packet is received annotations, the Java Language Specification recommends that you create a separate file named package- info.java in the directory of this package. This file then contains the package declaration with the annotations.