java annotation---摘自http://blog.csdn.net/numenZQ/archive/2007/06/17/1654827.aspx-阿里云开发者社区

开发者社区> 开发与运维> 正文
登录阅读全文

java annotation---摘自http://blog.csdn.net/numenZQ/archive/2007/06/17/1654827.aspx

简介:

作者:曾巧(numenzq)

 摘要

Annotation(注释)是J2SE 5.0引入的新功能,它被定义为JSR-175规范。简单地说,它可以用于创建文档,跟踪代码中的依赖性,甚至执行基本编译时检查。本文只会介绍注释的基本概念,以及Java内置注释的使用方法;关于定制注释及其他高级主题将在下一篇文章中讲解。

 正文

编程的一个最新的趋势,尤其是在Java编程方面,就是使用元数据。直到JSR-175 提案的通过,并在J2SE 5.0上实现,你才有了使用注释的机会,在不断的发展和演进中,基于JSR-181的元数据批注标准,能让我们更轻松的开发和部署Web Service了,不需要被大量的配置文件所烦恼,说得有点远了,转回整体,元数据是可以添加到代码中的修饰符,它可以用于包声明、类型声明、构造函数、方法、字段、参数和变量。J2SE包含内置注释,还支持你自己编写的定制注释。

 内容

l         注释基本知识

l         元数据的作用

l         基本内置注释

l         概要

 

注释基础知识

    在J2SE 5.0中,注释是以‘@注释名’在代码中存在的,例如:J2SE 5.0内置的注释:@Override、@Deprecated;有的注释还可以添加一些参数值,例如:@SuppressWarnings(value="unchecked");对于这种只有一个参数,且参数名为value的注释,我们在使用时可以简写为:@SuppressWarnings("unchecked")。

    根据注释参数的个数,我们可以将注释分为:标记注释、单值注释、完整注释三类。它们都不会直接影响到程序的语义,只是作为注释(标识)存在,我们可以通过反射机制编程实现对这些元数据的访问。另外,你可以在编译时选择代码里的注释是否只存在于源代码级,或者它也能在class文件中出现。

 

元数据的作用

如果要对于元数据的作用进行分类,目前还没有明确的定义,不过我们可以根据它所起的作用,大致可分为三类:

l         编写文档:通过代码里标识的元数据生成文档。

l         代码分析:通过代码里标识的元数据对代码进行分析。

l         编译检查:通过代码里标识的元数据让编译器能实现基本的编译检查。

 

基本内置注释

    @Override注释能实现编译时检查,你可以为你的方法添加该注释,以声明该方法是用于覆盖父类中的方法。如果该方法不是覆盖父类的方法,将会在编译时报错。例如我们为某类重写toString()方法却写成了tostring(),并且我们为该方法添加了@Override注释;代码如下:

package com.gelc.annotation.demo.basic;

 

public class OverrideDemo { 

    // @Override

    public String tostring() { 

        return super.toString();

    }

}

在编译时,则会提示以下错误信息:

OverrideTest.java:5: 方法未覆盖其父类的方法

        @Override

         ^

1 错误

    就像示例演示的那样,该注释一大好处就是可以在编译时帮我们捕获部分编译错误,但又有多少编程人员愿意为每个覆盖父类的方法添加该注释呢?这个只有靠编程人员自己进行取舍了。

 

    @Deprecated的作用是对不应该在使用的方法添加注释,当编程人员使用这些方法时,将会在编译时显示提示信息,它与javadoc里的@deprecated标记有相同的功能,准确的说,它还不如javadoc @deprecated,因为它不支持参数,使用@Deprecated的示例代码示例如下:

package com.gelc.annotation.demo.basic;

 public class DeprecatedDemo {

     public static void main(String[] args) {

         // DeprecatedClass.DeprecatedMethod();

    }

}

 

class DeprecatedClass {

     @Deprecated

    public static void DeprecatedMethod() {

        // TODO

    }

}

    编译时,会得到以下提示:

注意:DeprecatedDemo.java 使用或覆盖了已过时的 API。

注意:要了解详细信息,请使用 -Xlint:deprecation 重新编译。

    如果在编译时添加-Xlint:deprecation参数,我们能更清楚的看到该警告的详细信息,如下:

