Java annotation (注解)

简介：

---

在Java计算机编程语言中，注释是一种可以添加到Java源代码的语法元数据。可以注解类，方法，变量，参数和包。与Javadoc标签一样，可以从源文件中读取Java注解。与Javadoc标记不同，Java注解也可以嵌入和读取编译器生成的类文件。这允许Java VM在运行时保留注解并通过反射读取。可以用Java中的现有元注释创建元注解。

注解有很多用法：

• 1. 为编译器提供信息(Information for the compiler) ——编译器能直接使用注解检查错误(detect errors)和禁止警告(suppress warnings)。
• 2. 编译期和部署时处理(Compile-time and deployment-time processing) —— 软件工具可以使用注解生成代码，XML文件等待。
• 3. 运行期处理(Runtime processing) —— 一些注解可以在运行期被检测。

---

注解基础知识：  

---

　　注解格式：  

---

在最简单的形式中，注释如下所示：

@Entity

at符号（@）向编译器指示后面的内容是注释。在以下示例中，注释的名称为Override：

@Override

void mySuperMethod() { ... }

注释可以包含可以命名或未命名的元素，并且这些元素有值：

@Author(   

name = "Benjamin Franklin",   

date = "3/27/2003"

)

class MyClass() { ... }

要么

@SuppressWarnings(value = "unchecked")

void myMethod() { ... }

如果只有一个名为的元素value，那么名称可以省略，如：

@SuppressWarnings（ “unchecked”） void myMethod（）{...} 如果注释没有元素，则可以省略括号，如上例所示@Override。

也可以在同一声明中使用多个注释：

@Author（name =“Jane Doe”）

@EBook

class MyClass {...}

如果注释具有相同的类型，则称为重复注释：

@Author（name =“Jane Doe”）

@Author（姓名=“John Smith”）

class MyClass {...}  

---

　　可以使用注解的位置：

---

注解可以应用于声明：类，字段，方法和其他程序元素的声明。当在声明中使用时，每个注解通常按照惯例出现在它自己的行上。

从Java SE 8发行版开始，注解也可以应用于类型的使用。这里有些例子：

类实例创建表达式：    

new @Interned MyObject（）;

　　输入：    

myString =（@ NonNull String）str;

　　implements 条款：    

class UnmodifiableList <T>实现        

@Readonly List <@Readonly T> {...}

　　抛出的异常声明：    

void monitorTemperature（）抛出        

@Critical TemperatureException {...}

这种形式的注释称为类型注解。  

---

　　内置注解：

---

Java定义了一组内置于该语言中的注释。在七个标准注释中，三个是java.lang的一部分，其余四个是从java.lang.annotation导入的。

应用于Java代码的注释：

1. @Override - 检查方法是否为覆盖。如果在其中一个父类或已实现的接口中找不到该方法，则会导致编译错误。
2. @Deprecated - 将方法标记为过时。如果使用该方法，则会发出编译警告。
3. @SuppressWarnings - 指示编译器禁止在注释参数中指定的编译时警告。 应用于其他注释的注释（也称为“Meta Annotations”）：
4. @Retention - 指定标记注释的存储方式 - 无论是仅代码，编译到类中，还是通过反射在运行时可用。
5. @Documented - 标记另一个注释以包含在文档中。
6. @Target - 标记另一个注释以限制可以应用注释的Java元素类型。
7. @Inherited - 标记要继承到带注释类的子类的另一个注释（默认情况下，注释不会继承到子类）。 从Java 7开始，该语言增加了三个附加注释。
8. @SafeVarargs - 自Java 7以来，使用泛型varargs参数抑制方法或构造函数的所有调用者的警告。
9. @FunctionalInterface - 指定类型声明旨在成为Java 8以来的功能接口。
10. @Repeatable - 指定自Java 8以来，注释可以多次应用于同一声明。

---

@Deprecated

