元注解

@Target

java.lang.annotation.ElementType.TYPE：//类、接口（包括注解类型）和枚举的声明
java.lang.annotation.ElementType.FIELD：//字段声明（包括枚举常量）
java.lang.annotation.ElementType.METHOD：//方法声明
java.lang.annotation.ElementType.PARAMETER：//参数声明
java.lang.annotation.ElementType.CONSTRUCTOR：//构造函数声明
java.lang.annotation.ElementType.LOCAL_VARIABLE：//本地变量声明
java.lang.annotation.ElementType.ANNOTATION_TYPE：//注解类型声明
java.lang.annotation.ElementType.PACKAGE：//包声明
java.lang.annotation.ElementType.TYPE_PARAMETER：//类型参数声明，JavaSE8引进，可以应用于类的泛型声明之处java.lang.annotation.ElementType.TYPE_USE：JavaSE8引进，此类型包括类型声明和类型参数声明，是为了方便设计者进行类型检查，例如，如果使用@Target（ElementType.TYPE_USE）对@NonNull进行标记，则类型检查器可以将@NonNull class C {...} C类的所有变量都视为非null

注意：如果一个注解没有指定@Target注解，则此注解可以用于除了TYPE_PARAMETER和TYPE_USE以外的任何地方。

以下我们看看ElementType.TYPE_PARAMETER和ElementType.TYPE_USE的使用示例，对于其他的ElementType注解元素，看其说明就知道怎么用了：

声明由ElementType.TYPE_PARAMETER标记的@NotEmpty注解：

package org.springmorning.demo.javabase.annotation.meta;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE_PARAMETER)
public @interface NotEmpty {
}

声明由ElementType.TYPE_USE标记的@NotEmpty注解：

package org.springmorning.demo.javabase.annotation.meta;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE_USE)
public @interface NotNull {
}

以下示例代码说明了这两种Target注解元素的使用区别，ElementType.TYPE_USE包含了ElementType.TYPE和ElementType.TYPE_PARAMETER

package org.springmorning.demo.javabase.annotation.meta;

import java.util.ArrayList;

//泛型类型声明时，使用TYPE_USE类型，编译通过
class A <@NotNull TT>{}

//泛型类型声明时，使用使用TYPE_PARAMETER类型，编译通过
public class TypeParameterAndTypeUseAnnotation<@NotEmpty T>{

    //使用TYPE_PARAMETER类型，会编译不通过
//    public @NotEmpty T test(@NotEmpty T a){
//        new ArrayList<@NotEmpty String>();
//            return a;
//    }

    //使用TYPE_USE类型，编译通过
    public @NotNull T test(@NotNull T a){
        new ArrayList<@NotNull String>();
        return a;
    }
}

@Retention 注解的作用

注解@Retention可以用来修饰注解，是注解的注解，称为元注解。
Retention注解有一个属性value，是RetentionPolicy类型的，Enum RetentionPolicy是一个枚举类型，
这个枚举决定了Retention注解应该如何去保持，也可理解为Rentention 搭配 RetentionPolicy使用。

RetentionPolicy有3个值：CLASS RUNTIME SOURCE

按生命周期来划分可分为3类：
1、RetentionPolicy.SOURCE：注解只保留在源文件，当Java文件编译成class文件的时候，注解被遗弃；
2、RetentionPolicy.CLASS：注解被保留到class文件，但jvm加载class文件时候被遗弃，这是默认的生命周期；
3、RetentionPolicy.RUNTIME：注解不仅被保存到class文件中，jvm加载class文件之后，仍然存在；

这3个生命周期分别对应于：Java源文件(.java文件) —> .class文件 —> 内存中的字节码。
那怎么来选择合适的注解生命周期呢？
首先要明确生命周期长度 SOURCE < CLASS < RUNTIME ，所以前者能作用的地方后者一定也能作用。
一般如果需要在运行时去动态获取注解信息，那只能用 RUNTIME 注解，比如@Deprecated使用RUNTIME注解

如果要在编译时进行一些预处理操作，比如生成一些辅助代码（如 ButterKnife），就用 CLASS注解；
如果只是做一些检查性的操作，比如 @Override 和 @SuppressWarnings，使用SOURCE 注解。

注解@Override用在方法上，当我们想重写一个方法时，在方法上加@Override，当我们方法的名字出错时，编译器就会报错
注解@Deprecated，用来表示某个类或属性或方法已经过时，不想别人再用时，在属性和方法上用@Deprecated修饰
注解@SuppressWarnings用来压制程序中出来的警告，比如在没有用泛型或是方法已经过时的时候