DeprecatedDemo.java:6: 警告:[deprecation] SomeClass 中的 DeprecatedMethod() 已

过时

                SomeClass.DeprecatedMethod();

                         ^

1 警告

    通过上面的示例,你已经掌握到了如何使用@Deprecated,但你理解到@Deprecated与@deprecated的区别了吗?你可以简单的理解为:@Deprecated是为了编译时检查,而@deprecated是为了生成文档的需要,各尽其责。

 

    @SuppressWarnings与前两个注释有所不同,你需要添加一个参数才能正确使用,这些参数值都是已经定义好了的,我们选择性的使用就好了,参数如下:

参数

语义

deprecation

使用了过时的类或方法时的警告

unchecked

执行了未检查的转换时的警告,例如当使用集合时没有用泛型 (Generics) 来指定集合保存的类型

fallthrough

当 Switch 程序块直接通往下一种情况而没有 Break 时的警告

path

在类路径、源文件路径等中有不存在的路径时的警告

serial

当在可序列化的类上缺少 serialVersionUID 定义时的警告

finally

任何 finally 子句不能正常完成时的警告

all

关于以上所有情况的警告

    通过上面的表格,你应该了解到每个参数的用意了,下面我就以一个常用的参数unchecked为例,为你展示如何使用@SuppressWarnings注释,示例代码如下:

package com.gelc.annotation.demo.basic;

 

import java.util.List;

import java.util.ArrayList;

 public class SuppressWarningsDemo {

     public static List cache = new ArrayList();

     // @SuppressWarnings(value = "unchecked")

    public void add(String data) {

         cache.add(data);

    }

}

    当我们不使用@SuppressWarnings注释时,编译器就会有如下提示:

注意:SuppressWarningsDemo.java 使用了未经检查或不安全的操作。

注意:要了解详细信息,请使用 -Xlint:unchecked 重新编译。

相信你对这个提示相当熟悉了,我就不在这里多说了。下面我们还是来试试使用了@SuppressWarnings(value="unchecked")注释会是什么效果,它会屏蔽编译时的警告信息,这也就是它所要达到的目的。另外,由于@SuppressWarnings注释只有一个参数,并且参数名为value,所以我们可以将上面一句注释简写为@SuppressWarnings("unchecked")。

 概要

在J2SE 5.0出现三个多年头后的今天,再回头看看它当时引入的这一新特性,虽然它已不是什么新概念了,还是值得我们再次回味的,下面文章中将介绍编程人员如何定制注释。
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

摘要

在前一篇文章中,已经向你介绍了Annotation的基本概念、作用、Java内置注释等,本文将向你展示在J2SE 5.0或更高版本中Annotation(注释)更强大的一面:自定义注释,开发人员可以根据需求编写特定功能的注释。通过对本文的学习,我们将了解到如何创建注释,使用自定义注释等知识。

 

内容

l         定制注释类型

l         使用定制的注释类型

l         添加变量

l         为变量赋默认值

l         概要

 定制注释类型

    好的,让我们创建一个自己的注释类型(annotation type)吧。它类似于新创建一个接口类文件,但为了区分,我们需要将它声明为@interface,如下例:

public @interface NewAnnotation {

 }

 

使用定制的注释类型

    我们已经成功地创建好一个注释类型NewAnnotation,现在让我们来尝试使用它吧,如果你还记得本文的第一部分,那你应该知道他是一个标记注释,使用也很容易,如下例:

public class AnnotationTest {

     @NewAnnotation

    public static void main(String[] args) {

     }

}

 

添加变量

    J2SE 5.0里,我们了解到内置注释@SuppressWarnings()是可以使用参数的,那么自定义注释能不能定义参数个数和类型呢?答案是当然可以,但参数类型只允许为基本类型、String、Class、枚举类型等,并且参数不能为空。我们来扩展NewAnnotation,为之添加一个String类型的参数,示例代码如下:

public @interface NewAnnotation {

     String value();

}

    使用该注释的代码如下:正如你所看到的,该注释的使用有两种写法,这也是在之前的文章里所提到过的。如果你忘了这是怎么回事,那就再去翻翻吧。

