Java annotation Manual

Author: cleverpig (author's blog: http://blog.matrix.org.cn/page/cleverpig)
Original article: http://www.matrix.org.cn/resource/article/44/44055_Java+Annotation+Reflect.html
Keywords: Java, annotation, reflect

Preface:
In the previous article "Java annotation getting started", I introduced the definition and use of annotation in a wide range, but the depth is not enough. Therefore, after getting started with Java annotation, the author continues to sort out the concepts and knowledge points of annotation and share them with friends who like research.

Note: The Program Member or program element mentioned in this article is a concept that refers to the unit that makes up the program code, such as class, method, and member variable.

I. What is annotation?

Annotation provides a way to associate any information or metadata (metadata) with program elements. In some ways, annotation is used like a modifier and applied to declarations of packages, classes, constructor, method, member variables, parameters, and local variables. The information is stored in the "name = value" structure of annotation. Annotation is an interface that provides access to its information through the Java reflection API.

Annotation can be used to associate any information for a program element (class, method, member variable, etc. It should be noted that there is a basic rule here: annotaion cannot affect the execution of program code. No matter how much annotation is added or deleted, the code is always executed. In addition, although some annotation is accessed at runtime through the Java reflection API method, the Java interpreter ignores these annotation at work. It is precisely because the Java Virtual Machine ignores annotation that the annotation type does not work in the Code. Only through a supporting tool can the annotation type information be accessed and processed. This article will cover the standard annotation and meta-
Annotation type. The tools that accompany these annotation types are Java compilers (of course, they must be processed in some special way ).

Because of the above reasons, annotation is very easy to use. A local variable can be labeled by an annotation type named nonnull as an asserted that the local variable cannot be assigned a null value. However, we can compile an annotation code analysis tool to parse the Code with the preceding variables and try to verify this asserted. Of course, you do not have to write the code yourself. After JDK is installed, you can find the tool "apt" in the JDK/bin directory. It provides a framework for processing annotation: It scans annotation in the source code after it is started, and call the defined annotation processor to complete the work we want to complete (for example, verify the assertions in the previous example ). Here,
The powerful functions of annotation seem to replace tools such as XDoclet. As we go deeper, we will be more confident in this.
Note: For details, see the jsr250 specification:
Http://www.jcp.org/aboutJava/communityprocess/pfd/jsr250/

Ii. annotation definition:

This section describes annotation-related technologies. We will see the standard annotation type of java5.0. This standard type is the "Built-in" type mentioned earlier. They can be directly supported by javac. Fortunately, javac in Java Beta has added support for custom annotation.

1. Concepts and syntax of annotation:

First, the key concept is to understand that annotation is the annotation of information or metadata associated with a program element. It never affects Java program execution, but has an impact on auxiliary tools such as compiler warnings or document generators.

The following lists common annotation types. We should note the differences between annotation and annotation types:

A. annotation:
Annotation uses the new syntax brought about by java5.0, and its behavior is very similar to modifiers such as public and final. Each annotation has a name and number of Members> = 0. Each annotation member has the name and value (like JavaBean) called the name = value pair, and name = value carries annotation information.

B. annotation type:
The annotation type defines the annotation name, type, and member default value. An annotation type can be said to be a special Java interface. Its member variables are restricted, and the new syntax must be used to declare the annotation type. When we access annotation through the Java reflection API, the returned value will be an object that implements the annotation class interface. By accessing this object, we can easily access its annotation member. The subsequent sections will refer to the three quasi-annotation types contained in the Java. lang Package of java5.0.

C. annotation member:
The annotation member is declared in the form of a non-parameter method in the annotation type. The method name and return value define the name and type of the member. There is a specific default Syntax: Allow declaring the default value of any annotation Member: An Annotation can use the name = value pair as the value of an annotation member without defining the default value, you can also use the name = value pair to overwrite the default values of other members. Some similar class inheritance features. The constructor of the parent class can be used as the default constructor of the subclass, but can also be overwritten by the quilt class.

D. Marker annotation type:
An annotation type without Member definition is called marker annotation. This annotation type only uses its own existence or not to provide us with information. For example, override.

E. Meta-annotation:
Meta-annotation is also called meta-Annotation. It is used to declare annotation-type annotation. Java5.0 provides some standard meta-annotation types. The target and retention described below are meta-annotation.

F.tar get:
The target of annotation is a labeled program element. Target indicates the range of objects modified by annotation: annotation can be used for packages, types (class, interface, enumeration, annotation type) type members (methods, constructor methods, member variables, enumerated values), method parameters, and local variables (such as cyclic variables and catch parameters ). In the annotation type declaration, target can be used to better clarify the object to be modified.

G. Retention:
The retention of annotation defines the retention duration of the annotation: Some annotation only appears in the source code and is discarded by the compiler; others are compiled in the class file; annotation compiled in the class file may be ignored by the virtual machine, while others will be read when the class is loaded (Please note that the execution of the class is not affected, because annotation and class are separated in use ). This meta-annotation can be used to limit the "Life Cycle" of annotation.

H. Metadata:
Metadata is widely used in various computer development processes, so when we talk about metadata here, metadata usually refers to the information loaded by annotation or annotation itself.

2. Use standard annotation:
Java5.0 defines three standard annotation types in the Java. lang package:

A. Override:
Java. Lang. Override is a marker annotation type and is used as a annotation method. It indicates that the labeled method overload the parent class method and plays the role of assertion. If we use this annotation, the Java compiler will warn you of a compilation error when a method that does not overwrite the parent class method.
This annotaton is often used when we try to overwrite the parent class method and make sure that the method name is wrong.

The method of use is extremely simple: when using this annotation, you only need to add @ override before the modified method.
The following code uses @ override to modify a tostring method that attempts to overload the parent class, and there is a spelling error sample:
Listing 1:

@ Overridepublic string tosting () {// note that the method name is incorrectly spelled return "[" + super. tostring () + "]";}

B. deprecated:
Deprecated is also a marker annotation. When a type or type member is modified with @ deprecated, the compiler does not encourage the labeled program element. In addition, this modifier has a certain degree of "continuity": if we use this obsolete type or member in code through inheritance or overwrite, although the inherited or overwritten type or member is not declared as @ deprecated, the compiler still needs to issue an alert.
It is worth noting that the annotation type @ deprecated is different from the @ deprecated tag in javadoc: the former is recognized by the Java compiler, the latter is identified by the javadoc tool to generate documents (including descriptions of why a Program Member has passed, how it should be disabled or replaced ).
In java5.0, the Java compiler still looks for the javadoc tag @ deprecated as in the previous version and uses them to generate warning information. However, this situation will change in later versions. Now we should start to use @ deprecated to modify outdated methods instead of @ deprecated javadoc tag.
Listing 2:

The following is a piece of code using @ deprecated:/*** here is the @ deprecated declaration of javadoc. * @ deprecated no one has players for this format any more. use VHS instead. */@ deprecated public class Betamax {...}

C. suppresswarnings:
@ Suppresswarnings is used to warn the compiler to initialize classes, methods, member variables, and variables. In java5.0, The javac compiler provided by Sun provides the-xlint option for us to enable the compiler to warn against legal program code, which in turn represents a program error. For example, when we use a generic collection class without providing its type, the compiler will prompt a warning of "unchecked warning.

Generally, when this happens, we need to find the code that generates the warning. If it really indicates an error, we need to correct it. For example, if the warning information indicates that the switch statement in our Code does not cover all possible cases, we should add a default case to avoid this warning.
Similar to this, sometimes we cannot avoid this warning. For example, when we use a generic collection class that must interact with the old code of the non-generic, we cannot avoid this unchecked warning. At this time, @ suppresswarning will come in handy. Add @ suppresswarnings before calling the method to tell the compiler to stop warning about this method.
Suppresswarning is not a marker annotation. It has a member of the string [] type. The value of this Member is the forbidden warning name. For the javac compiler, the warning names that are valid by the-xlint option are also valid for @ suppresswarings, And the compiler ignores unrecognized warning names.

The annotation syntax allows annotation names followed by parentheses. The name = value pairs separated by commas are used to assign values to annotation members:
Listing 3:

@SuppressWarnings(value={"unchecked","fallthrough"})public void lintTrap() { /* sloppy method body omitted */ }

In this example, the suppresswarnings annotation type only defines a single member, so only one simple value = {...} is used as the name = value pair. Since the Member value is an array, braces are used to declare the array value.

Note: We can abbreviated annotation in the following cases: when annotation only has a single member and the member name is "value = ". In this case, you can save "value = ". For example, abbreviated suppresswarnings annotation:
Listing 4:

@SuppressWarnings({"unchecked","fallthrough"})

If the number of forbidden warnings declared by suppresswarnings is one, you can ignore the braces:

@SuppressWarnings("unchecked")

3. Annotation Syntax:

In the previous chapter, we can see the syntax for writing marker annotation and a single member annotation. The complete syntax is described as follows:

Annotation is composed of "@ + annotation type name + (name-value pairs separated by commas. The members can be in any order. If the annotation type defines the default value of a Member, this member can be omitted. The member value must be a compilation constant, embedded annotation, or array.

Next we will define an annotation type named reviews, which has a Member Composed of the @ review annotation array. This @ review annotation type has three members: "reviewer" is a string, "comment" is an optional string with default values, and "Grade" is a review. grade Enumeration type value.
Listing 5:

@Reviews({  // Single-value annotation, so "value=" is omitted here    @Review(grade=Review.Grade.EXCELLENT,            reviewer="df"),    @Review(grade=Review.Grade.UNSATISFACTORY,            reviewer="eg",            comment="This method needs an @Override annotation")})

Another important rule of annotation syntax is that no program member can have more than one annotation instance. For example, you can simply place multiple @ review annotation in a class. This is also the reason why the @ reviews annotation type array is defined in the above Code.

4. Annotation member type and value:

The annotation member must be a non-empty compile-time expression. The available Member types are: primitive type, String, class, enumerated type, annotation type, and arrays of the previous type.

The following defines an annotation type named uncheckedexceptions. Its members are an array of classes that extend the runtimeexception class.
Listing 6:

@UncheckedExceptions({    IllegalArgumentException.class, StringIndexOutOfBoundsException.class})

5. Annotation goals:

Annotation is usually placed before the type definition and member definition. However, it also appears before package, method parameters, and local variables. Next, let's discuss some of these less commonly used methods:

Package annotation appears before the package declaration.
The following example package-info.java contains an optional javadoc comment without any public type definition.
Listing 7:

/*** This package holds my custom annotation types.*/@com.davidflanagan.annotations.Author("David Flanagan")package com.davidflanagan.annotations;

When the package-info. Java file is compiled, it will generate a class named containing the package-info.class declared by annotation (special interface. This interface has no members. Its name package-info is not a valid Java identifier, so it cannot be used in Java source code. This interface is simply regarded as a placeholder for package annotation.

Annotation used to modify method parameters, catch parameters, and local variables only appears in the modifier positions of these Program Members. The Java class file format is not prepared for storing annotation for local variables or catch parameters, so these annotations are always kept at the source code level (source retention); The method parameter annotation can be saved in the class file, it can also be retained to the runtime.

Finally, note that the enumeration type definition does not allow any modifier to modify its enumerated values.

6. Annotation and default values:
In annotation, a member without a default value must have a member value. It is important to understand how default values are processed: the default values of Members defined by the annotation type are stored in the class file and not compiled into annotation. If we modify an annotation type to change the default value of its members, this change affects all Members who do not explicitly provide the member value in this type of annotation (that is, the member value of this Member is modified ). Even after the annotation type changes the default value of its members, annotation has never been re-compiled. This type of annotation (compiled before the change) is also affected.

Iii. Working Principle of annotation:

Annotation and reflection
In Java, the reflection API provided by Java. Lang. Reflect is expanded to read the annotation capability during runtime. Let's review what we mentioned earlier: After an annotation type is defined as runtime retention, it is visible at runtime, when the class file is loaded, the annotation stored in the class file will be read by the virtual machine. So how does reflect help us access the annotation in class?

The following describes the new features of Java. Lang. Reflect for annotation. Among them, java. Lang. Reflect. annotatedelement is an important interface, which represents a Program Member who provides the ability to query annotation. This interface is implemented by Java. Lang. Package and Java. Lang. Class, and indirectly implemented by the method class, constructor class, and Java. Lang. reflect field class. The method parameters in Annotation can be obtained through the getparameterannotations () method of the method class and constructor class.

The following code uses the isannotationpresent () method of the annotatedelement class to determine whether a method has the @ unstable annotation, so as to determine whether the method is stable:
Listing 8:

import java.lang.reflect.*;Class c = WhizzBangClass.class;                           Method m = c.getMethod("whizzy", int.class, int.class);  boolean unstable = m.isAnnotationPresent(Unstable.class);

The isannotationpresent () method is very useful for checking marker annotation. Because marker annotation does not have member variables, we only need to know whether the class method uses annotation modification. When processing Annotation with Members, we use the getannotation () method to obtain annotation member information (member name, member value ). Here we see a set of beautiful Java annotation systems: If annotation exists, the object implementing the corresponding annotation interface will be getannotation () method
Then, call the member method defined in the annotation type to conveniently obtain any member value.

In retrospect, if the annotation type is declared as runtime retention, we use the following code to access the member value of @ reviews annotation:
Listing 9:

Annotatedelement target = whizzbangclass. class; // obtain the queried annotatedelement // query annotatedelement's @ reviews annotation information reviews annotation = target. getannotation (reviews. class); // because the @ reviews annotation type member is an array of the @ review annotation type, // The review [] reviews are declared below to save the value member value of the @ reviews annotation type. Review [] reviews = annotation. value (); // query the member information of each @ review annotation for (review R: reviews) {review. grade = R. grade (); string reviewer = R. reviewer (); string comment = R. comment (); system. out. printf ("% s assigned a grade of % s and comment '% s' % N", reviewer, grade, comment );}

4. How to customize annotation?

1. Differences between annotation and interfaces:
Because the annotation type is an extraordinary interface, there are some differences between the two:

A. the annotation type uses the keyword @ interface instead of interface.
This keyword Declaration implies a message: it inherits the java. Lang. annotation. annotation interface, not an interface.

B. The annotation type and method definition are unique and restricted.
Methods of the annotation type must be declared as non-parameter and thrown without exceptions. These methods define annotation members: the method name is a member name, and the return value of the method becomes the member type. The Return Value Type of the method must be the primitive type, class type, enumeration type, annotation type, or a one-dimensional array with one of the preceding types as the element. After the method, you can use default and a default value to declare the default value of the member. null cannot be the default value of the member, which is very different from the method defined in non-annotation type.
The annotation type and its method cannot use the annotation type parameter or the member cannot be generic. Only methods whose return value type is class can use generic in the annotation type, because this method can use class conversion to convert various types to class.

C. The annotation type is similar to the interface type.
They can define constants and static member types (for example, enumeration type definition ). The annotation type can also be implemented or inherited as an interface.

2. instance:
Next, we will see how to define the annotation type example. It shows the annotation type declaration and the difference between @ interface and interface:
Listing 10:

Package COM. david Flanagan. annotations; import Java. lang. annotation. *;/*** use annotation to describe the labeled Members which are unstable and need to be changed */@ retention (retentionpolicy. runtime) Public @ interface unstable {}

The following example defines only one member. By naming this member as value, we can easily use this annotation quick declaration method:
Listing 11:

/*** Use the annotation definition of author to indicate the author of the Code in the Program */Public @ interface author {/** return the author name */string value ();}

The example below is more complex. The reviews annotation type has only one member, but the type of this Member is complex: An array composed of review annotation. The review annotation type has three members: grade, reviewer, a string member indicating the review name, and comment, a string member with default values.
List 12:

Import Java. lang. annotation. *;/*** the reviews annotation type has only one member. * However, this member type is complex: An array composed of review annotation */@ retention (retentionpolicy. runtime) Public @ interface reviews {review [] value ();}/*** the review annotation type has three members: * Enumeration type members: grade, * string type member reviewer that represents the review name, and * string type member comment with default values. */Public @ interface review {// The embedded Enumeration type public static Enum grade {excellent, satisfactory, unsatisfactory}; // The following method defines the annotation member grade (); string reviewer (); string comment () Default "";}

Finally, we define an annotation method to list all unchecked exceptions in Class running (this is not necessarily an error as mentioned above ). This annotation type uses an array as a unique member. Each element in the array is an exception class. To enhance reporting of unchecked exceptions (such exceptions are thrown at runtime), we can restrict the types of exceptions in the Code:
Listing 13:

public @interface UncheckedExceptions {    Class<? extends RuntimeException>[] value();}

V. Meta-Annotation

Annotation types can be marked by themselves. Java5.0 defines four standard meta-annotation types, which are used to provide instructions on other annotation types. These types and their supported classes can be found in the Java. Lang. annotation package. For more information, see the jdk5.0 manual.

1. Talk about target.
As a target of the meta-annotation type, which describes the types of Program Members modified by annotation. When an annotation type does not have a target, it will be treated as a normal annotation. When you modify a specific program member, it will play the role of its application. For example, when override is used for modifier, added the meta-annotation @ target to enable the compiler to check the annotation and remove the override that modifies the error type.

The target meta-annotation type has a unique value as a member. The type of this Member is Java. Lang. annotation. elementtype [], and elementtype is the enumerated type of program members that can be labeled.

2. Retention usage
We mentioned retention at the beginning of the article, but we didn't explain it in detail. Retention describes whether annotation is discarded by the compiler or stored in the class file. If annotation is stored in the class file, whether the class file is read by the virtual machine when it is loaded. By default, annotation is saved in the class file, but cannot be accessed by reflection during runtime. Retention has three values: source, class, and runtime. These values come from the enumeration type values of Java. Lang. annotation. retentionpolicy.

The retention meta-annotation type has a unique value as a member. Its value comes from the enumeration type value of Java. Lang. annotation. retentionpolicy.

3. appsented
Documented is a meta-annotation type used to describe other types of annotation which should be used as a public API of the labeled Program Member. Therefore, it can be documented by tools such as javadoc.

Incluented is a marker Annotation with no members.

4. inherited
@ Inherited meta-annotation is also a marker annotation, which describes that a labeled type is inherited. If an annotation type modified with @ inherited is used for a class, this annotation will be used for the subclass of this class.

Note: The @ inherited annotation type is inherited by the subclass of the labeled class. The class does not inherit annotation from the interface it implements, and the method does not inherit annotation from the method it loads.

When the retention of annotation marked by @ inherited annotation is retentionpolicy. runtime, the reflection API enhances this inheritance. If we use Java. lang. when reflect queries an annotation of the @ inherited annotation type, the reflection code check starts: Check the class and its parent class until the specified annotation type is found, or you can reach the top layer of the class inheritance structure.

Vi. Summary:

This article covers almost all concepts and knowledge points of annotation, from Annotation definition, syntax to working principle, how to customize annotation, to meta-annotation. There are also some supporting code snippets for reference. Although there are not many, they are concise and important. I think the key to using annotation is to use it. I hope this manual can help you make good use of annotation, which is also my greatest pleasure.

All articles with this logo are original by caoer (caoer), the blog blogger.
, Reprinted please indicate the origin and original author. Thank you very much.