Annotations

/** * Describes the Request-For-Enhancement(RFE) that led * to the presence

of the annotated API element. */public @interface RequestForEnhancement {

int id();

String synopsis();

String engineer() default "[unassigned]";

String date(); default "[unimplemented]";

}

Once an annotation type is defined, you can use it to annotate declarations. An

annotation is a special kind of modifier, and can be used anywhere that other

modifiers (such as

public

static

, or

final

) can be used. By convention, annotations

precede other modifiers. Annotations consist of an at-sign (

) followed by an

annotation type and a parenthesized list of element-value pairs. The values must

be compile-time constants. Here is a method declaration with an annotation corresponding

to the annotation type declared above:

@RequestForEnhancement(

id = 2868724,

synopsis = "Enable time-travel",

engineer = "Mr. Peabody",

date = "4/1/3007")

public static void travelThroughTime(Date destination) { ... }

An annotation type with no elements is termed a marker annotation type, for example:

/** * Indicates that the specification of the annotated API element * is

preliminary and subject to change. */public @interface Preliminary { }

It is permissible to omit the parentheses in marker annotations, as shown below:

@Preliminary public class TimeTravel { ... }

In annotations with a single element, the element should be named

value

, as shown below:

/**

* Associates a copyright notice with the annotated API element.

*/public @interface Copyright { String value();}

It is permissible to omit the element name and equals sign (

) in a single-element

annotation whose element name is

value

, as shown below:

@Copyright("2002 Yoyodyne Propulsion Systems")

public class OscillationOverthruster { ... }

To tie it all together, we'll build a simple annotation-based test framework. First

we need a marker annotation type to indicate that a method is a test method, and

should be run by the testing tool:

import java.lang.annotation.*;

/**

* Indicates that the annotated method is a test method.

* This annotation should be used only on parameterless static methods.

*/

@Retention(RetentionPolicy.RUNTIME)

@Target(ElementType.METHOD)

public @interface Test { }

Note that the annotation type declaration is itself annotated. Such annotations are

called meta-annotations. The first (

@Retention(RetentionPolicy.RUNTIME)

) indicates

that annotations with this type are to be retained by the VM so they can be read

reflectively at run-time. The second (

@Target(ElementType.METHOD)

) indicates that

this annotation type can be used to annotate only method declarations.

Here is a sample program, some of whose methods are annotated with the above interface:

public class Foo {

@Test

public static void m1() { }

public static void m2() { }

@Test

public static void m3() {

throw new RuntimeException("Boom");

}

public static void m4() { }

@Test

public static void m5() { }

public static void m6() { }

@Test

public static void m7() {

throw new RuntimeException("Crash");

}

public static void m8() { }}

Here is the testing tool:

import java.lang.reflect.*;

public class RunTests {

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

int passed = 0, failed = 0;

for (Method m : Class.forName(args[0]).getMethods()) {

if (m.isAnnotationPresent(Test.class)) {

try {

m.invoke(null);

passed++;

} catch (Throwable ex) {

System.out.printf("Test %s failed: %s %n", m, ex.getCause());

failed++;

}

}

}

System.out.printf("Passed: %d, Failed %d%n", passed, failed); }}

The tool takes a class name as a command line argument and iterates over all the

methods of the named class attempting to invoke each method that is annotated

with the

Test

annotation type (defined above). The reflective query to find out

if a method has a

Test

annotation is highlighted in green. If a test method

invocation throws an exception, the test is deemed to have failed, and a failure

report is printed. Finally, a summary is printed showing the number of tests that

passed and failed. Here is how it looks when you run the testing tool on the

Foo

program (above):

$ java RunTests FooTest public static void Foo.m3() failed:

java.lang.RuntimeException: Boom Test public static void Foo.m7() failed:

java.lang.RuntimeException: Crash Passed: 2, Failed 2

While this testing tool is clearly a toy, it demonstrates the power of annotations

and could easily be extended to overcome its limitations.

zengjinliang

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
Annotations

AnnotationsMany APIs require a fair amount of boilerplate code. For example, in order to write a JAX-RPC web service, you must provide a paired interface and implementation. This boil...
复制链接

扫一扫