java原生注解

  概念：

 注解（Annotation）,元数据（Meta data）的一种形式，提供了程序本身之外的数据。是从jdk1.5才引入的特性，注解与类、接口、枚举在同一个层次，并可以应用于包、类型、构造方法、方法、成员变量、参数、本地变量的声明中。

  语法：

1. 以@Interface关键字定义
2. 注解包含成员，成员以无参数的方法的形式被声明。其方法名和返回值定义了该成员的名字和类型。
3. 成员赋值是通过@Annotation(name=value)的形式。
4. 注解需要标明注解的生命周期，注解的修饰目标等信息，这些信息是通过元注解实现的。

  注解元素数据类型

• 所有基本类型（int,float,boolean等）
• String
• Class
• enum
• Annotation
• 以上类型的数组

注解分类

 注解分为元注解和基本内置注解

 元注解

  适用于其他注解的注解。
jdk1.5版本定义了4个标准的元注解类型，如下：

• @Target(目标注解–表示这个注解能放在什么位置上)
  @Target可以选择的位置如下

  Name	Describe
  ElementType.TYPE	类、接口（包括注解）、枚举
  ElementType.FIELD	成员变量
  ElementType.METHOD	方法
  ElementType.PARAMETER	参数
  ElementType.CONSTRUCTOR	构造器
  ElementType.LOCAL_VARIABLE	局部变量
  ElementType.ANNOTATION_TYPE	注解
  ElementType.PACKAGE	包
  ElementType.TYPE_PARAMETER	泛型(jdk1.8新增)
  ElementType.TYPE_USE	使用类型，可以用于标注任意类型除了class(jdk1.8新增)
  ElementType.MODULE	模块(jdk1.9新增)

  @Retention(RetentionPolicy.CLASS)
  @Documented
  @Target(ElementType.METHOD)
  public @interface MetadataDemo {
  }
  
  @Target({METHOD,TYPE})
  @Retention(RetentionPolicy.RUNTIME)
  @Inherited
  @Documented
  public @interface JDBCConfig {
       String ip();
       int port() default 3306;
       String database();
       String encoding();
       String loginName();
       String password();
  }
  

  如果一个注解没有指定@Target注解，则此注解可以用于除了类型参数（TYPE_PARAMETER）和类型使用（TYPE_USE）以外的任何地方
• @Retention
  标明注解的生命周期
  • RetentionPolicy.SOURCE
    标记的注解只保留在源层中，编译器将忽略它，用于检测代码（注解只存在在源代码中，编译成class文件之后就消失了，如@Override）
  • RetentionPolicy.CLASS
    编译器在编译时保留标记的注释，但是java虚拟机（jvm）会忽略它。（注解在java文件编译成class文件后，依然存在，但是运行起来后就没有了）主要用于编译时生成额外的文件，如xml、java文件等,而且CLASS也是@Retention的默认值
  • RetentionPolicy.RUNTIME
    标记的注解由jvm保留，以便运行时环境可以使用它（注解在运行起来之后依然存在，程序可以通过反射获取这些信息）

这3个生命周期分别对应于：Java源文件(.java文件) —> .class文件 —> 内存中的字节码

• @Inherited
  当一个类继承了拥有此注解的类时，即使当前类没有任何注解。只要父类的注解拥有该注解，则在子类中可以获取到此注解。

  @Retention(RetentionPolicy.RUNTIME)
  @Documented
  @Target(ElementType.TYPE)
  @Inherited
  public @interface MetadataDemo {
  }
  @MetadataDemo
  public class init{}
  public class after extends init{}
  通过类反射可以获取到 after父类的注解@MetadataDemo
  

• @Documented
  标记注解，用于描述其他类型的注解应该被作为被标注的程序成员的公共API，因此可以被例如javadoc此类的工具文档化。

jdk1.8之后又新增了两个元注解

• @Repeatable(重复注解)
  被标记的注解可以多次应用于相同的声明或类型使用
  在Java8之前重复使用注解的解决方案，但可读性不是很好。如下：

  public @Interface Authority{
  		String role();
  }
  public @Interface Authorities{
  		 Authority[] value();
  }
  public class RepeatAnnotationUseOldVersion {
  	 	@Authorities({
  		 	@Authority(role="Admin"),
  		 	@Authority(role="Manager")
  		 	})
  	    public void doSomeThing(){
  	    }
  }
  

  上面的代码，就是由另一个注解来存储重复注解，在使用的时候，用存储注解@Authorities来扩展重复注解，我们再来看看使用 @Repeatable的效果

  @Repeatable(Authorities.class)
  public @interface Authority {
      String role();
  }
  public @interface Authorities {
      Authority[] value();
  }
  public class RepeatAnnotationUseNewVersion {
      @Authority(role="Admin")
      @Authority(role="Manager")
      public void doSomeThing(){ }
  }
  

  上面的代码，与之前不同的地方说，创建重复注解@Authority时，加上@Repeatable，指向存储注解@Authorities，在使用时候，直接可以重复使用@Authority。
• @Native
  提示程序可以从本机代码（c\c++）引用java中定义的常量值（JNI）
  

 内置注解

jdk1.5内置了3个注解

• @Deprecated
  意思是说此方法或类已经过时，不再建议使用。
  在新版本中有其他方法或类可以代替这个使用，以后的版本
• @Override
  覆盖超类（父类）中的方法声明。
  使用此注解必须满足以下条件中的一个否则编译器或报错
  1. 该方法确实覆盖或实现了在超类中声明的方法。
  2. 该方法具有一个覆盖的签名–相当于在object中声明的任何公共方法的签名。
