java 注解(翻译自Java Tutorials)

原文出自 http://www.cnblogs.com/ggjucheng/archive/2012/12/03/2800487.html

英文出自 http://docs.oracle.com/javase/tutorial/java/javaOO/annotations.html

注解为程序提供数据，但是，它不是程序的一部分。它们不会在注解的代码直接影响应用。

注解有如下的使用

• 编译器信息— 编译器用注解检测到错误或抑制警告。
• 编译时和部署时的处理 — 软件工具可以处理注释的信息来生成代码，XML文件，等等。
• 运行时处理 — 有些注解是在运行时进行检查.

注解可以应用到程序声明的类，字段，方法，和其他程序元素。

@Author(
   name = "Benjamin Franklin",
   date = "3/27/2003"
)
class MyClass() { }
或

@SuppressWarnings(value = "unchecked")
void myMethod() { }

如果有一个元素取名为value，那么这个名字可以被忽略，例如：

@SuppressWarnings("unchecked")
void myMethod() { }

如果注解没有元素，小括号可以被忽略，例如：

@Override
void mySuperMethod() { }

 

文档

许多注解取代了本来已经在代码中的注释。

假设传统的软件组在每个类的类体的开始，使用注释提供了重要的信息：

public class Generation3List extends Generation2List {

   // Author: John Doe
   // Date: 3/17/2002
   // Current revision: 6
   // Last modified: 4/12/2004
   // By: Jane Doe
   // Reviewers: Alice, Bill, Cindy

   // class code goes here

}

使用注解提供一样的元数据，首先要声明一个注解类型，语法是：

@interface ClassPreamble {
   String author();
   String date();
   int currentRevision() default 1;
   String lastModified() default "N/A";
   String lastModifiedBy() default "N/A";
   // Note use of array
   String[] reviewers();
}

注解的声明，就像在interface声明前面添加一个@字符(@是AT,即Annotation Type)。注解类型，其实是一种形式的接口，它会覆盖在后面的课程中。就目前而言，你不需要了解接口

注解的声明的正文，包括注解元素的声明，看起来很像方法。注意，这里可以定义可选的默认值。

一旦注解定义好了，就可以在使用注解时，填充注解的值，就像这样：

@ClassPreamble (
   author = "John Doe",
   date = "3/17/2002",
   currentRevision = 6,
   lastModified = "4/12/2004",
   lastModifiedBy = "Jane Doe",
   // Note array notation
   reviewers = {"Alice", "Bob", "Cindy"}
)
public class Generation3List extends Generation2List {

// class code goes here

}

注意：要让@ClassPreamble的信息出现在Javadoc生成的文档，必须使用@Documented注解定义@ClassPreamble

// import this to use @Documented
import java.lang.annotation.*;

@Documented
@interface ClassPreamble {

   // Annotation element definitions
   
}

 

编译器使用注解

有这么几种注解类型通过语言规范预定义：@Deprecated, @Override, @SuppressWarnings。

@Deprecated—@Deprecated注解指示，标识的元素是废弃的，不应该再使用。编译器会在任何使用到@Deprecated的类，方法，字段的程序，产生警告。当元素是废弃的，它也应该使用Javadoc的@deprecated标识文档化，，如下面的例子。两个Javadoc注释和注解中的“@”符号的使用不是巧合 - 它们是相关的概念上。另外，请注意Javadoc标记开始用小写字母“D”和注解开始以大写字母“D”。

   // Javadoc comment follows
    /**
     * @deprecated
     * explanation of why it
     * was deprecated
     */
    @Deprecated
    static void deprecatedMethod() { }
}
@Override—@Override注解通知编译器，覆盖父类声明的元素。
   // mark method as a superclass method
   // that has been overridden
   @Override 
   int overriddenMethod() { }

 

虽然不要求在覆盖方法时，必须使用注解，但是它可以避免错误。如果一个方法标记为@Override，但是无法正确覆盖父类的任何方法，编译器会产生错误。

@SuppressWarnings—@SuppressWarnings注解，告诉编译器，抑制正常情况下会产生的特定的警告。下面的例子，一个废弃的方法被使用，编译器正常会产生警告，而这个情况下，这个注解导致警告会被抑制。

   // use a deprecated method and tell 
   // compiler not to generate a warning
   @SuppressWarnings("deprecation")
    void useDeprecatedMethod() {
        // deprecation warning
        // - suppressed
        objectOne.deprecatedMethod();
    }

每个编译器的警告属于一个类别。java语言规范有两个类别："deprecation" 和"unchecked"。"unchecked" 会在使用以前的写的泛型的遗留代码进行交互时，产生警告。抑制更多类别的警告，使用下面的语法：

@SuppressWarnings({"unchecked", "deprecation"})

 

注解处理

注解的更高级使用，包括注解处理，读一个java程序，根据注解执行一些动作。例如，它可以产生辅助的源代码，减轻程序员创建的样板代码，始终遵循可预测的模式的工作量。为了推动这个工作，JDK 5.0包含了一个注解处理工具，成为apt。在JDK 6.0中，apt是java编译器的标准的一部分。

运行期使用注解，注解类型本身必须使用@Retention(RetentionPolicy.RUNTIME)注解，例如：

import java.lang.annotation.*; 

@Retention(RetentionPolicy.RUNTIME)
@interface AnnotationForRuntime {

   // Elements that give information
   // for runtime processing
   
}