Java Annotation

　　Java 1.5中开始引入的Annotation，类似于注释的一种技术，参考了一些网上的译法，姑且译成注解吧。

　　我们在开发中，用得最多的Annotation莫过于@Override了。大家天天用，可能很多同学却没有关注过其背后的细节，我们看一下它的定义：

Java代码
  1. @Target(ElementType.METHOD)  
  2. @Retention(RetentionPolicy.SOURCE)  
  3. public @interface Override {  
  4. }  

　　在Android源码中，这个注解定义在libcore/luni/src/main/java/java/lang/Override.java中。

　　这是一个标称注解，只在源代码级有效，主要被编译器用来判断是否真的继承了父类中的方法。

　　常用的Annotation还有著名的@Deprecated，过时的建议不用的方法。

　　它的定义如下：

Java代码
  1. @Documented  
  2. @Retention(RetentionPolicy.RUNTIME)  
  3. public @interface Deprecated {  
  4. }  

　　另外还有通知编译器不要做警告的@SuppressWarnings

Java代码
  1. @Target( { ElementType.TYPE, ElementType.FIELD, ElementType.METHOD,  
  2.         ElementType.PARAMETER, ElementType.CONSTRUCTOR,  
  3.         ElementType.LOCAL_VARIABLE })  
  4. @Retention(RetentionPolicy.SOURCE)  
  5. public @interface SuppressWarnings {  
  6.   
  7.     /** 
  8.      * The list of warnings a compiler should not issue. 
  9.      */  
  10.     public String[] value();  
  11. }  

　　元注解

　　除了上面几个常用的注解定义于最基本的java.lang包中，用于实现这几个Annotation的Annotation都实现在java.lang.annotation包中。它们是被用于实现其它注解所用的。

　　元素类型 - ElementType

　　就是这个注解可以用于什么语法单元，比如@Override只能用于方法，方法的类型就是ElementType.METHOD.

　　这是一个枚举，包括下面的类型：

　　TYPE: 类，接口，枚举

　　FIELD: 域变量

　　METHOD:方法

　　PARAMETER:函数参数

　　CONSTRUCTOR:构造函数

　　LOCAL_VARIABLE:局部变量

　　ANNOTATION_TYPE:注解类型

　　PACKAGE:包

　　@Target

　　定义了元素类型，就可以通过这些类型来指定注解适用的类型了。

Java代码
  1. @Documented  
  2. @Retention(RetentionPolicy.RUNTIME)  
  3. @Target(ElementType.ANNOTATION_TYPE)  
  4. public @interface Target {  
  5.     ElementType[] value();  
  6. }  

　　@Target注解就是一个ElementType的数组，就像上面我们看到的用法：

Java代码
  1. @Target( { ElementType.TYPE, ElementType.FIELD, ElementType.METHOD,  
  2.         ElementType.PARAMETER, ElementType.CONSTRUCTOR,  
  3.         ElementType.LOCAL_VARIABLE })  

　　@Documented

Java代码
  1. @Documented  
  2. @Retention(RetentionPolicy.RUNTIME)  
  3. @Target(ElementType.ANNOTATION_TYPE)  
  4. public @interface Documented {  
  5. }  

　　用于描述一个注解是可以生成JavaDoc的，也暗示了这个注解是一个公开的API。

　　@Retention

　　这是4个元注解中最重要的一个，用于定义这个注解的生命周期。

　　取值是另一个枚举：

　　• RetentionPolicy.SOURCE:注解只存在于源代码中，编译器生成class代码时就忽略了

　　• RetentionPolicy.CLASS:会编译进class文件，但是VM执行时调不到

　　• RetentionPolicy.RUNTIME:在运行时也可以访问到

　　RetentionPolicy的定义如下：

Java代码
  1. public enum RetentionPolicy {  
  2.     /** 
  3.      * Annotation is only available in the source code. 
  4.      */  
  5.     SOURCE,  
  6.     /** 
  7.      * Annotation is available in the source code and in the class file, but not 
  8.      * at runtime. This is the default policy. 
  9.      */  
  10.     CLASS,  
  11.     /** 
  12.      * Annotation is available in the source code, the class file and is 
  13.      * available at runtime. 
  14.      */  
  15.     RUNTIME  
  16. }  

　　有了这些基础，再看@Retention的实现，就可以完全看得懂了：

Java代码
  1. @Documented  
  2. @Retention(RetentionPolicy.RUNTIME)  
  3. @Target(ElementType.ANNOTATION_TYPE)  
  4. public @interface Retention {  
  5.     RetentionPolicy value();  
  6. }  

　　@Retention本身是个运行时可用的注解，公开的API，只对注解本身有效。

　　它只定义了一个RetentionPolicy枚举的值。

　　通过反射处理注解

　　所有的@Target可用的对象都支持用getAnnotations()方法去读取注解。

　　例如，读取一个类的注解：

Java代码
  1. Class clazz = ThreadSafeCounter.class;  
  2. Annotation[] as = clazz.getAnnotations();  

　　我们通过一个例子来说明：

　　首先先定义一个注解，这个注解用于说明这类或者方法是线程安全的，有一个value用于保存锁对象的名字。

Java代码
  1. import java.lang.annotation.*;  
  2.   
  3. @Documented  
  4. @Retention(RetentionPolicy.RUNTIME)  
  5. @Target({ElementType.TYPE,ElementType.METHOD})  
  6. public @interface ThreadSafe {  
  7.     String value();  
  8. }  