**@**Documented

**@**Documented 注解表明这个注解应该被 javadoc工具记录. 默认情况下,javadoc是不包括注解的. 但如果声明注解时指定了 @Documented,则它会被 javadoc 之类的工具处理, 所以注解类型信息也会被包括在生成的文档中，是一个标记注解，没有成员。

带@Documented生成的javadoc

在这里插入图片描述

不带@Documented生成的javadoc

这两个图的唯一差距就是类的说明是否有这个@API注解。
在这里插入图片描述

总结

@Documented注解只是用来做标识，没什么实际作用，了解就好。

@SuppressWarnings

简介：

java.lang.SuppressWarnings是J2SE5.0中标准的Annotation之一。可以标注在类、字段、方法、参数、构造方法，以及局部变量上。**

作用：**告诉编译器忽略指定的警告，不用在编译完成后出现警告信息。

一. 使用:

@SuppressWarnings(“”)
@SuppressWarnings({})
@SuppressWarnings(value={})

根据sun的官方文档描述：
value -将由编译器在注释的元素中取消显示的警告集。允许使用重复的名称。忽略第二个和后面出现的名称。出现未被识别的警告名 不是错误：编译器必须忽略无法识别的所有警告名。但如果某个注释包含未被识别的警告名，那么编译器可以随意发出一个警告。

各编译器供应商应该将它们所支持的警告名连同注释类型一起记录。鼓励各供应商之间相互合作，确保在多个编译器中使用相同的名称。

示例：

· @SuppressWarnings(“unchecked”)

告诉编译器忽略 unchecked 警告信息，如使用List，ArrayList等未进行参数化产生的警告信息。

· @SuppressWarnings(“serial”)

如果编译器出现这样的警告信息：The serializable class WmailCalendar does not declare a static final serialVersionUID field of type long
使用这个注释将警告信息去掉。

· @SuppressWarnings(“deprecation”)

如果使用了使用@Deprecated注释的方法，编译器将出现警告信息。
使用这个注释将警告信息去掉。

· @SuppressWarnings(“unchecked”, “deprecation”)

告诉编译器同时忽略unchecked和deprecation的警告信息。

· @SuppressWarnings(value={“unchecked”, “deprecation”})

等同于@SuppressWarnings(“unchecked”, “deprecation”)

转自http://blog.sina.com.cn/s/blog_ad8b5870010166vt.html

　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　

编码时我们总会发现如下变量未被使用的警告提示：

img

上述代码编译通过且可以运行，但每行前面的“感叹号”就严重阻碍了我们判断该行是否设置的断点了。这时我们可以在方法前添加 @SuppressWarnings(“unused”) 去除这些“感叹号”。

二、 @SuppressWarings注解　　

作用：用于抑制编译器产生警告信息。

示例1——抑制单类型的警告：

@SuppressWarnings("unchecked")
public void addItems(String item){
  @SuppressWarnings("rawtypes")
   List items = new ArrayList();
   items.add(item);
}

示例2——抑制多类型的警告：

@SuppressWarnings(value={"unchecked", "rawtypes"})
public void addItems(String item){
   List items = new ArrayList();
   items.add(item);
}

示例3——抑制所有类型的警告：

@SuppressWarnings("all")
public void addItems(String item){
   List items = new ArrayList();
   items.add(item);
}

三、注解目标　

通过 @SuppressWarnings 的源码可知，其注解目标为类、字段、函数、函数入参、构造函数和函数的局部变量。

而家建议注解应声明在最接近警告发生的位置。

四、抑制警告的关键字　　

关键字 用途
all to suppress all warnings
boxing to suppress warnings relative to boxing/unboxing operations
cast to suppress warnings relative to cast operations
dep-ann to suppress warnings relative to deprecated annotation
deprecation to suppress warnings relative to deprecation
fallthrough to suppress warnings relative to missing breaks in switch statements
finally to suppress warnings relative to finally block that don’t return
hiding to suppress warnings relative to locals that hide variable
incomplete-switch to suppress warnings relative to missing entries in a switch statement (enum case)
nls to suppress warnings relative to non-nls string literals
null to suppress warnings relative to null analysis
rawtypes to suppress warnings relative to un-specific types when using generics on class params
restriction to suppress warnings relative to usage of discouraged or forbidden references
serial to suppress warnings relative to missing serialVersionUID field for a serializable class
static-access o suppress warnings relative to incorrect static access
synthetic-access to suppress warnings relative to unoptimized access from inner classes
unchecked to suppress warnings relative to unchecked operations
unqualified-field-access to suppress warnings relative to field access unqualified
unused to suppress warnings relative to unused code

