Repeating Annotations

#可重复注解

有时候你需要在定义或者类型使用时多次使用同一个注解。Java8中repeating annotations 可以实现.

例如，你在写一个程序，使用一个定时服务，是你的方法可以在特定的时间或者按着确切的调度计划执行。类似于UNIX系统的 cron 服务.现在你想要设置一个定时器来运行方法, doPeriodicCleanup, 在每个月的最后一天和每个周五的晚上11点。为了是计时器生效，创建@Schedule注解并在方法 doPeriodicCleanup方法上使用两次。第一次明确每个月的最后一天，第二个明确在每个周五晚上11点，一下是代码实例:

1
2
3

@Schedule(dayOfMonth="last")
@Schedule(dayOfWeek="Fri", hour="23")
public void doPeriodicCleanup() { ... }

上一个例子在方法上使用了同一个注解两次。你可以在使用标准注解的任何地方重复注解。例如，你有一个处理访问权限的异常的类。使用一个 @Alert 注解作用于客户经理，另一个作用于管理员:

1
2
3

@Alert(role="Manager")
@Alert(role="Administrator")
public class UnauthorizedAccessException extends SecurityException { ... }

因为共存的原因，重复注解存储在有Java 编译器自动生成的的注解容器 container annotation 中。想要实现这种功能，需要在代码中做两处声明。

Step 1: 定义一个可重复的注解类型

注解类型必须由 @Repeatable元注解标注 meta-annotation. 下面的例子定义了一个自定义的 @Schedule可重负注解类型:

1
2
3
4
5
6
7
8

import java.lang.annotation.Repeatable;
@Repeatable(Schedules.class)
public @interface Schedule {
  String dayOfMonth() default "first";
  String dayOfWeek() default "Mon";
  int hour() default 12;
}

元注解 @Repeatable meta-annotation的值,包含在括号里, 是Java编译器自动生成的存储重复注解的注解容器的类型。本例中注解容器的类型是 Schedules,因此重复注解 @Schedule 存储在 @Schedules 注解中.

没有声明注解类型为可重复时而多次使用会导致编译时错误。

Step 2: 声明注解容器类型

注解容器类型必须有一个 value元素，元素为数组类型.数组的组件类型必须是可重复注解类型。注解容器 Schedules 类型定义如下:

1
2
3

public @interface Schedules {
    Schedule[] value();
}

获取注解Retrieving Annotations

在反射接口 Reflection API中有几种可以取出注释的方法。方法的作用是返回一个单独的注解，例如AnnotatedElement.getAnnotation(Class), 如果请求的注解类型只存在一个，那么结果不会改变，仍然只返回一个注解。如果某注解类型的注解存在多个，则要先获取他们的注解容器类型。这样，遗留代码仍然可以继续生效。在Java SE 8 中引入了其他的方法，可以通过注解容器一次性返回多个注解，例如AnnotatedElement.getAnnotationsByType(Class). 参考AnnotatedElement 类的详细介绍获取更多可用方法的信息。

设计思路Design Considerations

当设计一个注解类型时，你必须要考虑这种注解类型的注解基数cardinality。可以使用注解零次，一次，或者如果注解类型被标记为@Repeatable可以使用多次。同样可以通过@Target元注解可以显示注解类型使用的地方。例如，你可以创建一个只用于方法或者字段的可冲入注解。仔细的设计你的注解类型已保证开发者更加有弹性的使用注解，并发挥强大作用，这是非常重要的。

预定义的注解类型

Java SE API 预定义了一系列的注解类型。一些是被Java编译器使用，另外一是应用于其他注解(注解的注解).

Java语言使用的注解

java.lang 包中所定义的注解类型有 @Deprecated, @Override, 以及 @SuppressWarnings.

@Deprecated @Deprecated 注解表明了标注的元素是不推荐的并且不应该再继续使用。无论什么时候程序使用了有该标记的类，方法，字段，编译器都会产生一个警告。如果元素标记了@Deprecated那么他的主时钟也必须是用Java文档 @deprecated 标签，正如下面的例子。在Java文档注释中使用符号@与注解中一样并不是巧合的coincidental：他们是关联的概念。不过，要注意，Java文档注释里的标签首字母为小写d注解中首字母为D.

1
2
3
4
5
6
7
8

   // Javadoc comment follows
    /**
     * @deprecated
     * explanation of why it was deprecated
     */
    @Deprecated
    static void deprecatedMethod() { }
}

@Override @Override 注解告知编译器元素是为了复写在父类中定义的元素。复写方法将会在接口与继承Interfaces and Inheritance一篇中讨论到.

