LAB-1107：Java 注释

如今，Java™ 技术已无处不在：大型企业系统、台式机、手持设备，甚至智能卡都有它的身影。因此，Java 技术是全世界开发人员的首选平台。所有这些都发生 1995 年 Java 技术产生后的较短的时间内。尽管该技术在第一版发布后有过不少更新和改进，但通过并入一系列 Java Specification Request（JSR），核心 Java 平台 5.0 版带来的语言层面的更新和改进是前所未有的。在本次动手课程中，您将学习到所有这些更新以及如何使用 Java 5.0 平台构建桌面应用程序。本动手实验室将指导您使用 Java 注释。

软件需求

开始之前，需要在您的计算机中安装以下软件。

Java Standard Development Kit (JDK™)版本 5.0（下载）。

如果已经安装了 JDK 5.0，那么可以跳过此步骤。
安装文件的名称如下所示（针对 JDK 5.0 更新版本 x）。

jdk-1_5_0_xx-windows-i586-p.exe（Windows）
jdk-1_5_0_xx-linux-i586.bin（Linux）
jdk-1_5_0_xx-solaris-i586.sh（Solaris x86）

NetBeans IDE 5.5（下载）

在安装 NetBeans IDE 5.5 时，安装程序会询问使用哪个版本的 JDK。

1107_javase5annotation.zip（下载）

其中含有本文档和实验室内容
下载此压缩文件，并将它解压到任意目录中

变更记录

2007 年 3 月 12 日：创建
2007 年 6 月 10 日：添加课外练习

练习 1：覆盖注释

(1.1)覆盖注释

0. 如未启动 NetBeans IDE 则启动它。

1. 创建一个新 NetBeans 项目

选择文件->新建项目（Ctrl+Shift+N）。此时将出现新建项目对话框。
在选择项目窗格中，选择类别列表中的 Java，并选择项目列表中的 Java 应用程序。单击下一步按钮。
在名称和位置窗格中的项目名称字段中键入 OverrideAnnotation 作为项目名。
在创建主类字段中键入 OverrideAnnotation。（如下图 1.10 所示）
单击完成按钮。

图 1.10：创建一个新项目

注意到出现了 OverrideAnnotation 项目，IDE 生成的 OverrideAnnotation.java 显示在 NetBeans IDE 的源编辑器窗口中。

2. 根据代码 1.11 修改由 IDE 生成的 OverrideAnnotation.java。仔细阅读该代码，需要特别注意粗体部分。

public class OverrideAnnotation {

    private String name;
    private int id;

    /**
     * Constructor
     **/
    public OverrideAnnotation(){
        name = "Java Passion!";
    }

    public String getName(){
        return name;
    }

    public void setName(String name){
        this.name = name;
    }

    public int getId(){
        return id;
    }

    public void setId(int id){
        this.id = id;
    }

    /**
     * Test of equals method overriding vs. overloading
     * For exercise 1 change this method
     **/
    public boolean equals(String otherName){
        int comparisson = name.compareTo(otherName);

        return (comparisson == 0);
    }

    public static void main(String[] args){
        // TODO code application logic here
    }

}

代码 1.11：不带 @Override 注释的 equals()方法。3. 生成和运行项目

右键单击 ExtendThreadClassTest0 项目并选择运行。
注意到代码编译成功（如下图 1.13 所示）。这一结果并不理想。我们想实现的是在运行时检查出问题。

Created dir: C:\handson2\development\javase5generics\samples(2)\OverrideAnnotation\build\classes
Compiling 1 source file to C:\handson2\development\javase5generics\samples(2)\OverrideAnnotation\build\classes
compile:
run:
BUILD SUCCESSFUL (total time: 1 second)

图 1.13：运行 ExtendThreadClassTest0 应用程序的结果

5. 根据代码 1.15 修改 ExtendThreadClassTest0.java。需要添加的代码段突出显示为蓝色粗体字。

public class OverrideAnnotation {

    private String name;
    private int id;