public class AnnotationTest {

     @NewAnnotation("Just a Test.")

    public static void main(String[] args) {

        sayHello();

    }

    @NewAnnotation(value="Hello NUMEN.")

    public static void sayHello() {

        // do something

    }

}

 

为变量赋默认值

    我们对Java自定义注释的了解正在不断的增多,不过我们还需要更过,在该条目里我们将了解到如何为变量设置默认值,我们再对NewAnnotaion进行修改,看看它会变成什么样子,不仅参数多了几个,连类名也变了。但还是很容易理解的,我们先定义一个枚举类型,然后将参数设置为该枚举类型,并赋予默认值。

public @interface Greeting {

    public enum FontColor {RED, GREEN, BLUE};

     String name();

     String content();

     FontColor fontColor() default FontColor.BLUE;

}

    我们还是来看看如何使用吧,这里有两种选择,其实变数也就是在赋予默认值的参数上,我们可以选择使用该默认值,也可以重新设置一个值来替换默认值,如下例:

public class AnnotationTest {

     @NewAnnotation("Just a Test.")

    public static void main(String[] args) {

        sayHello();

        sayHelloWithDefaultFontColor();

        sayHelloWithRedFontColor();

    }

   

    @NewAnnotation("Hello NUMEN.")

    public static void sayHello() {       

    }

    @Greeting(name="NUMEN", content="Hello")

    public static void sayHelloWithDefaultFontColor() {

        // do something

    }

    @Greeting(name="NUMEN", content="Hello", fontColor=Greeting.FontColor.RED )

    public static void sayHelloWithRedFontColor() {

        // do something

    }

}

 概要

    通过对本文的学习,你应该了解和掌握到如何定制注释和使用注释,这样会在一定程度上辅助我们的开发。在下一篇文章中,我们会学习元注释。
-----------------------------------------------------------------------------------------------------------------------------------------------------------------

摘要

在之前的文章中,我们已经了解了Annotation的基本概念,Java的内置Annotation和如何定制自己的Annotation;在这里我们将学习Annotation的另一个特性:元注释,它可以使我们更好的定制我们的注释。

 

内容

l         限定注释使用范围

l         注释保持性策略

l         文档化功能

l         标注继承

l         概要

 

限定注释使用范围

    当我们的自定义注释不断的增多也比较复杂时,就会导致有些开发人员使用错误,主要表现在不该使用该注释的地方使用。为此,Java提供了一个ElementType枚举类型来控制每个注释的使用范围,比如说某些注释只能用于普通方法,而不能用于构造函数等。下面是Java定义的ElementType枚举:

package java.lang.annotation;

 

public enum ElementType {

 TYPE,         // Class, interface, or enum (but not annotation)

 FIELD,        // Field (including enumerated values)

  METHOD,       // Method (does not include constructors)

 PARAMETER,        // Method parameter

 CONSTRUCTOR,      // Constructor

 LOCAL_VARIABLE,   // Local variable or catch clause

 ANNOTATION_TYPE, // Annotation Types (meta-annotations)

 PACKAGE       // Java package

}

    下面我们来修改Greeting注释,为之添加限定范围的语句,这里我们称它为目标(Target)使用方法也很简单,如下:

package com.gelc.annotation.demo.customize;

 

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

public @interface Greeting {

 

    public enum FontColor {

        RED, GREEN, BLUE

    };

 

    String name();

 

    String content();

 

    FontColor fontColor() default FontColor.BLUE;

}

正如上面代码所展示的,我们只允许Greeting注释标注在普通方法和构造函数上,使用在包申明、类名等时,会提示错误信息。

 

注释保持性策略

    在Java编译器编译时,它会识别在源代码里添加的注释是否还会保留,这就是RetentionPolicy。下面是Java定义的RetentionPolicy枚举:

编译器的处理有三种策略:

Ø         将注释保留在编译后的类文件中,并在第一次加载类时读取它

Ø         将注释保留在编译后的类文件中,但是在运行时忽略它

Ø         按照规定使用注释,但是并不将它保留到编译后的类文件中