1
2
3
4

// mark method as a superclass method
// that has been overridden
@Override 
int overriddenMethod() { }

当复写方法的时候并不是必须要使用这个注解，他可以帮助你预防错误。如果标记了@Override标记的方法没有正确的复写他父类中的一个方法，编译器就会产生错误。

@SuppressWarnings @SuppressWarnings 注解告诉编译器，阻止可能产生的特定的警告。下面的例子中，使用了一个不推荐的方法，编译器通常会生成一个警告。在这种情况下，使用这个注解就可以阻止产生警告.

1
2
3
4
5
6
7
8

// 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警告，当遇到泛型 generics出现之前的遗留代码时可能会出现。 如果要阻止多个类型的警告，参考以下语法:

1

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

@SafeVarargs @SafeVarargs 注解，当使用在一个构造器或者方法时，断定该方法在使用可变参数时没有潜在的不安全因素。使用了该注解，与 varargs可变参数使用相关的未检查警告可以被阻止。

@FunctionalInterface @FunctionalInterface 功能接口注解，在Java SE8中引入。表明是一个功能接口，与Java语言标准中定义的功能接口一样.

用于其他注解的注解

用于其注解的注解叫做元注解meta-annotations. java.lang.annotation中定义了数个元注解.

@Retention @Retention 保留注解表明了注解是如何被存储的:

• RetentionPolicy.SOURCE – 该标记表明注解只在资源层面被保留，编译器会忽略.
• RetentionPolicy.CLASS – 该标记表明注解在编译时被保留，JVM会忽略.
• RetentionPolicy.RUNTIME – 该标记表明注解会被JVM保留，可以再运行时使用.

@Documented @Documented 文档注解，表明使用了对应注解的元素，会被Java文档工具Javadoc tool使用。(默认情况下，注解不会被包含在Java文档中)。参考Java文档工具页面 Javadoc tools page，获取更多相关信息.

@Target @Target 注解，限制了限制了注解可以应用于那种Java元素类型。目标注解可以使用如下的元素类型作为它的值:

• ElementType.ANNOTATION_TYPE 可以应用于注解类型.
• ElementType.CONSTRUCTOR 可以应用于构造器.
• ElementType.FIELD 可以应用于字段或者属性（字段、枚举的常量）.
• ElementType.LOCAL_VARIABLE 可以应用于局部变量.
• ElementType.METHOD 可以应用于方法级别的注解.
• ElementType.PACKAGE 可以应用于包的定义.
• ElementType.PARAMETER 可以应用于方法的参数。
• ElementType.TYPE 可以应用于任何的类（接口、类、枚举、注解）。

@Inherited @Inherited 继承注解表明，注解类型可以用从器的父类继承。(默认是不可以继承的)，当用户查询类的注解类型而类本身没有该注解时，就会查询其父类是否有该注解。这个注解只能使用与类的定义.

@Repeatable @Repeatable 可重复的注解，在Java SE 8中引入，表明该注解在同一个声明或者类型处可以使用不止一次。参考可重复注解 Repeating Annotations.

枚举类问题与练习

问题

1. 问题: True or false: 枚举类可以是 java.lang.String类的子类.

练习

1. 练习: 重写 Questions and Exercises: Classes 中 Card 类，使用枚举类来表示扑克中的花色和点数。
2. 练习: 重写 Deck 类.

答案

定义一个注解类型

许多注解代替代码中的注释。

假设一个软件组通常在类体的起始处填写注释已提供重要的信息:

1
2
3
4
5
6
7
8
9
10
11
12

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
}

为了使用注解添加这些元数据，你必须先定义一个注解类型 annotation type. 其语法如下:

1
2
3
4
5
6
7
8
9

@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, 与注解的符号一样).

注解类型是接口 interface的一种格式后面的课程会讲到,现在你不需要理解接口。

上面的注解类型定义，类体中包含了注解类型元素 annotation type element 的定义,看起来像是方法，不过注意，他们可以定义默认值。

定义注解类型之后，你可以使用这个注解类型，并填入元素值，像下面这样:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

@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 注解定义的元素出现在java文档生成器生成的文档中，你必须为 @ClassPreamble 注解的定义添加d @Documented 注解:

1
2
3
4
5
6
7
8
9

// import this to use @Documented
import java.lang.annotation.*;
@Documented
@interface ClassPreamble {
   // Annotation element definitions
   
}

课程: 注解

注解Annotations, 一种元数据的格式,提供程序相关的数据而不是程序本身. 注解并不会直接影响所标注的代码的影响。

注解有一系列的作用，分别如下:

