目录

注解概述

JDK内置的注解

元注解

Override注解 

Deprecated

注解中自定义属性

value();

注解中的属性类型

属性是一个数组

Retention的源代码

反射注解

通过反射机制获取属性对象的值 

通过反射机制获取注释信息

注解概述

    1、注解，或者叫做注释类型，英文单词是：Annotation

    2、注解Annotation是一种引用数据类型。编译之后也是生成xxx.class文件。

    3、怎么自定义注解呢？语法格式？

         [修饰符列表] @interface 注解类型名{

         }
    4、注解怎么使用，用在什么地方？

        第一：注解使用时的语法格式是：
            @注解类型名
        
        第二：注解可以出现在类上、属性上、方法上、变量上等....
        注解还可以出现在注解类型上。

自定义注解：MyAnnotation 

public @interface MyAnnotation {
    // ??????
}

@MyAnnotation
public class AnnotationTest01 {

    @MyAnnotation
    private int no;

    @MyAnnotation
    public AnnotationTest01(){}

    @MyAnnotation
    public static void m1(){
        @MyAnnotation
        int i = 100;
    }

    @MyAnnotation
    public void m2(@MyAnnotation
                   String name,
                   @MyAnnotation
                   int k){

    }
}

@MyAnnotation
interface MyInterface {

}

@MyAnnotation
enum Season {
    SPRING,SUMMER,AUTUMN,WINTER
}

注解修饰注解。 

@MyAnnotation
public @interface OtherAnnotation {
}

默认情况下，注解可以出现在任意位置。

JDK内置的注解

 java.lang包下的注解

元注解

        什么是元注解？
            用来标注“注解类型”的“注解”，称为元注解。

        常见的元注解有哪些？
            Target
            Retention
        
        关于Target注解：
            这是一个元注解，用来标注“注解类型”的“注解”
            这个Target注解用来标注“被标注的注解”可以出现在哪些位置上。

            @Target(ElementType.METHOD)：表示“被标注的注解”只能出现在方法上。
            @Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, MODULE, PARAMETER, TYPE})
                表示该注解可以出现在：
                    构造方法上
                    字段上
                    局部变量上
                    方法上
                    ....
                    类上...
        
        关于Retention注解：
            这是一个元注解，用来标注“注解类型”的“注解”
            这个Retention注解用来标注“被标注的注解”最终保存在哪里。

            @Retention(RetentionPolicy.SOURCE)：表示该注解只被保留在java源文件中。
            @Retention(RetentionPolicy.CLASS)：表示该注解被保存在class文件中。
            @Retention(RetentionPolicy.RUNTIME)：表示该注解被保存在class文件中，并且可以被反射机制所读取。

Override注解 

源码：

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.SOURCE)
public @interface Override {
}

@Override

标识性注解，给编译器做参考的。
编译器看到方法上有这个注解的时候，编译器会自动检查该方法是否重写了父类的方法。
如果没有重写，报错。

这个注解只是在编译阶段起作用，和运行期无关！

// @Override这个注解只能注解方法。
// @Override这个注解是给编译器参考的，和运行阶段没有关系。
// 凡是java中的方法带有这个注解的，编译器都会进行编译检查，如果这个方法不是重写父类的方法，编译器报错。

Deprecated

Deprecated这个注解标注的元素已过时。
这个注解主要是向其它程序员传达一个信息，告知已过时，有更好的解决方案存在。

// 表示这个类已过时。
@Deprecated
public class AnnotationTest03 {

    @Deprecated
    private String s;

    public static void main(String[] args) {
        AnnotationTest03 at = new AnnotationTest03();
        at.doSome();
    }

    @Deprecated
    public void doSome(){
        System.out.println("do something!");
    }

    // Deprecated这个注解标注的元素已过时。
    // 这个注解主要是向其它程序员传达一个信息，告知已过时，有更好的解决方案存在。
    @Deprecated
    public static void doOther(){
        System.out.println("do other...");
    }
}