• @SuppressWarnings
  指示应在带注解的元素（以及包含在注解中的所有程序元素）。注意，在给定元素中被抑制的警告集是在所有包含元素中被抑制的警告的超集。
  还要保证抑制影响的范围最小。
  例如，如果你注解一个类以抑制一个警告，并注解一个方法来抑制另一个，两个警告将在方法中被抑制。

  	public class SuppressWarnings {
  
  	    /**
  	     * 变量单个类型的警告
  	     */
  	    @java.lang.SuppressWarnings("unused")
  	    public void unused() {
  	        String s = "";
  	    }
  	
  	    /**
  	     * 抑制多个类型的警告
  	     * @param item 元素
  	     */
  	    @java.lang.SuppressWarnings({"unchecked", "rawtypes"})
  	    public void addItems(String item){
  	        List items = new ArrayList();
  	        items.add(item);
  	    }
  	
  	    /**
  	     * 抑制所有类型的警告
  	     * @param item
  	     */
  	    @java.lang.SuppressWarnings("all")
  	    public void all(String item) {
  	        List items = new ArrayList();
  	        items.add(item);
  	    }
  	}
  

  @SuppressWarnings可以使用属性列表如下：

  Name	Describe
  all	禁止所有警告
  boxing	禁止与装箱/拆箱操作相关的警告
  cast	强制转换以抑制与强制转换操作相关的警告
  dep-ann	用于抑制相对于已弃用注解的警告
  deprecation	以抑制相对于弃用的警告
  fallthrough	在switch语句中，通过fallthrough来抑制与丢失中断相关的警告
  finally	抑制与最终块相关的不返回的警告
  hiding	以抑制相对于隐藏变量的本地警告
  incomplete-switch	在switch语句(enum案例)中， incomplete-switch用来抑制相对于丢失条目的警告
  javadoc	禁止与javadoc警告相关的警告
  nls	使用nls来抑制相对于非nls字符串的警告。
  null	抑制相对于空值分析的警告
  rawtypes	拒绝与使用原始类型相关的警告
  resource	用于抑制与使用类型为Closeable的资源相关的警告的资源
  restriction	限制禁止与使用不鼓励或禁止引用相关的警告
  serial	抑制相对于可串行化类缺少serialVersionUID字段的警告
  static-access	静态访问，抑制相对于不正确的静态访问的警告
  static-method	静态方法，用于抑制相对于可以声明为静态的方法的警告
  super	来抑制相对于在没有超级调用的情况下重写方法的警告
  synthetic-access	用于抑制相对于内部类的未优化访问的警告的合成访问
  sync-override	在覆盖同步方法时，由于缺少同步而取消警告
  unchecked	以抑制与未选中操作相关的警告
  unqualified-field-access	不限定字段访问来抑制与字段访问不限定相关的警告
  unused	抑制与未使用代码和死代码相关的警告

jdk1.7新增了1个注解

• @SafeVarargs
  用来抑制“堆污染“警告
  程序员断言注释的方法或构造函数的主体不会对其varargs（可变）参数执行潜在的不安全的操作。将此注解应用于方法或构造函数时，会取消关于不可还原变量（varargs）类型的未经检查的警告，并在调用站点上取消有关参数化数组创建的未检查警告。
  使用条件：
   只能用在参数长度可变的方法或构造方法上，且方法必须声明未static或final，否则会出现编译错误。
  开发人员必须确保这个方法的实现中对泛型类型的处理不会引发类型安全问题

  	public static <T> T userVar(T...args)//Possible heap pollution from parameterized vararg type
      {
          System.out.println(args.length);
          return args.length>0?args[0]:null;
      }
  
      public static void main(String[] args)
      {
      	System.out.println(userVar(new ArrayList<System>()));//Unchecked generics array creation for varargs parameter
      }
  

  显然没有使用@SafeVarargs时，泛型方法声明时编译器会发出警告说泛型极可能造成堆污染，被调用时编译器发出警告-未经检查的泛型数组创建。
  反之使用@SafeVarargs时，会消出这些警告。

  堆污染：参数化类型的变量（泛型）引用不属于该参数化类型的对象。

  @SafeVarargs // Not actually safe!
  static void m(List<String>... stringLists) {
      Object[] array = stringLists;
      List<Integer> tmpList = Arrays.asList(42);
      array[0] = tmpList; // Semantically invalid, but compiles without warnings
      String s = stringLists[0].get(0); // Oh no, ClassCastException at runtime!
  }
  

jdk1.8又新增了1个注解

• @FunctionalInterface（函数式接口）
  主要用于lambda表达式
  特点：
   1. 该注解只能标记在”有且仅有一个抽象方法“的接口上。
   2. JDK1.8新增的接口中的静态方法和默认方法，都不算是抽象方法。
   3. 接口默认继承java.lang.Object,所以如果接口显示声明覆盖了Object中的方法，那么也不算抽象方法。
   4. 该注解也不是必须的，如果一个接口符合“函数式接口”定义，那么加不加该注解都没有影响。加上该注解能够更好地让编译器进行检查。如果编写的不是函数式接口，但是加上了@FunctionalInterface,那么编译器会报错。
  正确的函数式接口

  @FunctionalInterface
  public interface TestInterface{
      
      //抽象方法
      public void sub();
      
      //java.lang.Object中的方法不是抽象方法
      public boolean equals(Object var1);
      
      //default 不是抽象方法
      public default void defaultMethod(){
      }
      
      //static不是抽象方法
      public static void staticMethod(){
      }
  }