• 编译所用的注解信息 — 注解可以用来侦测错误或者忽略警告.
• 编译时以及部署时的处理Compile-time and deployment-time processing — 软件工具可以处理注解信息来生成代码,XML文件等。
• 运行时的处理Runtime processing — 某些注解可在运行时检测.

本课程解释了哪里可以用到注解，如何应用注解，JavaSE api预定义了那些可用的注解类型，注解类型如何与插件式的系统想结果写出强壮的类型检查代码，以及如何实现可重复的注解。

注解基础

注解的格式

最贱的注解格式实例如下:

1

@Entity

标志符号 (@) 向编译器表示紧跟着的信息是注解，下面的例子注解的名字为Override:

1
2

@Override
void mySuperMethod() { ... }

注解可以包含元素 elements,可以是署名的，也可以是匿名的，元素有对应的值:

1
2
3
4
5

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

或者

1
2

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

如果只有一个名为value的元素，那么元素署名可以省略，如下:

1
2

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

如果注解不包含元素，那么小括号也可以移除，就像之前的@Override注解.

也可以在统一个声明或者定义处使用多个注解:

1
2
3

@Author(name = "Jane Doe")
@EBook
class MyClass { ... }

如果多个注解拥有同样的类型，叫做重复注解repeating annotation:

1
2
3

@Author(name = "Jane Doe")
@Author(name = "John Smith")
class MyClass { ... }

重复注解在Java SE8中支持的，获取更多相关信息可以参看 Repeating Annotations.

注解类型可以是java.lang或者java.lang.annotation包中的一种。之前的例子中Override and SuppressWarnings 是 预定义注解predefined Java annotations.你也可以定义自己的注解类型， Author 和 Ebook 注解是自定义注解类型。

注解可以用在哪里

注解可以用定义：类，字段，方法以及其他编程元素定义时可以使用。挡在定义时使用注解，按照惯例每一个注解占一行.

Java SE8 版本中，注解同样可以应用在类型使用时，以下是一些列子:

• 类型实例创建表达式:

  1	new @Interned MyObject();

• 类型转换:

  1	myString = (@NonNull String) str;

• implements 引用时:

  1 2	class UnmodifiableList<T> implements @Readonly List<@Readonly T> { ... }

• 声明抛出异常时:

  1 2	void monitorTemperature() throws @Critical TemperatureException { ... }

这种形式的注解叫做类型注解 type annotation.获取更多相关信息，参考 类型注解与插件式类型系统Type Annotations and Pluggable Type Systems.

枚举类

枚举类型 enum type 是一种特殊的数据类型，可以使一个变量值为一组预定义的常量来。变量值必须等于预定义的常量值中的一个。常见的例子包括指南者中的方向(值 NORTH, SOUTH, EAST, and WEST) 以及一周中的每一天.

因为他们是常量，所以枚举类的成员都是用大写字母表示。

Java编程语言中，你可以使用enum关键字定义枚举类。例如，一周中的每一天可以定义如下:

1
2
3
4

public enum Day {
    SUNDAY, MONDAY, TUESDAY, WEDNESDAY,
    THURSDAY, FRIDAY, SATURDAY 
}

你可以在任何你想表达一组固定的常量集合时使用枚举类。包含了自然界中的列举类型例如太阳系中的行星以及任何你可能在编译时就知道的任何可能值—例如，菜单中的选项，命令行中的标记等等.

以下代码是如何使用上面定义的Day枚举类型:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

public class EnumTest {
    Day day;
    
    public EnumTest(Day day) {
        this.day = day;
    }
    
    public void tellItLikeItIs() {
        switch (day) {
            case MONDAY:
                System.out.println("Mondays are bad.");
                break;
                    
            case FRIDAY:
                System.out.println("Fridays are better.");
                break;
                         
            case SATURDAY: case SUNDAY:
                System.out.println("Weekends are best.");
                break;
                        
            default:
                System.out.println("Midweek days are so-so.");
                break;
        }
    }
    
    public static void main(String[] args) {
        EnumTest firstDay = new EnumTest(Day.MONDAY);
        firstDay.tellItLikeItIs();
        EnumTest thirdDay = new EnumTest(Day.WEDNESDAY);
        thirdDay.tellItLikeItIs();
        EnumTest fifthDay = new EnumTest(Day.FRIDAY);
        fifthDay.tellItLikeItIs();
        EnumTest sixthDay = new EnumTest(Day.SATURDAY);
        sixthDay.tellItLikeItIs();
        EnumTest seventhDay = new EnumTest(Day.SUNDAY);
        seventhDay.tellItLikeItIs();
    }
}