    /**
     * Constructor
     **/
    public OverrideAnnotation(){
        name = "Java Passion!";
    }

    public String getName(){
        return name;
    }

    public void setName(String name){
        this.name = name;
    }

    public int getId(){
        return id;
    }

    public void setId(int id){
        this.id = id;
    }

    /**
     * Test of equals method overriding vs. overloading
     * For exercise 1 change this method
     **/
    @Override
    public boolean equals(String otherName){
        int comparisson = name.compareTo(otherName);

        return (comparisson == 0);
    }

    public static void main(String[] args){
        // TODO code application logic here
    }

}

代码 1.15：含 @Override 注释的 equals()方法

6. 注意到编译程序现在检查出一个问题。这正是我们想实现的行为。

图 1.16：结果

7. 根据代码 1.17 修改 ExtendThreadClassTest0.java。需要添加的代码段突出显示为蓝色粗体字。

public class OverrideAnnotation {

    private String name;
    private int id;

    /**
     * Constructor
     **/
    public OverrideAnnotation(){
        name = "Java Passion!";
    }

    public String getName(){
        return name;
    }

    public void setName(String name){
        this.name = name;
    }

    public int getId(){
        return id;
    }

    public void setId(int id){
        this.id = id;
    }

    /**
     * Test of equals method overriding vs. overloading
     * For exercise 1 change this method
     **/
    @Override
    public boolean equals(Object otherName){
        String newName = (String)otherName;
        int comparison = name.compareTo(newName);

        return (comparison == 0);
    }

    public static void main(String[] args){
        // TODO code application logic here
    }

}

代码 1.17：使其成为覆盖的方法

8. 编译该项目。注意到再也没有编译错误了。

解决方案：针对此练习的解决方案作为可运行的 NetBeans 项目包含在动手实验室的压缩文件中。项目文件位于 <LAB_UNZIPPED_DIRECTORY>/javase5annotation/samples/OverrideAnnotation。您可以打开并运行它。

结束语

练习 2：单成员注释

许多注释只需要附加单个值。仔细阅读包含单成员注释定义的 Mutator.java 文件。本练习的目的是编辑 AnnotatedClass.java 文件并为 setName 方法添加一个 Mutator 注释。有两种实现方法。第一种方法是按以下要求修改代码：

(2.1)通过实现 Runnable 接口创建和启动线程 —— start()方法不在构造方法中

1. 创建一个新的 NetBeans 项目

选择文件->新建项目（Ctrl+Shift+N）。此时将出现新建项目对话框。
在选择项目窗格中，选择类别列表中的 Java，并选择项目列表中的 Java 应用程序。单击下一步按钮。
在名称和位置中的项目名称字段中键入 MutatorAnnotation 作为项目名。
在创建主类字段中键入 MutatorAnnotation。
单击完成按钮。

注意到生成了 MutatorAnnotation 项目，由 IDE 生成的 RunnableThreadTest1.java 显示于 NetBeans IDE 源编辑器的窗口中。

2. 根据代码 2.11 修改由 IDE 生成的 MutatorAnnotation.java。此修改是将一个 Mutator 注释添加到 setName 方法中。我们使用以上提及的第一种方法。仔细阅读该代码，需要特别注意粗体部分。

public class MutatorAnnotation {

    private String name;
    private int id;

    /**
     * Constructor
     **/
    public MutatorAnnotation(){
        name = "Java Passion!";
    }

    public String getName(){
        return name;
    }

    @Mutator(variable = "name")
    public void setName(String name){
        this.name = name;
    }

    public int getId(){
        return id;
    }

    public void setId(int id){
        this.id = id;
    }

    /**
     * Test of equals method overriding vs. overloading
     * For exercise 1 change this method
     **/
    @Override
    public boolean equals(Object otherName){
        String newName = (String)otherName;
        int comparison = name.compareTo(newName);

        return (comparison == 0);
    }

    public static void main(String[] args){
        // TODO code application logic here
    }

}

代码 2.11：MutatorAnnoation