　　下面定义一个使用该注解的类, 类和其中的一个方法都使用这个注解。其实有点废话，类都线程安全了，方法还能不安全么，呵呵

Java代码
  1. import java.lang.annotation.Annotation;  
  2. import java.lang.reflect.Method;  
  3.   
  4. @ThreadSafe("ThreadSafeCounter")  
  5. public class ThreadSafeCounter {  
  6.     private int mCounter;  
  7.   
  8.     public ThreadSafeCounter(int counter) {  
  9.         mCounter = counter;  
  10.     }  
  11.   
  12.     @ThreadSafe("this")  
  13.     public int incAndGet() {  
  14.         synchronized (this) {  
  15.             return mCounter++;  
  16.         }  
  17.     }  

　　下面定义一个main方法去通过反射读注解，先读类的注解：

Java代码
  1. public static void main(String[] args){  
  2.     Class clazz = ThreadSafeCounter.class;  
  3.     Annotation[] as = clazz.getAnnotations();  
  4.   
  5.     for(Annotation a:as){  
  6.         ThreadSafe t= (ThreadSafe)a;  
  7.         System.out.println("Annotation type="+clazz.getName());  
  8.         System.out.println("lock name is:"+t.value());  
  9.     }  

　　然后再读取

Java代码
  1.     Method[] methods = clazz.getMethods();  
  2.     for(Method method: methods){  
  3.         boolean hasAnno = method.isAnnotationPresent(ThreadSafe.class);  
  4.         if(hasAnno){  
  5.             ThreadSafe anno = method.getAnnotation(ThreadSafe.class);  
  6.             System.out.println("method name="+method.getName()+",lock object="+anno.value());  
  7.         }  
  8.     }  
  9. }
  10. }  

　　本章内容参考文献：《Java程序设计完全手册》，王作启，伍正云著，北京：清华大学出版社，2014

　　Android中的Annotation

　　Android标准的Annotation

　　@Nullable

　　定义：

Java代码
  1. @Retention(SOURCE)  
  2. @Target({METHOD, PARAMETER, FIELD})  
  3. public @interface Nullable {  
  4. }  

　　源码级的，可以用于方法、参数和域，表示一个方法或域的值可以合法地为空，或者是函数的返回值可以合法为空。代码中已经针对为空的情况做了相应的处理。

　　这是个标称注解。

　　@NonNull

Java代码
  1. @Retention(SOURCE)  
  2. @Target({METHOD, PARAMETER, FIELD})  
  3. public @interface NonNull {  
  4. }  

　　与@Nullable相反，@NonNull要求一定不能为空。

　　@UiThread

　　定义：

Java代码
  1. @Retention(SOURCE)  
  2. @Target({METHOD,CONSTRUCTOR,TYPE})  
  3. public @interface UiThread {  
  4. }  

　　表示标有该注解的方法或构造函数应该只在UI线程调用。

　　如果注解元素是一个类，说明该类的所有方法都应该在UI线程中调用。

　　@MainThread

Java代码
  1. @Retention(SOURCE)  
  2. @Target({METHOD,CONSTRUCTOR,TYPE})  
  3. public @interface MainThread {  
  4. }  

　　这个是要求运行在主线程的

　　@WorkerThread

Java代码
  1. @Retention(SOURCE)  
  2. @Target({METHOD,CONSTRUCTOR,TYPE})  
  3. public @interface WorkerThread {  
  4. }  

　　要求运行在工作线程

　　@IntRef

　　用于定义整数值。

Java代码
  1. @Retention(CLASS)  
  2. @Target({ANNOTATION_TYPE})  
  3. public @interface IntDef {  
  4.     /** Defines the allowed constants for this element */  
  5.     long[] value() default {};  
  6.   
  7.     /** Defines whether the constants can be used as a flag, or just as an enum (the default) */  
  8.     boolean flag() default false;  
  9. }  

　　我们看一个使用@IntRef例子：

Java代码
  1. @IntDef({HORIZONTAL, VERTICAL})  
  2. @Retention(RetentionPolicy.SOURCE)  
  3. public @interface OrientationMode {}  
  4.   
  5. public static final int HORIZONTAL = 0;  
  6. public static final int VERTICAL = 1;  

　　在上面定义的@OrientationMode注释中，可以支持的值是HORIZONTAL, VERTICAL.

　　然后我们再看一个使用flag的例子：

Java代码
  1. @IntDef(flag = true,  
  2.         value = {  
  3.             SHOW_DIVIDER_NONE,  
  4.             SHOW_DIVIDER_BEGINNING,  
  5.             SHOW_DIVIDER_MIDDLE,  
  6.             SHOW_DIVIDER_END  
  7.         })  
  8. @Retention(RetentionPolicy.SOURCE)  
  9. public @interface DividerMode {}  

　　View相关的

　　@RemoteView

　　支持RemoteView机制，这是一个运行时的注释.

　　定义路径：/frameworks/base/core/java/android/widget/RemoteViews.java

Java代码
  1. /** 
  2.  * This annotation indicates that a subclass of View is alllowed to be used 
  3.  * with the {@link RemoteViews} mechanism. 
  4.  */  
  5. @Target({ ElementType.TYPE })  
  6. @Retention(RetentionPolicy.RUNTIME)  
  7. public @interface RemoteView {  
  8. } 
本文发布：Android开发网
本文地址：http://www.jizhuomi.com/android/course/661.html
2017年3月15日
发布:鸡啄米 分类:Android开发教程 浏览: 评论:0