输出如下:

1
2
3
4
5

Mondays are bad.
Midweek days are so-so.
Fridays are better.
Weekends are best.
Weekends are best.

Java编程语言中的枚举类型比其他语言中的要更加欠打。 enum 声明定义了一个类(交过枚举类型 enum type).枚举类型，类体也可以包含方法以及其他成员。编译器在创建枚举类型时会自动的增加一些特殊的代码。例如，他们有已个静态的values方法可以返回包含所有定义的枚举值的数据。这个方法通常与for-each结构结合使用，来迭代枚举类中的所有类型。例如，下面的代码 Planet 类例子遍历了太阳系中的所有行星.

1
2
3
4

for (Planet p : Planet.values()) {
    System.out.printf("Your weight on %s is %f%n",
                      p, p.surfaceWeight(mass));
}

注意:所有的枚举类型简单的继承了类 java.lang.Enum。因为Java只能继承自一个类（参考 Declaring Classes).Java不支持多重继承 (参考 Multiple Inheritance of State, Implementation, and Type)，因此所有的枚举类都不能再继承任何类。

下面的例子中，Planet是一个枚举类，代表了太阳系中的所有行星.他们通过的常量属性质量和半径来定义。

每一个枚举常量定义的同时包含了质量与半径参数。这些参数在常量创建的时候传递给构造器。Java要求常量必须首先声明，优先与任何的成员和方法。因此，当枚举类有额外的字段和方法时，枚举常量结束时必须以分号semicolon结束.

Note:枚举类的构造器必须是私有级别或者是包级的访问权限。它将在自动创建定义在枚举类体开始的常量。你不能自己调用枚举类的构造方法。

另外，对于他的属性和构造器，Planet提供方法允许你获取每一个行星的表面重力以及重量。下面是一个简单的程序，获取你在地球的体重（任一单位）并计算出你在其他所有星球的体重（同样单位下）:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

public enum Planet {
    MERCURY (3.303e+23, 2.4397e6),
    VENUS   (4.869e+24, 6.0518e6),
    EARTH   (5.976e+24, 6.37814e6),
    MARS    (6.421e+23, 3.3972e6),
    JUPITER (1.9e+27,   7.1492e7),
    SATURN  (5.688e+26, 6.0268e7),
    URANUS  (8.686e+25, 2.5559e7),
    NEPTUNE (1.024e+26, 2.4746e7);
    private final double mass;   // in kilograms
    private final double radius; // in meters
    Planet(double mass, double radius) {
        this.mass = mass;
        this.radius = radius;
    }
    private double mass() { return mass; }
    private double radius() { return radius; }
    // universal gravitational constant  (m3 kg-1 s-2)
    public static final double G = 6.67300E-11;
    double surfaceGravity() {
        return G * mass / (radius * radius);
    }
    double surfaceWeight(double otherMass) {
        return otherMass * surfaceGravity();
    }
    public static void main(String[] args) {
        if (args.length != 1) {
            System.err.println("Usage: java Planet <earth_weight>");
            System.exit(-1);
        }
        double earthWeight = Double.parseDouble(args[0]);
        double mass = earthWeight/EARTH.surfaceGravity();
        for (Planet p : Planet.values())
           System.out.printf("Your weight on %s is %f%n",
                             p, p.surfaceWeight(mass));
    }
}

如果你运行这个类 Planet.class 并且输入参数175, 可以说的如下输出:

1
2
3
4
5
6
7
8
9

$ java Planet 175
Your weight on MERCURY is 66.107583
Your weight on VENUS is 158.374842
Your weight on EARTH is 175.000000
Your weight on MARS is 66.279007
Your weight on JUPITER is 442.847567
Your weight on SATURN is 186.552719
Your weight on URANUS is 158.397260
Your weight on NEPTUNE is 199.207413

嵌套类：问题与练习

问题

1. 问题: 程序 Problem.java 不能编译，你需要怎么做才能让它成功编译?为什么?