3. 编写 Mutator.java。

public @interface Mutator {
String variable();
}

代码 2.12：Mutator.java

4. 生成（编译）该项目

右键单击 MutatorAnnotation 项目并选择编译项目或运行项目。
注意到编译成功。

5. 根据代码 2.13 修改由 IDE 生成的 MutatorAnnotation.java。

public class MutatorAnnotation {

    private String name;
    private int id;

    /**
     * Constructor
     **/
    public MutatorAnnotation(){
        name = "Java Passion!";
    }

    public String getName(){
        return name;
    }

    @Mutator("name")
    public void setName(String name){
        this.name = name;
    }

    public int getId(){
        return id;
    }

    public void setId(int id){
        this.id = id;
    }

    /**
     * Test of equals method overriding vs. overloading
     * For exercise 1 change this method
     **/
    @Override
    public boolean equals(Object otherName){
        String newName = (String)otherName;
        int comparison = name.compareTo(newName);

        return (comparison == 0);
    }

    public static void main(String[] args){
        // TODO code application logic here
    }

}

代码 2.13：经过修改的 MutatorAnnotation.java

6. 注意到编译错误。（如图 2.13 和图 2.14 所示）如前所述，对单成员注释而言，用于该注释的标识符必须为调用值。

Compiling 2 source files to C:\handson2\development\javase5generics\samples(2)\MutatorAnnotation\build\classes
C:\handson2\development\javase5generics\samples(2)\MutatorAnnotation\src\MutatorAnnotation.java:18: cannot find symbol
symbol : method value()
location: @interface Mutator
@Mutator("name")
1 error
BUILD FAILED (total time:0 seconds)

图 2.14：编译错误

图 2.14：编译错误

6. 根据代码 2.15 修改 Mutator.java。

public @interface Mutator {
String value();
}

代码 2.15：经过修改的 Mutator.java

7. 编译（生成）该项目

右键单击 MutatorAnnotation 项目并选择运行或编译项目。
注意到该编译成功。

解决方案：针对此练习的解决方案作为可运行的 NetBeans 项目包含在动手实验室的压缩文件中。项目文件位于 <LAB_UNZIPPED_DIRECTORY>/javase5annotation/samples/MutatorAnnotation。您可以打开并运行它。

返回练习顶部

结束语

在本练习中，您了解了如何使用两种不同的方法添加单成员注释。

练习 3：多成员注释

(3.1)多成员注释

1. 创建一个新的 NetBeans 项目

选择文件->新建项目（Ctrl+Shift+N）。此时将出现新建项目对话框。
在选择项目窗格中，选择类别列表中的 Java，并选择项目列表中的 Java 应用程序。单击下一步按钮。
在名称和位置窗格中的项目名称字段中键入 MultipleMemberAnnotation 作为项目名。
在创建主类字段中键入 MultipleMemberAnnotation。
单击完成按钮。

注意到出现了 MultipleMemberAnnotation 项目，由 IDE 生成的 MultipleMemberAnnotation.java 显示于 NetBeans IDE 的源编辑器窗口中。

2. 根据代码 3.11 修改 IDE 生成的 MultipleMemberAnnotation.java。仔细阅读该代码，需要特别注意粗体部分。

public class MultipleMemberAnnotation {
private String name;
private int id;

public MultipleMemberAnnotation(){
    name = "Java Passion!";
}

@Accessor(variableName = "name")
public String getName(){
    return name;
}

@Accessor(variableName = "name", variableType = "int")
public int getId(){
    return id;
}

public void setId(int id){
    this.id = id;
}

/**
   * Test of equals method overriding v. overloading
   * For exercise 1 change this method
   **/
@Override
public boolean equals(Object otherName){
    String newName = (String)otherName;
    int comparison = name.compareTo(newName);

    return (comparison == 0);
}

    public static void main(String[] args){
        // TODO code application logic here
    }
}

代码 3.11：MultipleMemberAnnotation.java