五、Java Lint选项

1. lint的含义

　　用于在编译程序的过程中，进行更细节的额外检查。

2. \javac** 的标准选项和非标准选项**

标准选项：是指当前版本和未来版本中都支持的选项，如 -cp 和 -d 等。

非标准选项：是指当前版本支持，但未来不一定支持的选项。通过 javac -X 查看当前版本支持的非标准选项。

img

3. 查看警告信息

默认情况下执行 javac 仅仅显示警告的扼要信息，也不过阻止编译过程。若想查看警告的详细信息，则需要执行 javac -Xlint:keyword 来编译源码了。

从 Java 7 开始，额外添加了 3 个注解:

  • @SafeVarargs - Java 7 开始支持，忽略任何使用参数为泛型变量的方法或构造函数调用产生的警告。
  • @FunctionalInterface - Java 8 开始支持，标识一个匿名函数或函数式接口。
  • @Repeatable - Java 8 开始支持，标识某注解可以在同一个声明上使用多次。

1、Annotation 架构

img

从中，我们可以看出：

(01) 1 个 Annotation 和 1 个 RetentionPolicy 关联。

可以理解为：每1个Annotation对象，都会有唯一的RetentionPolicy属性。

(02) 1 个 Annotation 和 1~n 个 ElementType 关联。

可以理解为：对于每 1 个 Annotation 对象，可以有若干个 ElementType 属性。

(03) Annotation 有许多实现类，包括：Deprecated, Documented, Inherited, Override 等等。

Annotation 的每一个实现类，都 “和 1 个 RetentionPolicy 关联” 并且 “ 和 1~n 个 ElementType 关联”。

下面，我先介绍框架图的左半边(如下图)，即 Annotation, RetentionPolicy, ElementType；然后在就 Annotation 的实现类进行举例说明。

img

2、Annotation 组成部分

java Annotation 的组成中，有 3 个非常重要的主干类。它们分别是：

Annotation.java

package java.lang.annotation;
public interface Annotation {

boolean equals(Object obj);

int hashCode();

String toString();

Class<? **extends** Annotation> annotationType();
}

说明：

(01) Annotation 就是个接口。

“每 1 个 Annotation” 都与 “1 个 RetentionPolicy” 关联，并且与 “1～n 个 ElementType” 关联。可以通俗的理解为：每 1 个 Annotation 对象，都会有唯一的 RetentionPolicy 属性；至于 ElementType 属性，则有 1~n 个。

(02) ElementType 是 Enum 枚举类型，它用来指定 Annotation 的类型。

“每 1 个 Annotation” 都与 “1～n 个 ElementType” 关联。当 Annotation 与某个 ElementType 关联时，就意味着：Annotation有了某种用途。例如，若一个 Annotation 对象是 METHOD 类型，则该 Annotation 只能用来修饰方法。

(03) RetentionPolicy 是 Enum 枚举类型，它用来指定 Annotation 的策略。通俗点说，就是不同 RetentionPolicy 类型的 Annotation 的作用域不同。

“每 1 个 Annotation” 都与 “1 个 RetentionPolicy” 关联。

  • a) 若 Annotation 的类型为 SOURCE，则意味着：Annotation 仅存在于编译器处理期间，编译器处理完之后，该 Annotation 就没用了。 例如，” @Override” 标志就是一个 Annotation。当它修饰一个方法的时候，就意味着该方法覆盖父类的方法；并且在编译期间会进行语法检查！编译器处理完后，”@Override” 就没有任何作用了。
  • b) 若 Annotation 的类型为 CLASS，则意味着：编译器将 Annotation 存储于类对应的 .class 文件中，它是 Annotation 的默认行为。
  • c) 若 Annotation 的类型为 RUNTIME，则意味着：编译器将 Annotation 存储于 class 文件中，并且可由JVM读入。

这时，只需要记住”每 1 个 Annotation” 都与 “1 个 RetentionPolicy” 关联，并且与 “1～n 个 ElementType” 关联。学完后面的内容之后，再回头看这些内容，会更容易理解。

3、java 自带的 Annotation

