java 注释 : annotations 元数据

annotations : 注释

好处

1.文档编制
2.编译器检查
3.代码分析

JSR 175 是编程语言的元数据工具,为将元数据合并到核心java语言中提供正式理由和说明


基本知识:

注释采用"@"标记形式,后面是注释名称,然后在需要数据时,通过name=value对向注释提供数据
注释的三个基本种类:
    标记注释
        没有变量,注释显示简单,由名称标识,没有提供其他数据,(@fweiAnnotation)

    单一值注释
        与标记注释类似,但提供一段数据,(@fweiAnnotation("value"))

    完整注释
        有多个数据成员,使用完整的语法(@feiAnnotation(name1="value1",name2="value2"))

    可以在需要传送多个值时使用名-值对,
    还可以通过花括号为注释变量提供值数组
        @fwei2Annotation({
            @TODO(name="value",name1="value1"),
            @TODO(name="value",name1="value1"),
            @TODO(name="value",name1="value1"),
        })
        说明:fwei2Annotation注释类型是一个具有值的变量,与单一值注释类型相符,只是这里的单一值是数组
        该数组包含三个TODO注释,其中每个注释都是多值的.逗号分隔每个注释内的值,以及单个数组内的值

Override注释(标记注释)(标记注释没有成员变量)

仅用于方法(不用于类,包声明或其他构造)
指明注释的方法将覆盖超类中的方法


Deprecated注释(标记注释)

对不应再使用的方法进行注释

SuppressWarnings注释

忽视某部分warnings
SuppressWarnings注释的value值可以是单值或是数组
@SuppressWarings(value={"unchecked"})
@SuppressWarnings(value={"unchecked", "fallthrough"})



定制注释

Tiger中增加了一种新的类型--annotation type

@interface声明

定义新的注释类型,
package com.abcom.fwei.annotation;
public @interface FweiAnnotation{}
使用:
@com.abcom.fwei.annotation.FweiAnnotation    可以直接导入注释类型,直接使用@FweiAnnotation引用
public void testMethod(float amount,float rate){}
使用方法与内置注释类型的使用方法完全相同

添加成员

注释类型中的数据成员被设置成使用有限的信息进行工作.
定义数据成员不需要分别定义访问和修改的方法,
只需要定义一个方法,以成员的名称命名化,数据类型应该是该方法返回值的类型
package com.fwei.annotation
public @interface TODO{           
    String value();
}
使用:
import com.fwei.annotation.TODO

@com.fwei.annotation.TODO("fweiName")        //使用了简写方式
@com.fwei.annotation.TODO(value="fweiName")
public void testMethod(){}

说明:当注释类型只有一个成员变量,而且变量名为value时,才能使用上面(TODO的定义)的简写形式,

设置默认值

public @interface GroupTODO{
    public enum Severity{CRITICAL,IMPORTANT,TRIVIAL,DOCUMENTION};        //枚举
    Severity severity()
        default Severity.IMPORTANT;                    //定义默认值
    String item();
    String assignedTo();
    String dateAssigned();
}

定义默认值:在成员声明的后面添加关键字default,然后提供默认值.
默认值必须与成员变量的类型完全相同

使用:(没有指定severity成员)
@GroupTODO(
    item="item",
    assignedTo="assignedTo",
    dateAssigned("09/04/2009")
)
public void testMethod(){};

使用:(指定severity成员)
@GroupTODO(
    severity=GroupTODO.Severity.DOCUMENT,
    item="item",
    assignedTo="assignedTo",
    dateAssigned("09/04/2009")
)
public void testMethod(){};


对注释的注释

Target

ElementType类型(java.lang.annotation)
就个枚举类型,定义了注释类型可应用的不同程序元素
public enum ElementType{
    TYPE,
    FIELD,
    METHOD,
    PARAMETER,
    CONSTRUCTOR,
    LOCAL_VARIABLE,
    ANNOTATION_TYPE,
    PACKAGE
}
使用Target元注释时,至少要提供ElementType枚举值中的一个并指定注释可以应用的程序元素.

用法:
@Target({
    ElementType.TYPE,
    ElementType.METHOD,
    ElementType.CONSTRUCTOR,
    ElementType.ANNOTATION_TYPE
    })
public @interface TODO{
    String value();
}
表明:TODO应用于类型,方法,构造函数和其他注释类型.


设置保持性

Retention

与java编译器处理注释的注释类型的方式有关
public enum RetentionPolicy{
    SOURCE,        //按照规定使用注释,但是并不将它保留到编译后的类文件中
    CLASS,        //将注释保留在编译后的类文件中,但是在运行时忽略它
    RUNTIME        //将注释保留在编译后的类文件中,并在第一次加载类时读取它
}
使用:
@Retention(RetentionPolicy.SOURCE)
public @interface SupperssWarnings{}


添加公共文档

Documented

表示注释应该出现在类的javadoc中,
默认情况下注释不包括在javadoc中.

使用:
@Documented
@Retention(RetentionPolicy.RUNTIME)        //使用Documented注释类型时必须设置Retention(保持性)为RUNTIME
public @interface TODO{}

说明:使用Documented注释时必须设置Retention(保持性)为RUNTIME,javadoc使用虚拟机从其类文件(而非源文件)中加载 信息


设置继承

Inherited

使用:
@Documented
@Inherited
@Retention(RetentionPolicy.RUNTIME)
public @interface TODO{}

 

参考文档