3. 根据代码 3.12 编写 Accessor.java。本文件为访问器方法定义了一个注释。（访问器方法是访问字段值并采取 getXXX()形式的方法。）此注释含有定义为注释成员的变量名和变量类型。该例也展示了如何为其中一个成员设置默认值。仔细阅读该代码，需要特别注意粗体部分。

/**
* Annotation definition for an accessor method. This shows the use of
* multiple members.
**/
public @interface Accessor {
String variableName();
String variableType()default "String";
}

代码 3.12：SimpleThread.java

4. 生成和运行项目

右键单击 MultipleMemberAnnotation 项目并选择生成。
注意到编译成功。

compile:
Building jar: C:\handson2\development\javase5generics\samples(2)\MultipleMemberAnnotation\dist\MultipleMemberAnnotation.jar
To run this application from the command line without Ant, try:
java -jar "C:\handson2\development\javase5generics\samples(2)\MultipleMemberAnnotation\dist\MultipleMemberAnnotation.jar"
jar:
BUILD SUCCESSFUL (total time:0 seconds)

图 3.13：运行 MultipleMemberAnnotation 应用程序的结果

解决方案：针对此练习的解决方案作为可运行的 NetBeans 项目包含在动手实验室的压缩文件中。项目文件位于 <LAB_UNZIPPED_DIRECTORY>/javase5annotation/samples/MultipleMemberAnnotation。您可以打开并运行它。

结束语

练习 4：复杂注释类型

(4.1)复杂注释类型

1. 创建一个新的 NetBeans 项目

选择文件->新建项目（Ctrl+Shift+N）。此时将出现新建项目对话框。
在选择项目窗格中，选择类别列表中的 Java，并选择项目列表中的 Java 应用程序。单击下一步按钮。
在名称和位置窗格中的项目名称字段中键入 ComplexAnnotation 作为项目名。
在创建主类字段中键入 ComplexAnnotation。
单击完成按钮。

注意到出现了 ComplexAnnotation 项目，由 IDE 生成的 ComplexAnnotation.java 显示于 NetBeans IDE 的源编辑器窗口中。

2. 根据代码 4.11 修改由 IDE 生成的 ComplexAnnotation.java。

@Reviewer(@Name(first = "James", last = "Gosling"))
public class ComplexAnnotation {

    public static void main(String[] args){
        // TODO code application logic here
    }

}

代码 4.11：ComplexAnnotation.java

3. 根据代码 4.12 编写 Name.java。

import java.lang.annotation.*;

public @interface Name {
String first();
String last();
}

代码 4.12：PrintStringsThread.java

4. 根据代码 4.13 编写 Reviewer.java。仔细阅读该代码，需要特别注意粗体部分。

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
public @interface Reviewer {
Name value();
}

代码 4.13：TwoStrings.java

5. 编译和运行项目

右键单击 ComplexAnnotation 项目并选择生成。
注意到输出窗口的编译结果。（如图 4.14 所示）

compile:
run:
BUILD SUCCESSFUL (total time:0 seconds)

图 4.14：运行 ComplexAnnotation 应用程序的结果

解决方案：针对此练习的解决方案作为可运行的 NetBeans 项目包含在动手实验室的压缩文件中。项目文件位于 <LAB_UNZIPPED_DIRECTORY>/javase5annotation/samples/ComplexAnnotation。您可以打开并运行它。
返回练习顶部

结束语

练习 5：元注释

为注释类型声明进行注释的注释类型称为元注释类型。java.lang.annotation 这个包提供了几个这样的注释类型。元注释类型可以用于限制其进行注释的注释类型。

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)

Target 元注释被用于指定注释应用的位置。可能的选择包含以下内容：

FIELD
TYPE （类、接口或枚举定义）
METHOD
PARAMETER
CONSTRUCTOR
LOCAL_VARIABLE
ANNOTATION_TYPE
PACKAGE

Retention 元注释被用于指定注释要保持多长时间。可能的选择包含以下内容：

