[转载]Java注解--基础知识

[转载 ]

一、什么是java 注解

         注解，顾名思义，注解 , 就是对某一事物进行添加注释说明，会存放一些信息，这些信息可能对以后某个时段来说是很有用处的。

         Java 注解又叫 java 标注， java 提供了一套机制，使得我们可以对方法、类、参数、包、域以及变量等添加标准 ( 即附上某些信息 ) 。且在以后某个时段通过反射将标注的信息提取出来以供使用。

二、自定义Java 注解

1   为什么要自定义注解

         Java 从 1.5 版本以后默认内置三个标注：

Ø  @Override: 只能用在方法之上的，用来告诉别人这一个方法是改写父类的。

Ø  @Deprecated: 建议别人不要使用旧的 API 的时候用的 , 编译的时候会用产生警告信息 , 可以设定在程序里的所有的元素上 .

Ø  @SuppressWarnings: 这一个类型可以来暂时把一些警告信息消息关闭 .

但是，仅仅这三个标注是不能满足我们开发时一些需求的。所以 java 允许我们自定义注解来使用。

2   如何自定义注解

自定义步骤大致分为两步：

1，               通过 @interface 关键字 ( 注意，不是 interface ，是 @interace) 声明注解名称，以及注解的成员属性或者叫做注解的参数。

2，               使用 java 内置的四个元注解对这个自定义标注的功能和范围进行一些限制

问题来了，什么是元注解 ？

3   什么是元注解

元注解 ， 就是定义注解的注解，也就是说这些元注解是的作用就是专门用来约束其它注解的注解。请区别上面那三个注解，他们也是通过元注解定义而来的。

元注解有哪些呢，主要有四个 @Target,@Retention,@Documented,@Inherited ？

1.   *  元注解有： @Target,@Retention,@Documented,@Inherited  

2.   *   

3.   *     @Target  表示该注解用于什么地方，可能的  ElemenetType  参数包括：  

4.   *         ElemenetType.CONSTRUCTOR  构造器声明  

5.   *         ElemenetType.FIELD  域声明（包括  enum  实例）  

6.   *         ElemenetType.LOCAL_VARIABLE  局部变量声明  

7.   *         ElemenetType.METHOD  方法声明  

8.   *         ElemenetType.PACKAGE  包声明  

9.   *         ElemenetType.PARAMETER  参数声明  

10.  *         ElemenetType.TYPE  类，接口（包括注解类型）或 enum 声明  

11.  *           

12.  *     @Retention  表示在什么级别保存该注解信息。可选的  RetentionPolicy  参数包括：  

13.  *         RetentionPolicy.SOURCE  注解将被编译器丢弃  

14.  *         RetentionPolicy.CLASS  注解在 class 文件中可用，但会被 VM 丢弃  

15.  *         RetentionPolicy.RUNTIME VM 将在运行期也保留注释，因此可以通过反射机制读取注解的信息。  

16.  *           

17.  *     @Documented  将此注解包含在  javadoc  中  

18.  *       

19.  *     @Inherited  允许子类继承父类中的注解  

 

4 自定义及使用注解示例

         自定义一个类级别的标注 Description 

package lighter.javaeye.com;
   import java.lang.annotation.Documented;
   import java.lang.annotation.ElementType;
   import java.lang.annotation.Retention;
   import java.lang.annotation.RetentionPolicy;
   import java.lang.annotation.Target;
 
   @Target(ElementType.TYPE)// 这个标注应用于类
   @Retention(RetentionPolicy.RUNTIME)// 标注会一直保留到运行时
   @Documented// 将此注解包含在 javadoc 中
   public @interface Description {
       String value();
   } 

 

 

         再定义个方法级别的注解 Name

package lighter.javaeye.com;
   import java.lang.annotation.Documented;
   import java.lang.annotation.ElementType;
   import java.lang.annotation.Retention;
   import java.lang.annotation.RetentionPolicy;
   import java.lang.annotation.Target;
 
    // 注意这里的 @Target 与 @Description 里的不同 , 参数成员也不同
   @Target(ElementType.METHOD)
   @Retention(RetentionPolicy.RUNTIME)
   @Documented
   public @interface Name {
       String originate();
       String community();
   } 

 

 

         然后使用以上两个注解

package lighter.javaeye.com;
 
@Description(value="javaeye, 做最棒的软件开发交流社区 ")
public class JavaEyer {
         @Name(originate=" 创始人 :robbin",community="javaEye")
         public String getName()
         {
                   return null;
         }
        
         @Name(originate=" 创始人 : 江南白衣 ",community="springside")
         public String getName2()
         {
                   return " 借用两位的 id 一用 , 写这一个例子 , 请见谅 !";
         }
} 

 

说明：其中标注“ @Description(value="javaeye, 做最棒的软件开发交流社区 ") ”，可以写成“ @Description("javaeye, 做最棒的软件开发交流社区 ") ”，结果也是一样的。因为 Description 标注定义的时候其参数 ( 或者说属性 ) 为 value 。而 value 比较特殊，它在被指定参数的时候可以不用显示的写出来。当然如果定义的时候参数名不是 value 而是其它的比如 des ，那么使用注解的时候，必须显示写出参数名，然后再赋值： @Description(Des=”xxx”)

 

提取出注解的信息

package lighter.javaeye.com;
 
 import java.lang.reflect.Method;
 import java.util.HashSet;
 import java.util.Set;
 
 public class TestAnnotation {
         /**
          * author lighter
          * 说明 : 具体关天 Annotation 的 API 的用法请参见 javaDoc 文档
          */
       public static void main(String[] args) throws Exception {
       String CLASS_NAME = "lighter.javaeye.com.JavaEyer";
       Class test = Class.forName(CLASS_NAME);
       Method[] method = test.getMethods();
       boolean flag = test.isAnnotationPresent(Description.class);
        if(flag)
        {
                 Description des = (Description)test.getAnnotation(Description.class);
                 System.out.println(" 描述 :"+des.value());
                 System.out.println("-----------------");
        }
       
        // 把 JavaEyer 这一类有利用到 @Name 的全部方法保存到 Set 中去
        Set<Method> set = new HashSet<Method>();
        for(int i=0;i<method.length;i++)
        {
                 boolean otherFlag = method[i].isAnnotationPresent(Name.class);
                 if(otherFlag) set.add(method[i]);
        }
        for(Method m: set)
        {
                 Name name = m.getAnnotation(Name.class);
                 System.out.println(name.originate());
                 System.out.println(" 创建的社区 :"+name.community());
        }
     }
} 

 

注意事项：

所有的 Annotation 会自动继承 java.lang.annotation 这一个接口 , 所以不能再去继承别的类或是接口 .

   最重要的一点 ,Annotation 类型里面的参数该怎么设定 :

   第一 , 只能用 public 或默认 (default) 这两个访问权修饰 . 例如 ,String value(); 这里把方法设为 defaul 默认类型 .

   第二 , 参数成员只能用基本类型 byte,short,char,int,long,float,double,boolean 八种基本数据类型和 String,Enum,Class,annotations 等数据类型 , 以及这一些类型的数组 . 例如 ,String value(); 这里的参数成员就为 String.

参考资料： http://www.javaeye.com/topic/36659

                     http://www.javaeye.com/topic/400085