理解了上面的 3 个类的作用之后，我们接下来可以讲解 Annotation 实现类的语法定义了。

1）Annotation 通用定义

@Documented
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotation1 {
}

说明：

上面的作用是定义一个 Annotation，它的名字是 MyAnnotation1。定义了 MyAnnotation1 之后，我们可以在代码中通过 “@MyAnnotation1” 来使用它。 其它的，@Documented, @Target, @Retention, @interface 都是来修饰 MyAnnotation1 的。下面分别说说它们的含义：

(01) @interface

使用 @interface 定义注解时，意味着它实现了 java.lang.annotation.Annotation 接口，即该注解就是一个Annotation。

定义 Annotation 时，@interface 是必须的。

注意：它和我们通常的 implemented 实现接口的方法不同。Annotation 接口的实现细节都由编译器完成。通过 @interface 定义注解后，该注解不能继承其他的注解或接口。

(02) @Documented

类和方法的 Annotation 在缺省情况下是不出现在 javadoc 中的。如果使用 @Documented 修饰该 Annotation，则表示它可以出现在 javadoc 中。

定义 Annotation 时，@Documented 可有可无；若没有定义，则 Annotation 不会出现在 javadoc 中。

(03) @Target(ElementType.TYPE)

前面我们说过，ElementType 是 Annotation 的类型属性。而 @Target 的作用，就是来指定 Annotation 的类型属性。

@Target(ElementType.TYPE) 的意思就是指定该 Annotation 的类型是 ElementType.TYPE。这就意味着，MyAnnotation1 是来修饰”类、接口（包括注释类型）或枚举声明”的注解。

定义 Annotation 时，@Target 可有可无。若有 @Target，则该 Annotation 只能用于它所指定的地方；若没有 @Target，则该 Annotation 可以用于任何地方。

(04) @Retention(RetentionPolicy.RUNTIME)

前面我们说过，RetentionPolicy 是 Annotation 的策略属性，而 @Retention 的作用，就是指定 Annotation 的策略属性。

@Retention(RetentionPolicy.RUNTIME) 的意思就是指定该 Annotation 的策略是 RetentionPolicy.RUNTIME。这就意味着，编译器会将该 Annotation 信息保留在 .class 文件中，并且能被虚拟机读取。

定义 Annotation 时，@Retention 可有可无。若没有 @Retention，则默认是 RetentionPolicy.CLASS。

2）java自带的Annotation

通过上面的示例，我们能理解：@interface 用来声明 Annotation，@Documented 用来表示该 Annotation 是否会出现在 javadoc 中， @Target 用来指定 Annotation 的类型，@Retention 用来指定 Annotation 的策略。

理解这一点之后，我们就很容易理解 java 中自带的 Annotation 的实现类，即 Annotation 架构图的右半边。如下图：

img

java 常用的 Annotation：

@Deprecated  -- @Deprecated 所标注内容，不再被建议使用。
@Override    -- @Override 只能标注方法，表示该方法覆盖父类中的方法。
@Documented  -- @Documented 所标注内容，可以出现在javadoc中。
@Inherited   -- @Inherited只能被用来标注“Annotation类型”，它所标注的Annotation具有继承性。
@Retention   -- @Retention只能被用来标注“Annotation类型”，而且它被用来指定Annotation的RetentionPolicy属性。
@Target      -- @Target只能被用来标注“Annotation类型”，而且它被用来指定Annotation的ElementType属性。
@SuppressWarnings -- @SuppressWarnings 所标注内容产生的警告，编译器会对这些警告保持静默。

由于 “@Deprecated 和 @Override” 类似，”@Documented, @Inherited, @Retention, @Target” 类似；下面，我们只对 @Deprecated, @Inherited, @SuppressWarnings 这 3 个 Annotation 进行说明。

2.1) @Deprecated

@Deprecated 的定义如下：

@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface Deprecated {
}

说明：

  • (01) @interface – 它的用来修饰 Deprecated，意味着 Deprecated 实现了 java.lang.annotation.Annotation 接口；即 Deprecated 就是一个注解。 (02) @Documented – 它的作用是说明该注解能出现在 javadoc 中。
  • (03) @Retention(RetentionPolicy.RUNTIME) – 它的作用是指定 Deprecated 的策略是 RetentionPolicy.RUNTIME。这就意味着，编译器会将Deprecated 的信息保留在 .class 文件中，并且能被虚拟机读取。
  • (04) @Deprecated 所标注内容，不再被建议使用。