SOURCE：此注释信息只保留在源代码中，并不记录在生成的类文件中。
CLASS：此注释被编译器记录在类文件中，但在运行时不必被虚拟机保留。如果 @Retention 注释未进行指定，此注释即为默认值。
RUNTIME：注释被编译器记录于类文件中，由虚拟机在运行时进行保留，并可被反射读取。

在本练习中，您了解如何使用两个元注释类型。

（5.1）无线程间通信的生产者-消费者

1. 创建一个新的 NetBeans 项目

选择文件->新建项目（Ctrl+Shift+N）。此时将出现新建项目对话框。
在选择项目窗格中，选择类别列表中的 Java，并选择项目列表中的 Java 应用程序。单击下一步按钮。
在名称和位置窗格中的项目名称字段中键入 MetaAnnotation 作为项目名。
在创建主类字段中键入 MetaAnnotation。
单击完成按钮。

注意到生成了 MetaAnnotation 项目，由 IDE 生成的 MetaAnnotation.java 显示于 NetBeans IDE 源编译器窗口中。

2. 根据代码 5.11 修改由 IDE 生成的 MetaAnnotation.java。

public class MetaAnnotation {

    private String name;

    @Exposed("name")
    public void setName(String name){
        this.name = name;
    }
    public static void main(String[] args){
        // TODO code application logic here
    }

}

代码 5.11：MetaAnnotation.java

3. 生成和运行项目

右键单击 MetaAnnotation 项目并选择运行。
注意到编译出错。（如图 5.12 所示）

Compiling 2 source files to C:\handson2\development\javase5annotation\samples\MetaAnnotation\build\classes
C:\handson2\development\javase5annotation\samples\MetaAnnotation\src\MetaAnnotation.java:6: annotation type not applicable to this kind of declaration
@Exposed("name")
1 error
BUILD FAILED (total time:0 seconds)

图 5.12：编译错误

4. 根据代码 5.14 修改 MetaAnnotation.java 所做的修改是将 @Expose 注释用于指定一个字段而不是一个方法。

public class MetaAnnotation {

    @Exposed("name")
    private String name;

    // @Exposed("name")
    public void setName(String name){
        this.name = name;
    }
    public static void main(String[] args){
        // TODO code application logic here
    }

}

代码 5.14：MetaAnnotation.java

4. 生成和运行项目

右键单击 MetaAnnotation 项目并选择生成。
注意到编译成功。

解决方案：针对此练习的解决方案作为可运行的 NetBeans 项目包含在动手实验室的压缩文件中。项目文件位于 <LAB_UNZIPPED_DIRECTORY>/javase5annotation/samples/MetaAnnotation。您可以打开并运行它。5. 针对您自己的练习，请通过使用以下代码 5.15 中的数组机制将注释应用到多处。

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

代码 5.15：TARGET 的多重应用

返回练习顶部

结束语

练习 6：在运行时读取注释

(6.1)调度一次性任务

1. 创建一个新的 NetBeans 项目

选择文件->新建项目（Ctrl+Shift+N）。此时将出现新建项目对话框。
在选择项目窗格中，选择类别列表中的 Java，并选择项目列表中的 Java 应用程序。单击下一步按钮。
在名称和位置窗格中，项目名称字段中，键入 RuntimeAnnotation 作为项目名。
在创建主类字段中，键入 RuntimeAnnotation。
单击完成按钮。

注意到出现了 RuntimeAnnotation 项目，由 IDE 生成的 RuntimeAnnotation.java 显示于 NetBeans IDE 的源编辑器窗口中。

2. 根据代码 6.11 修改 IDE 生成的 RuntimeAnnotation.java。仔细阅读该代码，需要特别注意粗体部分。

import java.lang.annotation.*;

public class RuntimeAnnotation {

    AnnotatedClass ac;

    public RuntimeAnnotation(){
        ac = new AnnotatedClass();
    }

