Java中，注解初探（一）注解的引入和元注解
一. 注解的引入
在Java开发中，注解无所不在。注解是Java SE5引入的重要语言特性之一。在Java SE5中，内置了三种常用注解：
- @Override，表示当前定义的方法将覆盖父类中相同方法签名的方法。用于覆盖方法签名的正确性，被覆盖的方法如果不小心拼写错误，编译器会发出错误提示。该注解用来为程序员提供覆盖方法的编译时检查。对应的jdk源码如下：
package java.lang;
import java.lang.annotation.*;
/**
* Indicates that a method declaration is intended to override a
* method declaration in a supertype. If a method is annotated with
* this annotation type compilers are required to generate an error
* message unless at least one of the following conditions hold:
*
* -
* The method does override or implement a method declared in a
* supertype.
*
-
* The method has a signature that is override-equivalent to that of
* any public method declared in {@linkplain Object}.
*
*
* @author Peter von der Ahé
* @author Joshua Bloch
* @jls 9.6.1.4 @Override
* @since 1.5
*/
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.SOURCE)
public @interface Override {
}
- @Deprecated，表示当前定义的方法或类不再建议使用。但在当前版本中该方法或类仍然可以正常使用。在当前版本或新版本中，将有方法或类可以代替这个方法或类提供相同的服务，在某些方面，新的方法或类优于当前的方法或类的实现。并且，以后的版本中，将不会更新该方法或类，或者会移除该方法或类的这种实现。在使用开源类库的时候，遇到@Deprecated的方法，建议查询相关的替换方法。对应的jdk源码如下：
package java.lang;
import java.lang.annotation.*;
import static java.lang.annotation.ElementType.*;
/**
* A program element annotated @Deprecated is one that programmers
* are discouraged from using, typically because it is dangerous,
* or because a better alternative exists. Compilers warn when a
* deprecated program element is used or overridden in non-deprecated code.
*
* @author Neal Gafter
* @since 1.5
* @jls 9.6.3.6 @Deprecated
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(value={
CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE})
public @interface Deprecated {
}
- @SuppressWarnings，关闭指定的编译器警告。该注解标注的目标为类、字段、函数、函数入参、构造函数和函数的局部变量。建议注解标注在最接近警告发生的位置。这样使得该注解尽可能少的忽略需要显示的警告，而刚好能够忽略需要忽略的警告。对应的jdk源码如下：
package java.lang;
import java.lang.annotation.*;
import static java.lang.annotation.ElementType.*;
/**
* Indicates that the named compiler warnings should be suppressed in the
* annotated element (and in all program elements contained in the annotated
* element). Note that the set of warnings suppressed in a given element is
* a superset of the warnings suppressed in all containing elements. For
* example, if you annotate a class to suppress one warning and annotate a
* method to suppress another, both warnings will be suppressed in the method.
*
* As a matter of style, programmers should always use this annotation
* on the most deeply nested element where it is effective. If you want to
* suppress a warning in a particular method, you should annotate that
* method rather than its class.
*
* @author Josh Bloch
* @since 1.5
* @jls 4.8 Raw Types
* @jls 4.12.2 Variables of Reference Type
* @jls 5.1.9 Unchecked Conversion
* @jls 5.5.2 Checked Casts and Unchecked Casts
* @jls 9.6.3.5 @SuppressWarnings
*/
@Target({
TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE})
@Retention(RetentionPolicy.SOURCE)
public @interface SuppressWarnings {
/**
* The set of warnings that are to be suppressed by the compiler in the
* annotated element. Duplicate names are permitted. The second and
* successive occurrences of a name are ignored. The presence of
* unrecognized warning names is not an error: Compilers must
* ignore any warning names they do not recognize. They are, however,
* free to emit a warning if an annotation contains an unrecognized
* warning name.
*
* The string {@code "unchecked"} is used to suppress
* unchecked warnings. Compiler vendors should document the
* additional warning names they support in conjunction with this
* annotation type. They are encouraged to cooperate to ensure
* that the same names work across multiple compilers.
* @return the set of warnings to be suppressed
*/
String[] value();
}
从jdk内置的三个注解的源码可以看出：这三个注解本身，是被几个基本的注解所定义的。其中，
- @Override被@Target、@Retention所定义；
- @Deprecated被@Documented、@Retention、@Target所定义；
- @SuppressWarnings被@Target、@Retention所定义。
在Java8中，提供了5个元注解，专门用于其他注解（包括5个注解本身）的创建。下面将逐一对其进行介绍。
二. 元注解
Java8中提供了五个元注解。@Target、@Retention、@Documented、@Inherited、@Repeatable（jdk8加入）。其中，对应的源码如下：
- @Target的部分源码（不包括类的文档注释）
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Target {
/**
* Returns an array of the kinds of elements an annotation type
* can be applied to.
* @return an array of the kinds of elements an annotation type
* can be applied to
*/
ElementType[] value();
}
- @Retention的部分源码（不包括类的文档注释）
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Retention {
/**
* Returns the retention policy.
* @return the retention policy
*/
RetentionPolicy value();
}
- @Documented的部分源码（不包括类的文档注释）
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Documented {
}
- @Inherited的部分源码（不包括类的文档注释）
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Inherited {
}
- @Repeatable的部分源码（不包括类的文档注释）
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Repeatable {
/**
* Indicates the containing annotation type for the
* repeatable annotation type.
* @return the containing annotation type
*/
Class<? extends Annotation> value();
}
从五个元注解的源码可以看出：这五个元注解本身，都是由@Documented、@Retention、@Target三个元注解所定义。
下面引用Java编程思想（第五版）中的表格，来解释注解里的参数类型。
上述表格对元注解的作用及参数进行了总结。对于每一个注解的作用，现强调如下：
（1）@Target表示注解可以用于哪些地方
（2）@Retention表示注解的保存时长
（3）@Documented表示该注解保存在Javadoc中
（4）@Inherited表示允许子类继承父类的注解
（5）@Repeatable表示允许一个注解可以被使用一次或者多次
下面把ElementType的源码和RetentionPolicy的源码粘贴出来，方便参阅：
package java.lang.annotation;
/**
* The constants of this enumerated type provide a simple classification of the
* syntactic locations where annotations may appear in a Java program. These
* constants are used in {@link Target java.lang.annotation.Target}
* meta-annotations to specify where it is legal to write annotations of a
* given type.
*
* The syntactic locations where annotations may appear are split into
* declaration contexts , where annotations apply to declarations, and
* type contexts , where annotations apply to types used in
* declarations and expressions.
*
*
The constants {@link #ANNOTATION_TYPE} , {@link #CONSTRUCTOR} , {@link
* #FIELD} , {@link #LOCAL_VARIABLE} , {@link #METHOD} , {@link #PACKAGE} ,
* {@link #PARAMETER} , {@link #TYPE} , and {@link #TYPE_PARAMETER} correspond
* to the declaration contexts in JLS 9.6.4.1.
*
*
For example, an annotation whose type is meta-annotated with
* {@code @Target(ElementType.FIELD)} may only be written as a modifier for a
* field declaration.
*
*
The constant {@link #TYPE_USE} corresponds to the 15 type contexts in JLS
* 4.11, as well as to two declaration contexts: type declarations (including
* annotation type declarations) and type parameter declarations.
*
*
For example, an annotation whose type is meta-annotated with
* {@code @Target(ElementType.TYPE_USE)} may be written on the type of a field
* (or within the type of the field, if it is a nested, parameterized, or array
* type), and may also appear as a modifier for, say, a class declaration.
*
*
The {@code TYPE_USE} constant includes type declarations and type
* parameter declarations as a convenience for designers of type checkers which
* give semantics to annotation types. For example, if the annotation type
* {@code NonNull} is meta-annotated with
* {@code @Target(ElementType.TYPE_USE)}, then {@code @NonNull}
* {@code class C {...}} could be treated by a type checker as indicating that
* all variables of class {@code C} are non-null, while still allowing
* variables of other classes to be non-null or not non-null based on whether
* {@code @NonNull} appears at the variable's declaration.
*
* @author Joshua Bloch
* @since 1.5
* @jls 9.6.4.1 @Target
* @jls 4.1 The Kinds of Types and Values
*/
public enum ElementType {
/** Class, interface (including annotation type), or enum declaration */
TYPE,
/** Field declaration (includes enum constants) */
FIELD,
/** Method declaration */
METHOD,
/** Formal parameter declaration */
PARAMETER,
/** Constructor declaration */
CONSTRUCTOR,
/** Local variable declaration */
LOCAL_VARIABLE,
/** Annotation type declaration */
ANNOTATION_TYPE,
/** Package declaration */
PACKAGE,
/**
* Type parameter declaration
*
* @since 1.8
*/
TYPE_PARAMETER,
/**
* Use of a type
*
* @since 1.8
*/
TYPE_USE
}
package java.lang.annotation;
/**
* Annotation retention policy. The constants of this enumerated type
* describe the various policies for retaining annotations. They are used
* in conjunction with the {@link Retention} meta-annotation type to specify
* how long annotations are to be retained.
*
* @author Joshua Bloch
* @since 1.5
*/
public enum RetentionPolicy {
/**
* Annotations are to be discarded by the compiler.
*/
SOURCE,
/**
* Annotations are to be recorded in the class file by the compiler
* but need not be retained by the VM at run time. This is the default
* behavior.
*/
CLASS,
/**
* Annotations are to be recorded in the class file by the compiler and
* retained by the VM at run time, so they may be read reflectively.
*
* @see java.lang.reflect.AnnotatedElement
*/
RUNTIME
}
以上的内容，为注解的引入和元注解的一些基本概念。对于jdk中的注解，jdk本身提供了内置的注解处理器，从而实现注解的作用。下一篇关于注解的文章将探索注解处理器的编写和注解的一些常见应用相关。