@Deprecated注解表示被标记的元素时被废弃的(deprecated)，不应该再被使用。当代码使用被@Deprecated注解的方法，属性或者类的时候，编译器会给出警告(warning)。当一个元素被废弃了，它将会在Javadoc文档里打上@deprecated标记(@deprecated tag)，就像下面的例子一样。Javadoc注释和注解都使用@开头，并不是巧合，他们在概念上是相关联的。当然，我们也会看到Javadoc tag是以小写字母d开头，而注解是以大写字母D开头。

// Javadoc comment follows /** * @deprecated * explanation of why it was deprecated */ @Deprecated static void deprecatedMethod() { }

@Override

@Override 注解告诉编译器被注解的元素时重写(override)父类的。关于重写方法的信息，可以参见接口与继承(Interfaces and Inheritance)

// mark method as a superclass method // that has been overridden @Override int overriddenMethod() { }

重写方法，并不是强制需要这个注解，但这个注解可以帮助避免错误。如果一个被@Override标记的方法，没有正确重写父类的方法，编译器会报错。

@SuppressWarnings

@SuppressWarnings注解告诉编译器不要产生某个的警告。在下面的例子里，使用了一个被废弃(deprecated)的方法，然后编译器会产生一个警告(warning)。在这种情况下，这个注解要会抑制编译器产生警告。

// use a deprecated method and tell // compiler not to generate a warning @SuppressWarnings("deprecation") void useDeprecatedMethod() { // deprecation warning // - suppressed objectOne.deprecatedMethod(); }

每个编译期警告都有一个类型。Java语言规范列出了两种类型:deprecation 和unchecked。当接口是使用泛型前的遗留代码时，就会产生unchecked警告。为了抑制多个类型的警告，可以使用下面语法：

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

@SafeVarargs @SafeVarargs注解应用于一个方法或者构造函数，表示代码不会在可变参数(varargs)上进行不安全的操作。当@SafeVarargs注解被使用时，与可变参数相关(varargs)的unchecked警告都会被抑制。

@FunctionalInterface @FunctionalInterface注解是Java 8新加入的一个注解，用于表示类型是打算用于函数式接口的。

用于其他注解的注解(Annotations That Apply to Other Annotations)

注解用于其他的注解被叫做元注解(meta-annotations)。在java.lang.annotation里定义了很多元注解。

@Retention

@Retention注解指明被标记的注解如何存储： 
1. RetentionPolicy.SOURCE 表示被标记的注解，仅仅只在代码级被保留，同时会被编译器忽略； 
2. RetentionPolicy.CLASS 该标记表示被标记的注解会被编译器保留，但仅仅在编译期保留，但是会被JVM忽略； 
3. RetentionPolicy.RUNTIME 该标记的注解，表示会被JVM保留，可以在运行时被使用。

@Documented

@Documented注解指明被注解的元素，会被Javadoc工具生成到Javadoc文档里(默认，注解是不会包含在Javadoc里的)。更多信息，可以参见Javadoc工具页。

@Target

@Target注解用于注解可以用于哪些元素。一个target注解可以指定下面元素类型值的一种： 
1. ElementType.ANNOTATION_TYPE 应用于一个注解类型 
2. ElementType.CONSTRUCTOR 应用于构造函数 
3. ElementType.FIELD 应用于类的属性 
4. ElementType.LOCAL_VARIABLE 应用于局部变量 
5. ElementType.METHOD 应用于方法 
6. ElementType.PACKAGE 应用于包 
7. ElementType.PARAMETER 应用于方法的参数 
8. ElementType.TYPE 应用于类的元素

@Inherited

@Inherited注解表示这个注解可以被从父类继承(默认是不可以的)。当用户判断类是否被注解时，同时类并没有直接被注解，这时会去查询父类是否被注解。@Inherited注解只能在class上使用。

@Repeatable

@Repeatable注解是被Java 8新引入的，表示注解可以在同一个声明或类型上使用多次。

---

参考：

https://blog.csdn.net/shuanghujushi/article/details/52159300

https://docs.oracle.com/javase/tutorial/java/annotations/QandE/questions.html

https://en.wikipedia.org/wiki/Java_annotation