    public void printAnnotations(){
        Class c = ac.getClass();
        Annotation[] annotations = c.getAnnotations();
        int numberOfAnnotations = annotations.length;
        System.out.println("Class " + c.getName()+ " has " +
                numberOfAnnotations + " annotations");

        for (int i = 0 ; i < numberOfAnnotations; i++){
            System.out.println("Annotation " + i + ": " + annotations[i] +
                    ", type" + annotations[i].annotationType().getName());
        }
    }

    public static void main(String[] args){
        RuntimeAnnotation ar = new RuntimeAnnotation();
        ar.printAnnotations();
    }
}

代码 6.11：RuntimeAnnotation.java

3. 编写 AnnotatedClass.java。

@Reviewer(@Name(first = "James", last = "Gosling"))
public class AnnotatedClass {

    private String name;
    private int id;

    public AnnotatedClass(){
        name = "Java Passion!";
    }

    @Accessor(variableName = "name")
    public String getName(){
        return name;
    }

    @Mutator(variable ="name")
    public void setName(String name){
        this.name = name;
    }

    @Accessor(variableName = "name", variableType = "int")
    public int getId(){
        return id;
    }

    public void setId(int id){
        this.id = id;
    }

    public boolean equals(String otherName){
        int comparisson = name.compareTo(otherName);

        return (comparisson == 0);
    }
}

代码 6.12：AnnotatedClass.java.

4. 编写 Reviewer.java。这段代码和上面编写的一样。

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
public @interface Reviewer {
Name value();
}

代码 6.13：Reviewer.java

5. 编写 Name.java。这段代码和上面编写的一样。

import java.lang.annotation.*;

public @interface Name {
String first();
String last();
}

代码 6.14：Name.java

6. 编写 Mutator.java。这段代码和上面编写的一样。

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
public @interface Mutator {
String variable();
}

代码 6.15：Name.java

7. 编写 Accessor.java。这段代码和上面编写的一样。

import java.lang.annotation.*;

/**
* Annotation definition for an accessor method. This shows the use of
* multiple members.
**/
@Retention(RetentionPolicy.RUNTIME)
public @interface Accessor {
String variableName();
String variableType()default "String";
}

代码 6.16：Name.java

8. 生成和运行项目

右键单击 RuntimeAnnotation 项目并选择生成。
在输出窗口中查看结果。（如图 6.17 所示）

Class AnnotatedClass has 1 annotations
Annotation 0: @Reviewer(value=@Name(first=James, last=Gosling)), typeReviewer

图 6.17：运行 UnRuntimeAnnotation 应用程序的结果

解决方案：针对此练习的解决方案作为可运行的 NetBeans 项目包含在动手实验室的压缩文件中。项目文件位于 <LAB_UNZIPPED_DIRECTORY>/javase5annotation/samples/RuntimeAnnotation。您可以打开并运行它。
返回练习顶部

结束语

课外练习（针对 Sang Shin“Java EE 编程在线课程”的学习者）

2. 将以下文件以 JavaIntro-javase5annotation 作为主题发送到 javaintro1homework@sun.com。

MyOwnAnnotationExample NetBeans 项目的压缩文件（其他人应该能够将其作为 NetBeans 项目打开并运行）。您可以使用自己喜欢的压缩工具，或者使用 JDK 附带的 "jar" 实用工具，如下所示。

cd <包含 MyOwnAnnotationExample 目录的父目录> （假定将项目命名为 MyOwnAnnotationExample）
jar cvf MyOwnAnnotationExample.zip MyOwnAnnotationExample（MyOwnAnnotationExample 目录应当包含 nbproject 目录）

抓取输出屏幕 —— 将其命名为 JavaIntro-javase5annotation.gif 或 JavaIntro-javase5annotation.jpg （或 JavaIntro-javase5annotation<任何图片格式都可以>）。

抓取的屏幕截图只需显示程序正常运行即可。不需要任何修饰和美化。

如果决定使用 NetBeans 之外的其他 IDE，则压缩文件应该包含重新编译项目所需的所有文件（含有所需源文件的 War 文件也可以）。