package java.lang.annotation;

 

public enum RetentionPolicy {

 SOURCE,       // Annotation is discarded by the compiler

 CLASS,        // Annotation is stored in the class file, but ignored by the VM

 RUNTIME       // Annotation is stored in the class file and read by the VM

}

    RetentionPolicy的使用方法与ElementType类似,简单代码示例如下:

package com.gelc.annotation.demo.customize;

 

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.METHOD, ElementType.CONSTRUCTOR })

public @interface Greeting {

 

    public enum FontColor {

        RED, GREEN, BLUE

    };

 

    String name();

 

    String content();

 

    FontColor fontColor() default FontColor.BLUE;

}

 

文档化功能

    Java提供的Documented元注释跟Javadoc的作用是差不多的,其实它存在的好处是开发人员可以定制Javadoc不支持的文档属性,并在开发中应用。它的使用跟前两个也是一样的,简单代码示例如下:

package com.gelc.annotation.demo.customize;

 

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;

 

@Documented

@Retention(RetentionPolicy.RUNTIME)

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

public @interface Greeting {

 

    public enum FontColor {

        RED, GREEN, BLUE

    };

 

    String name();

 

    String content();

 

    FontColor fontColor() default FontColor.BLUE;

}

 

值得大家注意的是,如果你要使用@Documented元注释,你就得为该注释设置RetentionPolicy.RUNTIME保持性策略。为什么这样做,应该比较容易理解,这里就不提了。

 

标注继承

继承应该是Java提供的最复杂的一个元注释了,它的作用是控制注释是否会影响到子类,简单代码示例如下:

package com.gelc.annotation.demo.customize;

 

import java.lang.annotation.Documented;

import java.lang.annotation.ElementType;

import java.lang.annotation.Inherited;

import java.lang.annotation.Retention;

import java.lang.annotation.RetentionPolicy;

import java.lang.annotation.Target;

 

@Inherited

@Documented

@Retention(RetentionPolicy.RUNTIME)

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

public @interface Greeting {

 

    public enum FontColor {

        RED, GREEN, BLUE

    };

 

    String name();

 

    String content();

 

    FontColor fontColor() default FontColor.BLUE;

}

 

概要

    你一定已经感受到元注释的好处和作用了吧,它可以让我们定制的注释功能更明确,约束性更强等好处;在下一篇文章中,我们将学习通过反射来获得这些注释信息。
--------------------------------------------------------------------------------------------------------------

摘要

本文是该系列文章中的最后一篇文章,作为收尾,本文主要讲解如何通过Java反射来获得我们想要的注释信息,如果你对反射比较熟悉,那你应该能轻而易举的读取到想要的注释信息。

 读取注释信息

    当我们想读取某个注释信息时,我们是在运行时通过反射来实现的,如果你对元注释还有点印象,那你应该记得我们需要将保持性策略设置为RUNTIME,也就是说只有注释标记了@Retention(RetentionPolicy.RUNTIME)的,我们才能通过反射来获得相关信息,下面的例子我们将沿用前面几篇文章中出现的代码,并实现读取AnnotationTest类所有方法标记的注释并打印到控制台。好了,我们来看看是如何实现的吧:

package com.gelc.annotation.demo.reflect;

 import java.lang.annotation.Annotation;

import java.lang.reflect.Method;

 public class AnnotationIntro {

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

         Method[] methods = Class.forName("com.gelc.annotation.demo.customize.AnnotationTest").getDeclaredMethods();

        Annotation[] annotations; 

        for (Method method : methods) {

            annotations = method.getAnnotations();

            for (Annotation annotation : annotations) {

                System.out.println(method.getName() + " : "        + annotation.annotationType().getName());

            }

        }

    }

}

 概要

    关于Java Annotation的介绍到此告一段落,如果大家还有疑问和其他问题,欢迎与我联系。

本文转自kenty博客园博客,原文链接http://www.cnblogs.com/kentyshang/archive/2007/06/26/796233.html如需转载请自行联系原作者


kenty

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

分享:
开发与运维
使用钉钉扫一扫加入圈子
+ 订阅

集结各类场景实战经验,助你开发运维畅行无忧

其他文章