2. 使用 Box 类(在 javax.swing 包中)的Java API文档 帮助你问答如下问题 .

   1. 问题: Box 定义了什么静态嵌套类?

   2. 问题: Box 定义了什么内部类?

   3. 问题: Box的内部类的父类是什么?

   4. 问题: Box的哪一个嵌套类你可以在任何一个类中使用?

   5. 问题: 如何创建一个 Box的`Filler嵌套类的实例?

练习

1. 练习: 获取文件 Class1.java. 编译并运行 Class1. 输出是什么?

2. 练习: 下面的联系涉及到修改 DataStructure.java类, 该类在 Inner Class Example 中有讨论.

   1. 定义一个名为 print(DataStructureIterator iterator)的方法.用一个类EvenIterator类的实例调用这个方法实现printEven方法的功能。

1. 调用方法 print(DataStructureIterator iterator) 来打印奇数索引的元素.使用一个匿名类作为方法的参数，代替接口 DataStructureIterator的实例.

1. 定义一个方法 print(java.util.Function<Integer, Boolean> iterator) 实现 print(DataStructureIterator iterator)相同的功能.通过一个lambda表达式参数调用该方法实现打印出偶数下标的元素，重新用lambda表达式参数调用并实现打印出奇数下标的元素。

1. 定义两个方法可以是如下语句分别打印偶数下标对应的值和技术下标对应的值:

   1 2 3 4

   DataStructure ds = new DataStructure() // ... ds.print(DataStructure::isEvenIndex); ds.print(DataStructure::isOddIndex);

嵌套类：问题与练习答案

何时使用嵌套类，局部类，匿名类，Lambda表达式

正如在嵌套类 Nested Classes一章节中提到的,嵌套类可以使你将只是用一次的代码符合逻辑的整理到一块，增加代码的封装性，创建更可读和易于管理的代码。局部类，匿名类以及Lambda表达式同样适用于这些优势；并且他们可以用于更加具体的场景:

• 局部类Local class: 如果你需要创建类的不止一个实例，访问其构造函数，或者引入新的命名类型（因为，譬如你需要在后续条用额外的方法).
• 匿名类Anonymous class: 如果你需要定义额外的字段或者方法就使用匿名类.
• Lambda表达式Lambda expression:
  • 如果你想要封装一个单独的行为床底给其他的代码就是用Lambda表达式。例如，你你需要创建一个具体的作用于集合中每个元素的操作，当一个程序完成时的处理，或者程序遇到错误的处理。
  • 当你需要你功能接口的你个简单实例并且不需要预先的条件限制。（例如，你不需要使用构造器，不需要明明类型，字段，或者额外的方法）
• 嵌套类Nested class: 当你的需求与局部类相似，但是又想让类有更广的可用范围，并且你不需要访问局部变量和更多的方法参数就使用嵌套类。
  • 使用非静态的嵌套类（或者内部类）如果你需要访问闭合空间内的非公有字段或者方法。是用静态的嵌套类如果你不需要这些访问接入。

Lambda 表达式 Lambda Expressions

使用匿名类的一个问题在于，如果你要实现的匿名类非常的简单，例如只包含一个方法的借口，那么匿名列的语法看起来就不够简洁和轻便。这种情况下，你通常会尝试将某个功能作为参数传递给一其他方法，例如当点击按钮的时候会采取什么措施。Lambda表达式可以提供这样的功能，将功能作为方法的参数，或者代码作为数据。

上一节中， Anonymous Classes, 向你展示了实现一个基本的类而不需要命名，譬如只有一个方法的类，不过匿名类看起来有点复杂和笨重。Lambda表达式可以使你更加紧凑的表达一个单方法类的实例。

本节将包含以下的内容:

• Lambda表达式的经典应用Ideal Use Case for Lambda Expressions
  • 方法1：创建搜索某一特点的成员的方法Approach 1: Create Methods That Search for Members That Match One Characteristic
  • 方法2：创建更加通用的搜索方法Approach 2: Create More Generalized Search Methods
  • 方法3：用局部类实现特定搜索规则相关的的代码Approach 3: Specify Search Criteria Code in a Local Class
  • 方法4：用匿名类实现特定搜索规则相关的代码Approach 4: Specify Search Criteria Code in an Anonymous Class
  • 方法5：用Lambda表达式实现特定搜索规则的代码Approach 5: Specify Search Criteria Code with a Lambda Expression
  • 方法6：通过标准的功能接口使用lambda表达式Approach 6: Use Standard Functional Interfaces with Lambda Expressions
  • 方法7：在你的应用中使用Lambda表达式Approach 7: Use Lambda Expressions Throughout Your Application
  • 方法8：使用反应提高可扩展性Approach 8: Use Generics More Extensively
  • 方法9：使用已Lambda表达式作为参数的聚合操作Approach 9: Use Aggregate Operations That Accept Lambda Expressions as Parameters
• 在GUI应用中使用Lambda表达式Lambda Expressions in GUI Applications
• Lambda表达式语法Syntax of Lambda Expressions
• 访问闭合区间的局部变量Accessing Local Variables of the Enclosing Scope
• 目标类型Target Typing目标类型以及方法参数Target Types and Method Arguments
• 序列化Serialization