class T {
    public static void main(String[] args) {
        AnnotationTest03 at = new AnnotationTest03();
        at.doSome();

        AnnotationTest03.doOther();

        try {
            Class c = Class.forName("java.util.Date");
            Object obj = c.newInstance();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

注解中自定义属性

public @interface MyAnnotation {

    /**
     * 我们通常在注解当中可以定义属性，以下这个是MyAnnotation的name属性。
     * 看着像1个方法，但实际上我们称之为属性name。
     * @return
     */
    String name();

    /*
    颜色属性
     */
    String color();

    /*
    年龄属性
     */
    int age() default 25; //属性指定默认值

}

public class MyAnnotationTest {

    // 报错的原因：如果一个注解当中有属性，那么必须给属性赋值。（除非该属性使用default指定了默认值。）
    /*@MyAnnotation
    public void doSome(){

    }*/

    //@MyAnnotation(属性名=属性值,属性名=属性值,属性名=属性值)
    //指定name属性的值就好了。
    @MyAnnotation(name = "zhangsan", color = "红色")
    public void doSome(){

    }
}

value();

如果一个注解的属性的名字是value，并且只有一个属性的话，在使用的时候，该属性名可以省略。

public @interface MyAnnotation {

    /*
    指定一个value属性。
     */
    String value();

    //String email();
}

public class MyAnnotationTest {

    @MyAnnotation(value = "hehe")
    public void doSome(){

    }

    @MyAnnotation("haha")
    public void doOther(){

    }
}

注解中的属性类型

注解当中的属性可以是哪一种类型？
        属性的类型可以是：
            byte short int long float double boolean char String Class 枚举类型
            以及以上每一种的数组形式。

public @interface MyAnnotation {

    int value1();

    String value2();

    int[] value3();

    String[] value4();

    Season value5();

    Season[] value6();

    Class parameterType();

    Class[] parameterTypes();
}

public enum Season {
    SPRING,SUMMER,AUTUMN,WINTER
}

属性是一个数组

    // 数组是大括号
    @OtherAnnotation(age = 25, email = {"zhangsan@123.com", "zhangsan@sohu.com"}, seasonArray = Season.WINTER)
    public void doSome(){

    }

    // 如果数组中只有1个元素：大括号可以省略。
    @OtherAnnotation(age = 25, email = "zhangsan@123.com", seasonArray = {Season.SPRING, Season.SUMMER})
    public void doOther(){

    }

Retention的源代码

            //元注解    
            public @interface Retention {
                //属性
                RetentionPolicy value();
            }
            
        RetentionPolicy的源代码：
            public enum RetentionPolicy {
                 SOURCE,
                 CLASS,
                 RUNTIME
            }

            //@Retention(value=RetentionPolicy.RUNTIME)
            @Retention(RetentionPolicy.RUNTIME)
            public @interface MyAnnotation{}

反射注解

通过反射机制获取属性对象的值 

//只允许该注解可以标注类、方法
@Target({ElementType.TYPE, ElementType.METHOD})
// 希望这个注解可以被反射
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotation {

    /*
    value属性。
     */
    String value() default "沈阳大街";
}

//Test

@MyAnnotation("山东菏泽曹县")
public class MyAnnotationTest {

    //@MyAnnotation
    int i;

    //@MyAnnotation
    public MyAnnotationTest(){

    }

    @MyAnnotation
    public void doSome(){

        //@MyAnnotation
        int i;
    }

    public static void main(String[] args) throws Exception{
        // 获取这个类
        Class c = Class.forName("lit.jxxy.rg1508.java.annotation5.MyAnnotationTest");
        // 判断类上面是否有@MyAnnotation
        //System.out.println(c.isAnnotationPresent(MyAnnotation.class)); // true
        if(c.isAnnotationPresent(MyAnnotation.class)){
            // 获取该注解对象
            MyAnnotation myAnnotation = (MyAnnotation)c.getAnnotation(MyAnnotation.class);
            //System.out.println("类上面的注解对象" + myAnnotation); // @lit.jxxy.rg1508.java.annotation5.MyAnnotation()
            // 获取注解对象的属性怎么办？和调接口没区别。
            String value = myAnnotation.value();
            System.out.println(value);
        }

        // 判断String类上面是否存在这个注解
        Class stringClass = Class.forName("java.lang.String");
        System.out.println(stringClass.isAnnotationPresent(MyAnnotation.class)); // false
    }

通过反射机制获取注释信息

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface MyAnnotation {

    /*
    username属性
     */
    String username();

    /*
    password属性
     */
    String password();
}

    @MyAnnotation(username = "admin", password = "456456")
    public void doSome(){

    }

    public static void main(String[] args) throws Exception{
        // 获取MyAnnotationTest的doSome()方法上面的注解信息。
        Class c = Class.forName("lit.jxxy.rg1508.java.annotation6.MyAnnotationTest");
        // 获取doSome()方法
        Method doSomeMethod = c.getDeclaredMethod("doSome");
        // 判断该方法上是否存在这个注解
        if(doSomeMethod.isAnnotationPresent(MyAnnotation.class)) {
            MyAnnotation myAnnotation = doSomeMethod.getAnnotation(MyAnnotation.class);
            System.out.println(myAnnotation.username());
            System.out.println(myAnnotation.password());
        }
    }

注解在开发中的作用

     需求：
            假设有这样一个注解，叫做：@Id
            这个注解只能出现在类上面，当这个类上有这个注解的时候，
            要求这个类中必须有一个int类型的id属性。如果没有这个属性
            就报异常。如果有这个属性则正常执行！

// 表示这个注解只能出现在类上面
@Target(ElementType.TYPE)
// 该注解可以被反射机制读取到
@Retention(RetentionPolicy.RUNTIME)
public @interface MustHasIdPropertyAnnotation {

}

// 这个注解@Id用来标注类，被标注的类中必须有一个int类型的id属性，没有就报异常。

@MustHasIdPropertyAnnotation
public class User {
    int id;
    String name;
    String password;
}

/*
自定义异常
 */
public class HasNotIdPropertyException extends RuntimeException {
    public HasNotIdPropertyException(){

    }
    public HasNotIdPropertyException(String s){
        super(s);
    }
}

    public static void main(String[] args) throws Exception{
        // 获取类
        Class userClass = Class.forName("lit.jxxy.rg1508.java.annotation7.User");
        // 判断类上是否存在Id注解
        if(userClass.isAnnotationPresent(MustHasIdPropertyAnnotation.class)){
            // 当一个类上面有@MustHasIdPropertyAnnotation注解的时候，要求类中必须存在int类型的id属性
            // 如果没有int类型的id属性则报异常。
            // 获取类的属性
            Field[] fields = userClass.getDeclaredFields();
            boolean isOk = false; // 给一个默认的标记
            for(Field field : fields){
                if("id".equals(field.getName()) && "int".equals(field.getType().getSimpleName())){
                    // 表示这个类是合法的类。有@Id注解，则这个类中必须有int类型的id
                    isOk = true; // 表示合法
                    break;
                }
            }

            // 判断是否合法
            if(!isOk){
                throw new HasNotIdPropertyException("被@MustHasIdPropertyAnnotation注解标注的类中必须要有一个int类型的id属性！");
            }

        }
    }

JDK内置注解

@Override

 @Override的作用是标记重写父类的方法，@Override只能用于标记方法。编译器编译时会校验使用@Override标记的方法是否与父类对应方法形式一致。例：

Man.java

public class Man{
    private String name;
    private float height;
    private int weight;
    public void setName(String name){};
    public void setHeight(float height){};
    public void setWeight(int weight){};
}

Woman.java

public class Woman extends Man{
    @Override
    public void setHeight(int height){
        //编译时会报错，因为形参与父类不同
    }
}

@Deprecated

 @Deprecated用于提示所修饰的元素(类、方法、变量等)已过时，继续使用可能会发生危险或者存在更好的选择。JDK更新过程中不会删除过时的API，而是为这些API加上@Deprecated标签，使得JDK不建议用户继续使用该API的同时，也保证使用了过时API的旧项目能正常运行。

@SuppressWarnings

 @SupressWarnings的作用是抑制编译器警告。可以用于修饰所有成员。例如一个成员定义了却未使用(unused)，就可以使用@SupressWarnings("unused")来抑制成员未使用(unused)的警告。再例如使用原类型时抑制警告：

@SupressWarnings({"unused","rawtypes"})
ArrayList list = new ArrayList();   //使用了ArrayList不带类型参数的原类型

元注解

概述

 元注解是用来修饰注解定义的注解。

@Retention

 @Retention限定了被修饰注解的生命周期。它的取值有：

//注解在源文件(java文件)中有效(源文件保留)，编译时丢弃
@Retention(RetentionPolicy.SOURCE)        
//默认值。注解在class文件中有效(class保留)，但不会加载到JVM
@Retention(RetentionPolicy.CLASS)  
//注解在运行时有效(运行时保留)，JVM会保留注释,所以程序运行时可以通过反射机制获取到注解信息
@Retention(RetentionPolicy.RUNTIME)       

例：

@Retention(RetentionPolicy.SOURCE)
public @interface MyAnnotation{
    String[] value();
}

@Target

 @Target指定被修饰注解可以用来修饰程序中的哪些元素。取值有：

TYPE:被修饰注解可以修饰class/interface/@interface/enum。
FIELD:被修饰注解可以修饰field。
METHOD:被修饰注解可以修饰method。
PARAMETER:被修饰注解可以修饰parameter。
CONSTRUCTOR:被修饰注解可以修饰constructor。
LOCAL_VARIABLE:被修饰注解可以修饰local variable(局部变量)。
ANNOTATION_TYPE:被修饰注解可以修饰Annotation type。
PACKAGE:被修饰注解可以修饰package。
TYPE_PARAMETER:被修饰注解可以修饰class parameter(泛型类型参数)。
TYPE_USE:被修饰注解可以修饰任何使用类的元素。

例：

@Target({TYPE,METHOD,CONSTRUCTOR})   //该注解可以用于修饰 类、方法、构造器
public @interface MyAnnotation{
    String[] value();
}

**注意：**若未指明@Target元注解，则该注解默认可以修饰程序中的所有元素。

@Documented

 被@Documented修饰的注解修饰的成员在API文档中也会显示出相应的注解，而默认API文档中是不显示注解的。

@Inherited

 @Inherited修饰的注解将具有继承性，即如果一个类被@Inherited修饰的注解修饰，这个类的子类将自动具有该注解。

自定义注解

使用@interface关键字定义注解：

public @interface MyAnnotation{
    /*
      成员变量以“无参方法”的形式声明，“无参方法”的返回值即成员变量的值
    */
    int value();
    String message();
}

使用方法：

//修饰类
@MyAnnotation(value = 1,message = "type")
public class Person{
    //修饰属性
    @MyAnnotation(value = 2,message = "field")
    private String name;
    //修饰构造器
    @MyAnnotation(value = 3,message = "constructor")
    public Person(String name){
        this.name = name;
    }
    //修饰方法
    @MyAnnotation(value = 4,message = "method")
    public String getName(){
        return name;
    }
    //修饰参数
    public void setName(@MyAnnotation(value = 5,message = "param") String name){
        this.name = name;
    }    
}

使用default关键字指定成员变量默认值：

public @interface MyAnnotation{
    int value() default 0;
    String message() default "";
}

此时再使用时可以不用带参数从而直接使用默认值：

@MyAnnotation
public class Person{
    //也可以仅指定部分参数
    @MyAnnotation(message = "default test")
    public Person(String name){
        this.name = name;
    }
}

如果注解中没有成员，这个注解就是一个标识。例如@Override。

通过反射机制获取RUNTIME注解

定义注解

MyAnnotation.java

@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface MyAnnotation{
    int value() default 0;
    String message() default "";
}

Person类

Person.java

@MyAnnotation(message = "Person")
public class Person{
    @MyAnnotation(value = 1,message = "name")
    private String name;
    @MyAnnotation(value = 2,message = "height")
    private float height;
    @MyAnnotation(value = 3,message = "weight")
    private int weight;
    
    @MyAnnotation(value = 4,message = "Person()")
    public Person(String name,float height,int weight){
        this.name = name;
        this.height = height;
        this.weight = weight;
    }
    
    @MyAnnotation(value = 5,message = "setName()")
    public void setName(@MyAnnotation(value = 6,message = "paramName")String name){
        this.name = name;      
    }
    @MyAnnotation(value = 7,message = "getName()")
    public String getName(){
        return name;
    }
    
    @MyAnnotation(value = 8,message = "setHeight()")
    public void setHeight(@MyAnnotation(value = 9,message = "paramHeight")float height){
        this.height = height;
    }
    @MyAnnotation(value = 10,message = "getHeight()")
    public float getHeight(){
        return height;
    }
    
    @MyAnnotation(value = 11,message = "setWeight()")
    public void setWeight(@MyAnnotation(value = 12,message = "paramWeight")int weight){
        this.weight = weight;
    }
    @MyAnnotation(value = 13,message = "getWeight()")
    public int getWeight(){
        return weight;
    }
    
}

获取注解的方法

//java.lang.annotation.Annotation
public Annotation[] getAnnotations()

//java.lang.annotation.Annotation
public <A extends Annotation> A getAnnotation(Class<A> annotationClass)

//java.lang.annotation.Annotation
public Annotation[] getDeclaredAnnotations()

//java.lang.annotation.Annotation
public <A extends Annotation> A getDeclaredAnnotation(Class<A> annotationClass)

获取类的注解

Class<Person> clas = Person.class;
//获取注解
MyAnnotation annotation = clas.getDeclaredAnnotation(MyAnnotation.class);
//获取注解成员"value()"值
int value = annotation.value();
//获取注解成员"message()"值
String message = annotation.message();
System.out.println("value:"+value+",message:"+message);

获取属性的注解

Class<Person> clas = Person.class;
//获取属性
Field name = clas.getDeclaredField("name");
//使可访问
name.setAccessible(true);
//获取注解
MyAnnotation annotation = name.getDeclaredAnnotation(MyAnnotation.class);
//获取注解成员"value()"值
int value = annotation.value();
//获取注解成员"message()"值
String message = annotation.message();
System.out.println("value:"+value+",message:"+message);

获取构造器的注解

Class<Person> clas = Person.class;
//获取构造器
Constructor<Person> cons =
    clas.getDeclaredConstructor(String.class,float.class,int.class);
//使可访问
cons.setAccessible(true);
//获取注解
MyAnnotation annotation = cons.getDeclaredAnnotation(MyAnnotation.class);
//获取注解成员"value()"值
int value = annotation.value();
//获取注解成员"message()"值
String message = annotation.message();
System.out.println("value:"+value+",message:"+message);

获取方法的注解

Class<Person> clas = Person.class;
//获取方法
Method method = clas.getDeclaredMethod("setName",String.class);
//使可访问
method.setAccessible(true);
//获取注解
MyAnnotation annotation = method.getDeclaredAnnotation(MyAnnotation.class);
//获取注解成员"value()"值
int value = annotation.value();
//获取注解成员"message()"值
String message = annotation.message();
System.out.println("value:"+value+",message:"+message);

获取参数注解

Class<Person> clas = Person.class;
//获取方法(或构造器)
Method method = clas.getDeclaredMethod("setHeight",float.class);
//使可访问
method.setAccessible(true);
//获取参数
Parameter param = (method.getParameters())[0];
//获取注解
MyAnnotation annotation = param.getDeclaredAnnotation(MyAnnotation.class);
//获取注解成员"value()"值
int value = annotation.value();
//获取注解成员"message()"值
String message = annotation.message();
System.out.println("value:"+value+",message:"+message);

注意：

 只有包含@Retention(RetentionPolicy.RUNTIME)修饰的注解才能使用反射机制获取。

说明注释

概述

 Java中有三种注释形式：1.以//开头的单行注释；2.以/*开头*/结尾的多行注释；3.以/**开头*/结尾的说明注释。

 说明注释允许在程序中嵌入对程序的说明信息，生成API文档作为API调用时的指导。

 说明注释中可以包含以@开头标签，用于对特定信息的描述，例如作者、版本、方法参数和方法返回值等。

常用的说明注释标签

1.@author:用于类注释。说明类的作者。例：

/**
*@author Lishaoyin
*/
public class Person{}

2.@version:用于类注释。说明类的版本。例：

/**
*@version 1.0
*/
public class Person{}

3.@since:用于类和任意类成员注释。说明API是在JDK的哪个版本添加的。例：

/**
*@since 1.8
*/
public void setName(String name){}   //API在JDK1.8添加

4.@deprecated:用于类和任意类成员注释。说明该类成员已过期，不建议使用。例：

/**
*@deprecated this field is deprecated,you can use better choice
*/
private String name;

5.@throws:用于方法和构造器注释。说明方法或构造器可能会抛出的异常。例：

/**
*@throws java.io.IOException this method maybe throws IOException
*/
public void setHeight(float height) throws IOException {}

6.@exception:作用与@throws相同。

7.@see:用于类和任意类成员注释。在生成的文档中指定一个API文档超链接，用户点击后可跳转至指定内容的API文档。例：

/**
*@see java.lang.annotation.Annotation
*/
public class Person{}

8.@param:用于方法和构造器注释。说明方法或构造器的参数。例：

/**
*@param name String,person's name
*@param height float,person's height
*@param weight int,person's weight
*/
public Person(String name,float height,int weight){}

9.@return:用于方法注释。说明方法的返回值。

/**
*@return String,person's name
*/
public String getName(){}

TODO

 TODO是一种用法简单的计划标记工具，其作用是将计划指示信息嵌入到注释中(可嵌入到三种注释中的任意一种)。编译后可使用快速定位跳转到指定计划位置，继续完成计划中未完成的工作。例：

public class Person{
    
    public String getName(){
       //TODO function to get person's name 
    }
    
    public void setHeight(float height){
       /*TODO function to set person's height*/
    }
    
    /**
    *@param weight int,set person's weight
    *TODO function to set person's weight
    */
    public String setWeight(int weight){}
    
}

示例

Person.java

/**
*@author Lishaoyin
*version 1.0
*@since 1.8
*/
public class Person{
    
    private String name;
    private float height;
    private int weight;
    
    /**
    *@param name String,init person's name
    *@param height float,init person's height
    *@param weight int,init person's weight
    */
    public Person(String name,float height,int weight){
        this.name = name;
        this.height = height;
        this.weight = weight;
    }
    
    /**
    *@param name String,set person's name
    */
    public void setName(String name){
        this.name = name;
    } 
    /**
    *@return String,get person's name
    */
    public String getName(){
        return name;
    }
    
    /**
    *@param height float,set person's height
    */
    public void setHeight(float height){
        this.height = height;
    } 
    /**
    *@return float,get person's height
    */
    public float getHeight(){
        return height;
    }
    
    /**
    *@throws java.io.IOException this method maybe throws IOException
    *@see java.io.IOException
    *@param weight int,set person's weight
    */
    public void setWeight(int weight) throws java.io.IOException {
        this.weight = weight;
    }
    /**
    *@return int,get person's weight
    */
    public int getWeight(){
        return weight;
    }
    
    //TODO function to set person's sex
    
}