Java 注解详解 (annotation)

注解是java5的新特性。注解可以看做一种注释或者元数据（metadata），可以把它插入到我们的java代码中，用来描述我们的java类，从而影响java类的行为。

使用java注解一般来说主要有三种目的

构建时指示: retentionpolicy.source

编译期指示: retentionpolicy.class

运行时指示: retentionpolicy.runtime

java注解可以用在构建期。当构建我们的工程时，构建进程会编译源码、生成xml文件，打包编译后的代码和文件到jar包。构建过程一般由构建工具自动完成，常用的构建工具有ant、maven。构建工具在构建时会自动扫描我们的代码，当遇到构建期注解时，会根据注解的内容生成源码或者其它文件。

一个java注解由一个@符后面跟一个字符串构成，类似于这样：

java注解中一般包含一些元素，这些元素类似于属性或者参数，可以用来设置值，比如我们有一个包含两个元素的@entity注解:

上面注解中有两个元素，<code>tablename</code>和<code>primarykey</code>，它们各自都被赋予了自己的元素值。

注解可以用于描述一个类、接口、方法、方法参数、字段、局部变量等。在下边这个例子中，注解分别用在了类、字段、方法、参数和局部变量中：

java本身提供了三个内置注解，他们分别是：

<code>@deprecated</code>可以用来描述一个类、方法或者字段，表示java不赞成使用这些被描述的对象，如果我们使用了这些类、方法或者字段，编译器会给我们警告。<code>@deprecated</code>注解使用方法如下：

在我们实际应用中，在使用<code>@deprecated</code>注解时，最好同时使用java doc的<code>@deprecated</code>符号，用来描述当前类、方法或者字段是不赞成使用的，并且告诉开发者应该用哪个对象替换，如下面例子：

<code>@override</code>注解是一个编译时注解，它主要用在一个子类的方法中，当被注解的子类的方法在父类中找不到与之匹配的方法时，编译器会报错。 当我们在子类中覆盖父类的方法时，就要用到<code>@override</code>注解，这样，如果父类中的方法名称或参数发生改变时，如果子类没有做相应的调整编译器便会报错，这就是<code>@override</code>注解所起到的作用。当然<code>@override</code>注解不是强制使用的，但我还是推荐大家尽量使用它。下面是一个@override注解的例子：

<code>@suppresswarnings</code>注解的作用是使编译器忽略掉编译器警告。比如，如果我们的一个方法调用了一个<code>@deprecated</code>方法，或者做了一个不安全的类型转换，此时编译器会生成一个警告。如果我们不想看到这些警告，我们就可以使用<code>@suppresswarnings</code>注解忽略掉这些警告：

从上面内置注解可以看到，注解很方便也很有用，很多时候我们也需要创建我们自己的注解。创建注解其实和创建类或接口一样简单：

上面代码便创建了一个<code>@myapplication</code>注解，它一共有四个元素。<code>@interface</code>关键字就代表这是一个注解类型，所以使用<code>@interface</code>关键字就可以创建注解了。

需要注意的是，注解中的每个元素定义类似于接口中的方法定义。每个元素定义包含一个数据类型和名称，注解元素的数据类型可以是java基本数据类型、string、数组，但不能是复杂对象类型。

下面这段代码演示了如何使用注解：

我们可以通过<code>default</code>关键字为某个元素设置默认值，当一个元素被设置默认值之后，这个元素便成了注解的可选元素。

下面我们为<code>@myannotation</code>注解的<code>value</code>元素设置一个默认值：

当<code>value</code>元素设置默认值之后，再使用时我们就可以省略掉<code>value</code>元素，此时的<code>value</code>值采用的是默认值：

元注解就是注解的注解。我们可以通过元注解来控制描述我们自定义注解的行为。

<code>@retention</code>用来定义当前注解的作用范围，如果我们要把我们的自定义注解限制为运行时有效，那么我们可以使用<code>@retention</code>注解进行指定：

注意<code>@myannotation</code>注解上面的<code>@retention</code>的值：

上面这个注解会告诉编译器和jvm，这个注解需要在运行时有效，jvm会在运行时通过反射机制获取注解信息，关于如何在运行时利用反射获取注解信息，最后面会进行介绍。<code>@retention</code>注解的值一共有三种：

retentionpolicy.source : 注解只存在于源码中，不会存在于.class文件中，在编译时会被忽略掉

retentionpolicy.class：注解只存在于.class文件中，在编译期有效，但是在运行期会被忽略掉，这也是默认范围

retentionpolicy.runtime：在运行期有效，jvm在运行期通过反射获得注解信息

<code>@target</code>注解用来约束自定义注解可以注解java的哪些元素。比如下面这个例子：

这个例子中，<code>@target</code>的值是<code>elementtype.method</code>，通过它的名称可以看出，这个自定义注解只能注解类的方法。

<code>elementtype</code>的值一共有以下几种：

elementtype.annotation_type

elementtype.constructor

elementtype.field

elementtype.local_variable

elementtype.method

elementtype.package

elementtype.parameter

elementtype.type

其中大部分通过名字就能看出它的作用，不过有两个需要单独介绍一下：

elementtype.annotation_type：元注解类型，只能用来注解其它的注解，例如@target和@retention。

elementtype.type：可以用来注解任何类型的java类，如类、接口、枚举、或者注解类。

<code>@inherited</code>注解表示当前注解会被注解类的子类继承。比如有一个自定义注解：

如果有一个类使用了上面这个注解：

那么这个类的子类也会继承这个注解：

因为<code>mysubclass</code> 继承了<code>myclass</code>，而<code>myclass</code>的注解<code>@myannotation</code>是可继承的，最终<code>mysubclass</code>也会有<code>@myannotation</code>注解。

<code>@documented</code>的作用是告诉javadoc工具，当前注解本身也要显示在java doc中。比如我们用<code>@document</code>注解了我们的自定义注解：

如果一个类使用了这个注解：

那么当生成<code>mysuperclass</code>的javadoc的时候，<code>@myannotation</code>也会出现在javadoc当中。

上面对注解做了一个详细介绍，具体该如何使用我们的自定义注解呢？其实在现实应用中，我们的自定义注解一般都是起到运行时指示的作用，也就是运行时注解。对于运行时注解，我们可以通过反射机制获得注解信息。

比如我们有一个自定义注解：

并用这个注解注解了一个类：