[Google Guava笔记]（一）annotations

       最近在看Google Guava库的源码，为什么会看这个库的源码呢？不做解释。

        这个项目包含了一些Google的核心Java1.5+类库，这些类库已经被应用在Google许多基于Java的项目中。包括：

• com.google.common.annotations
• com.google.common.base
• com.google.common.collect
• com.google.common.io
• com.google.common.net
• com.google.common.primitives
• com.google.common.util.concurren

        我大致是按照包的顺序来看的，因为时间的关系有时也会先看小一点的包，包内的顺序会根据类之间的调用做相应调整。因为网上Guava的中文资料实在太少了，所以看源码的时候根据注释和个人的理解稍微记了下笔记，给大家提供一点参考。目前水平有限，很多地方理解可能不够深入，遇到不足或错误的地方，请各位大牛多多指正！

 

        这个类库比较大，所以将会分几篇日志来写，目前的计划是这样的：

1. com.google.common.annotations
2. com.google.common.base（预算是分为两篇）
3. com.google.common.net
4. com.google.common.primitives
5. com.google.common.collect（预算是分为两篇，不够就再加，这个包实在是太大了...以前是一个独立的项目Google Collections，后来加到Guava中了，只用了一个包，坑爹啊）
6. com.google.common.io（预算是分为两篇）
7. com.google.common.util.concurrent（预算是分为两篇）

        现在开始正文，annotations：提供了常用的注释类型。

        以下是java中annotations的相关知识，从网上找到的，引自：http://www.iteye.com/topic/171412，感谢lingzantia。

      注释类是实现 java.lang.annotation.Annotation接口的类，用于向程序分析工具或虚拟机提供注释信息，它和一般的类在定义和使用方式上有所不同。

        注释类的一般形式是：

public @interface MyAnnotation {

String value() default "hello world";

}

         它等价于下面的类：

public class MyAnnotation implements java.lang.annotation.Annotation {

private String value = "hello world";

public void setValue(String value) {

this.value = value;

}

public String getValue() {

return value;

}

}

         注释类的使用方法如下：

@MyAnnotation(value="hello")

 

Method method = AnnotationTest.class.getMethod("doSomething", null);// 获取被注释方法

MyAnnotation annotation = method.getAnnotation(MyAnnotation .class);// 获取注释对象

String value = annotation.value();

         @interface 表示该类是注释类，定义注释类时不能再继承或实现其它类。

         java.lang.annocation 包中常用的 class 有：接口 Annotation 、枚举类型 ElementType 和 RetentionPolicy 、注释类 Documented 、 Inherited 、 Retention 和 Target 。

public enum RetentionPolicy {

SOURCE, //编译器处理完 Annotation后不存储在 class中

CLASS, //编译器把 Annotation存储在 class中，这是默认值

RUNTIME //编译器把 Annotation存储在 class中，可以由虚拟机读取，反射需要

}

 

public enum ElementType {

TYPE, //指定适用点为 class, interface, enum

FIELD, //指定适用点为 field

METHOD, //指定适用点为 method

PARAMETER, //指定适用点为 method的 parameter

CONSTRUCTOR, //指定适用点为 constructor

LOCAL_VARIABLE, //指定使用点为局部变量

ANNOTATION_TYPE, //指定适用点为 annotation类型

PACKAGE //指定适用点为 package

}

 

         java.lang.annotation.Documented用于指定该 Annotation是否可以写入 javadoc中 .
         java.lang.annotation.Inherited用于指定该 Annotation用于父类时是否能够被子类继承 .

         示例如下：

import java.lang.annotation.ElementType;

import java.lang.annotation.Retention;

import java.lang.annotation.RetentionPolicy;

import java.lang.annotation.Target;

 

@Documented //这个 Annotation可以被写入 javadoc

@Inherited //这个 Annotation可以被继承

//表示这个 Annotation只能用于注释构造子和方法

@Target({ElementType.CONSTRUCTOR,ElementType.METHOD}) 

@Retention(RetentionPolicy.CLASS) //表示这个 Annotation存入 class但 vm不读取  

public @interface MyAnnotation {

String value() default "hahaha";

}

java.lang.reflect.AnnotatedElement接口提供了以下四个方法来访问注释：

public Annotation getAnnotation(Class annotationType);  

public Annotation[] getAnnotations();  

public Annotation[] getDeclaredAnnotations();  

public boolean isAnnotationPresent(Class annotationType);  

         Class、 Constructor、 Field、 Method、 Package等都实现了该接口 ,可以通过这些方法访问 Annotation信息 ,前提是要访问的 Annotation指定 Retention为 RUNTIME.
         Java内置的 annotation有 Override Deprecated SuppressWarnings.
         Override只用于方法 ,它指明注释的方法重写父类的方法 ,如果不是 ,则编译器报错 .
         Deprecated指明该方法不建议使用
         SuppressWarnings告诉编译器 :我知道我的代码没问题 ,你不用吓我了 ,我不怕的 ^_^
         这些都是 Mark Annotation,名称本身就包含了要提供的信息 ,不需要额外提供 .

 

1.1 Beta：这个注释使得被注释的 API受不希望的改变的影响，甚至是删除操作。 如果一个 API有 Beta注释，将不再遵守它所在的类库的约定。

Retention为 class， Target为类型、构造函数、域、方法、类型，标记为 Documented和 GwtCompatible。

是标记注释，不需要给出说明。

1.2 GwtCompatible：这个注释要求被注释的 method返回类型是与 GWT兼容的。用于 type时表示希望该类型的所有方法返回类型是与 GWT兼容的。常用于指示工厂方法创建的实例类型是 GWT可序列化类型。

Retention为 class， Target为类型和方法，标记为 Documented。

是标记注释，不需要给出说明。

1.3 GwtIncompatible：这个注释表示被注释的 type、 method或 field不能用于 GWT，即便它们所在的类型被注释为 GwtCompatible或者可以在 GWT中被访问。在 GWT中使用被 GwtIncompatible注释的 method或 field时会引起编译错误或抛出异常。

Retention为 class， Target为 type、 method和 field，标记为 Documented。

是非标记注释，需要描述被注释对象与 GWT不兼容的原因。一般情况下，简单的引用 GWT不支持的类型或方法就足够了，例如： @GwtIncompatible Class.isInstance。

1.4 VisibleForTesting：这个注释表示被注释的 type或 member可以被测试。标记为 GwtCompatible。是标记注释，不需要给出说明。

 

以上。