Java 注解 Annotation

   <h2><strong>What</strong></h2>    <p>Annotation 是何物 ? <strong>@Override</strong> 相信 Java 程序员都不陌生，经常会在一些方法上看到这样一个符号，这个 <strong>@Override</strong> 便是一个Annotation。如：</p>    <pre>  <code class="language-java">@Override      public String toString() {          return super.toString();      }</code></pre>    <p><strong>Annotation：</strong> 中文译之为 <strong>注解</strong> ，是一种能够添加到 Java 源代码中的语法元数据，于 Java SE5中被引入。注解可用来将信息元数据与程序元素进行关联，可以作用于包、类、接口、方法、域、参数、注解之上。注解为我们在代码中添加信息提供了一种形式化的方法，使我们可以在稍后某个时刻非常方便的使用这些数据。</p>    <h2><strong>Why</strong></h2>    <p>注解在一定程度上是在将元数据与源代码文件结合在一起，而不是保存在外部文档中的大趋势下诞生的。注解的优点主要有：</p>    <ul>     <li>注解可以提供用来完整地描述程序所需要的信息；</li>     <li>注解可以将一些数据、格式的验证和测试工作抽取出来交由编译器；</li>     <li>注解可以用来生成描述符文件、新的类定义文件或者一些“样板”代码，有助于减轻编写“样板”代码的负担；</li>     <li>使用注解从某种程度上可以提高代码的可读性；</li>    </ul>    <h2><strong>注解分类</strong></h2>    <p>元注解：即专职用于创建其它注解的注解，Java提供了四种元注解：@Target、@Retention、@Documented 和 @ Inherited</p>    <p>@Target：该注解用于定义注解的作用域，值可以取枚举类型 ElementType 中的一个或多个，如果未指定Target值，则该注解可以作用于如下所有的域。</p>    <ul>     <li>TYPE：类/接口/枚举/Annotation 声明</li>     <li>FIELD：域/枚举常量声明</li>     <li>METHOD：方法声明</li>     <li>PARAMETER：参数声明</li>     <li>CONSTRUCTOR：构造函数声明</li>     <li>LOCAL_VARIABLE：局部变量声明</li>     <li>ANNOTATION_TYPE：Annotation 类型声明</li>     <li>PACKAGE：包声明</li>    </ul>    <p>@Retention：该注解表示需要在什么级别保存该注解信息，可选值为枚举类型 RetentionPolicy 中的一个：</p>    <ul>     <li>SOURCE：注解将被编译器丢弃，主要起 <strong>标记</strong> 作用，告诉编译器一些信息，如@Override 和 @SuppressWarnings；</li>     <li>CLASS：注解在 class 文件中可用，但是会被 JVM 丢弃，可用于编译时动态处理，如动态生成代码；</li>     <li>RUNTIME：注解将会一直保留，因此可以通过反射机制读取注解信息，@Deprecated 和 @SafeVarargs；</li>    </ul>    <p>@Documented ：将此注解保留在 Javadoc 中；</p>    <p>@Inherited：允许子类继承父类中的注解。</p>    <p>标准注解：Java内置了四种标准注解：@Override、@SuppressWarnings、@Deprecated 和 @SafeVarargs</p>    <p>@Override：表示当前的方法定义将会覆盖父类中的方法，如果当前方法签名与父类中的方法签名不一致，编译器将会发出错误提示信息；</p>    <p>@SuppressWarnings：关闭不当的编译器警告信息；</p>    <p>@Deprecated ：表示该方法已经被弃用，如果程序中使用到被该注解作用的方法，编译器会发出警告信息；</p>    <p>@SafeVarargs：该注解是 Java 1.7 新引入的一个注解，表示该注解作用的对象不会对其可变参数进行任何潜在不安全的修改</p>    <p>自定义注解：Java提供的注解数目相对比较少，不过我们可以通过自定义注解的方式创建符合自己程序需要的注解类型。</p>    <h2><strong>How</strong></h2>    <p>这部分主要介绍如何创建一个新的注解并根据程序需要获取注解信息进行处理。</p>    <h2><strong>定义注解</strong></h2>    <p>自定义注解之前，先看看 Java 标准注解是怎样定义的，从而对注解有个大致印象！</p>    <p>下面两段代码分别是 @Override 和 @SuppressWarnings 注解的定义。</p>    <pre>  <code class="language-java">@Target(ElementType.METHOD)  @Retention(RetentionPolicy.SOURCE)    //使用元注解设置注解作用域、保留策略等  public @interface Override {  }</code></pre>    <pre>  <code class="language-java">@Target( { ElementType.TYPE, ElementType.FIELD, ElementType.METHOD,          ElementType.PARAMETER, ElementType.CONSTRUCTOR,          ElementType.LOCAL_VARIABLE })  @Retention(RetentionPolicy.SOURCE)  public @interface SuppressWarnings {      public String[] value();      // 注解配置信息  }</code></pre>    <p>从上面两个标准注解定义中可以看出，注解的定义有点类似于接口定义，注解也会被编译成 .class 文件。</p>    <p>定义注解的步骤：</p>    <ol>     <li>使用 <strong>@interface</strong> 就可以定义一个注解，注解名紧随其后；</li>     <li>然后根据程序需要，使用 Java 元注解设置注解的作用域、保留级别、是否可继承等信息；</li>     <li>根据需要，在注解中包含一些元素用于表示一些配置参数，提供必要的注解信息以便于后续对注解进行分析处理。</li>    </ol>    <p>实例</p>    <pre>  <code class="language-java">@Target(ElementType.METHOD)              // 该注解可以作用于方法声明  @Retention(RetentionPolicy.RUNTIME)     // 该注解会一直保留到运行时  @Documented                            // 将注解信息保留到 Javadoc中                 @Inherited                            // 该注解可以被子类继承  public @interface Property {       int id();                          // int 类型元素 id       String msg() default "default msg";  // 默认值为 “default msg” 的 String 类型元素 msg  //   Boolean flag() default false;    // Invalide type 'Boolean' for annotaton member  }</code></pre>    <p>上面一段代码自定义了一个名为 Property 的注解，该注解可以作用于方法声明，内部包含两个配置参数 id 和 msg，使用注解时可通过这两个元素传递注解信息。</p>    <h2><strong>注解元素</strong></h2>    <p>注解中包含的方法声明即为注解元素，注解元素定义类似于接口中的方法定义，元素的类型即为所需参数的类型，如 int id()表示需要一个int类型值，不过注解元素可以通过使用default关键字定义默认值，如果在使用注解时，没有为设置了默认值的元素提供值，则会使用该元素的默认值。不包含注解元素的注解为 <strong>标记注解</strong> ，这类注解的存在只是为了提供某种标记信息，如@Override注解。</p>    <p>注解元素只能使用如下几种类型，使用其余类型时，编译器会给出错误提示：</p>    <ul>     <li>所有基本类型（int、char、double等）</li>     <li>String</li>     <li>Class</li>     <li>enum</li>     <li>Annotation（即嵌套注解）</li>     <li>以上类型的数组（注意只能是数组，而不能是容器类型）</li>    </ul>    <h2><strong>使用注解</strong></h2>    <pre>  <code class="language-java">public class Goods {        @Property(id = 1, msg = "per price")      public void price(){}        @Property(id = 2)      public void type(){}  }</code></pre>    <p>注解通过名值对的形式赋值，具有默认值的注解可以不赋值，从而使用默认值。上面这段代码在 Goods 类中创建了两个函数 price() 和 type()，这两个函数均使用了自定义的 Property 注解，price() 函数为配置参数 id 和 msg 都赋了值，而type()函数只设置了 id 的值，这意味着type()函数的 msg 为默认值“default msg”。</p>    <h2><strong>编写注解处理器</strong></h2>    <p>至此已经了解了如何创建和使用注解，然而如果没有注解处理器对注解信息进行加工处理的话，注解也就不能显示其强大功能了。Java SE5扩展了反射机制的 API，以帮助程序员构建这类工具。同时，还提供了一个外部工具 apt（Annotation Process Tool）帮助解析带有注解的 Java源码。所有注解均可以使用Mirror API 在编译时便获取类型信息，但只有@Retention 为 RetentionPolicy.RUNTIME 的注解可以在运行时使用Java反射机制获取数据。</p>    <p>下面代码是一个简单的注解处理器，用于读取上面的 Goods 类，并使用反射机制在运行时查找我们自定义的注解Property，通过Property注解获取方法的 id 和 msg。</p>    <pre>  <code class="language-java">public class PropertyTracker {        public static void trackerProperty(List<Integer> ids, Class cls){          for (Method method : cls.getDeclaredMethods()){              Property annot = method.getAnnotation(Property.class);              if (annot != null){                  print("The Annotation's id is: " + annot.id() + " msg is: " + annot.msg());                  ids.remove(new Integer(annot.id()));              }else {                  print("This method doesn't has Annotation - Property!");              }          }            for (Integer i : ids){              print("Warning! Missing Property - " + i);          }      }        public static void main(String[] args) {          List<Integer> propertys = new ArrayList<>(5);          Collections.addAll(propertys, 1, 2, 3, 4, 5);          trackerProperty(propertys, Goods.class);      }  }</code></pre>    <pre>  <code class="language-java">//Output:  The Annotation's id is: 2 msg is: default msg  The Annotation's id is: 1 msg is: per price  Warning! Missing Property - 3  Warning! Missing Property - 4  Warning! Missing Property - 5</code></pre>    <p>解析：</p>    <p>trackerProperty方法需要一个List 类型参数 ids 和 一个Class类型参数cls，然后它会找出cls中有的Property和缺失的Property。</p>    <p>trackerProperty方法中使用到了两个反射方法：</p>    <p>getDeclaredMethods()：返回一个包含该类中定义的所有方法的数组</p>    <p>getAnnotation()：返回实参指定类型的Annotation，如果调用者没有该类型的注解则返回null值。</p>    <p>通过使用注解对象 annot 的id()和msg()方法获取注解的id和msg信息。</p>    <h2><strong>快速赋值机制</strong></h2>    <p>当注解内部只有一个需要赋值的注解元素时，可以将该注解元素名设为value，从而提供一种快捷赋值方式。即使用该注解时，直接在括号内提供注解元素的值即可，而无需使用名值对的方式。</p>    <p>如下所示：</p>    <pre>  <code class="language-java">@Target({ElementType.METHOD, ElementType.FIELD})  @Retention(RetentionPolicy.RUNTIME)  @Documented  @Inherited  public @interface Person {      int value();      String sex() default "girl";      boolean student() default true;  }</code></pre>    <pre>  <code class="language-java">public class Chatlist {        @Person(1)      String per1 = "person1";        @Person(value = 2, sex = "boy", student = false)      String per2 = "person2";  }</code></pre>    <p>注解Person内部包含三个注解元素：value、sex和student，其中sex和student均有默认值，所以value是唯一需要赋值的注解元素，可以使用快速赋值机制。不过当需要赋值的元素不止一个时，则value也需要使用名值对的方式赋值，如per2所示。</p>    <p> </p>    <p>来自：http://www.jianshu.com/p/cac5be09922e</p>    <p> </p>