例如，若某个方法被 @Deprecated 标注，则该方法不再被建议使用。如果有开发人员试图使用或重写被 @Deprecated 标示的方法，编译器会给相应的提示信息。

4、Annotation 的作用

Annotation 是一个辅助类，它在 Junit、Struts、Spring 等工具框架中被广泛使用。

我们在编程中经常会使用到的 Annotation 作用有：

1）编译检查

Annotation 具有”让编译器进行编译检查的作用”。

例如，@SuppressWarnings, @Deprecated 和 @Override 都具有编译检查作用。

(01) 关于 @SuppressWarnings 和 @Deprecated，已经在”第3部分”中详细介绍过了。这里就不再举例说明了。

(02) 若某个方法被 @Override 的标注，则意味着该方法会覆盖父类中的同名方法。如果有方法被 @Override 标示，但父类中却没有”被 @Override 标注”的同名方法，则编译器会报错。

2) 在反射中使用 Annotation

在反射的 Class, Method, Field 等函数中，有许多于 Annotation 相关的接口。

这也意味着，我们可以在反射中解析并使用 Annotation。

AnnotationTest.java

import java.lang.annotation.Annotation;
import java.lang.annotation.Target;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Inherited;
import java.lang.reflect.Method;

/\
* Annotation在反射函数中的使用示例
*/**
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
String[] value() default “unknown”;
}

/\
* Person类。它会使用MyAnnotation注解。
*/**
class Person {

/\
* empty()方法同时被 “@Deprecated” 和 “@MyAnnotation(value={“a”,”b”})”所标注
* (01) @Deprecated，意味着empty()方法，不再被建议使用
* (02) @MyAnnotation, 意味着empty() 方法对应的MyAnnotation的value值是默认值”unknown”
*/**
@MyAnnotation
@Deprecated
public void empty(){
System.out.println(“\nempty”);
}

/\
* sombody() 被 @MyAnnotation(value={“girl”,”boy”}) 所标注，
* @MyAnnotation(value={“girl”,”boy”}), 意味着MyAnnotation的value值是{“girl”,”boy”}
*/**
@MyAnnotation(value={“girl”,”boy”})
public void somebody(String name, int age){
System.out.println(“\nsomebody: “+name+”, “+age);
}
}

public class AnnotationTest {

public static void main(String[] args) throws Exception {

*// 新建Person*
Person person = **new** Person();
*// 获取Person的Class实例*
Class<Person> c = Person.**class**;
*// 获取 somebody() 方法的Method实例*
Method mSomebody = c.getMethod("somebody", **new** **Class**[]{String.**class**, **int**.**class**});
*// 执行该方法*
mSomebody.invoke(person, **new** Object[]{"lily", 18});
iteratorAnnotations(mSomebody);

​ // 获取 somebody() 方法的Method实例
​ Method mEmpty = c.getMethod(“empty”, new Class[]{});
​ // 执行该方法
​ mEmpty.invoke(person, new Object[]{});
​ iteratorAnnotations(mEmpty);
}

public static void iteratorAnnotations(Method method) {

​ // 判断 somebody() 方法是否包含MyAnnotation注解
​ if(method.isAnnotationPresent(MyAnnotation.class)){
​ // 获取该方法的MyAnnotation注解实例
​ MyAnnotation myAnnotation = method.getAnnotation(MyAnnotation.class);
​ // 获取 myAnnotation的值，并打印出来
​ String[] values = myAnnotation.value();
​ for (String str:values)
​ System.out.printf(str+”, “);
​ System.out.println();
​ }
​
​ // 获取方法上的所有注解，并打印出来
​ Annotation[] annotations = method.getAnnotations();
​ for(Annotation annotation : annotations){
​ System.out.println(annotation);
​ }
}
}

运行结果：

somebody: lily, 18
girl, boy, 
@com.skywang.annotation.MyAnnotation(value=[girl, boy])

empty
unknown, 
@com.skywang.annotation.MyAnnotation(value=[unknown])
@java.lang.Deprecated()

3) 根据 Annotation 生成帮助文档

通过给 Annotation 注解加上 @Documented 标签，能使该 Annotation 标签出现在 javadoc 中。

4) 能够帮忙查看查看代码

通过 @Override, @Deprecated 等，我们能很方便的了解程序的大致结构。

另外，我们也可以通过自定义 Annotation 来实现一些功能。