Core Java Advanced LiveLessons

Annotations

Slide navigation: Forward with space bar, → arrow key, or PgDn. Backwards with ← or PgUp.

.jpg

Know how to annotate declarations and type uses

What Are Annotations?

An annotation is a tag that you insert into the source code:
```
@Test public void testEmptyInput() { ... }
```
You can annotate:
1. Declarations of methods, variables, classes, and so on.
2. Types that occur in declarations, casts, instanceof checks, and method references.
Annotations don't change how your programs are compiled.
Annotations are processed by tools.
Annotations can be processed:
- At the source level.
- When a class is loaded.
- Through reflection in a program.

Annotation Elements

Annotations can have key/value pairs called elements:
```
@Test(timeout=10000)
```
An annotation element can be one of the following:
- A primitive type value.
- An instance of String, Class, or an enumerated type.
- An annotation.
- An array of the preceding (but not an array of arrays).

Example:

@BugReport(showStopper=true,
    assignedTo="Harry",
    testCase=CacheTest.class,
    status=BugReport.Status.CONFIRMED)

Syntax for Annotation Elements

Elements can have default values.
- For example, in JUnit, the default for timeout in @Test is 0L.

If the only specified element has key value, you can omit the key:

@SuppressWarnings("unchecked") // Same as @SuppressWarnings(value="unchecked")

Use braces for arrays with two or more elements:

@BugReport(reportedBy={"Harry", "Fred"})
@BugReport(reportedBy="Harry") // Same as {"Harry"}

An annotation element can be another annotation:
```
@BugReport(ref=@Reference(id=11235811), ...)
```

Multiple and Repeated Annotations

An item can have multiple annotations:

@Test
@BugReport(showStopper=true, reportedBy="Joe")
public void checkRandomInsertions()

If an annotation is declared to be repeatable, it can be repeated:

@BugReport(showStopper=true, reportedBy="Joe")
@BugReport(reportedBy={"Harry", "Carl"})
public void checkRandomInsertions()

Annotating Declarations

You can annotate the following declarations:

Methods and constructors.
Classes (including enum) and interfaces (including annotation interfaces).
```
@Entity public class User { ... }
```

Fields, local variables, and parameter variables.

@SuppressWarnings("unchecked") List<User> users = ...;
public User getUser(@Param("id") String userId)

Type parameters.

public class Cache<@Immutable V> { ... }

Packages.

@GPL(version="3") package com.horstmann.corejava; // In package-info.java
import org.gnu.GPL; // Imports the GPL annotation

Annotations for local variables and packages are discarded when a class is compiled.

Annotating Type Uses

A declaration annotation says something about the item being declared:

public User getUser(@NonNull String userId)
    // userId is assumed to be non-null

Suppose we declare a List<String> userIds and want to record the assumption that all elements are non-null.
Can't annotate the declaration of the userIds variable.
Instead, annotate the type use:
```
List<@NonNull String> userIds
```

With arrays, position matters:

@NonNull String[][] words,
String @NonNull [][] words,
String[] @NonNull [] words

More examples of type use annotations:

if (text instanceof @Localized String)
public String read() throws @Localized IOException
List<@Localized ? extends Message>
@Localized Message::getText

Explicit Receivers

Suppose we annotate parameters that are not mutated:
```
public boolean equals(@ReadOnly Object other)
```
How do we specify that this isn't mutated?

Use the “receiver syntax”:

public boolean equals(@ReadOnly Point this, @ReadOnly Object other)

Especially created for annotations, but legal without them:
```
public boolean equals(Point this, Object other)
```

Can annotate the hidden OuterClass.this parameter of an inner class constructor:

public class Sequence {
    class Iterator implements java.util.Iterator<Integer> {
        public Iterator(@ReadOnly Sequence Sequence.this) { ... }
    }
    ...
}

Define your own annotations

Annotation Types

Annotations are defined by annotation interfaces:

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Test {
    long timeout();
    ...
}

The @interface declaration creates an actual Java interface.
Methods in the interface correspond to annotation elements.
@Target and @Retention are meta-annotations: annotations of annotations.
@Target specifies what this annotation can be applied to.
@Retention specifies where the annotation can be accessed.
- Possible values are SOURCE, CLASS, RUNTIME

Default Values

Add a default clause after the interface method:

public @interface Test {
    long timeout() default 0L;
    ...
}

Default values can be arrays and annotations:

public @interface BugReport {
    String[] reportedBy() default {};
        // Defaults to empty array
    Reference ref() default @Reference(id=0);
        // Default for an annotation
    ...
}

Be familiar with the annotations in the Java API

Annotations for Compiling

Use the @Deprecated annotation to mark deprecated features. If anyone uses them, the compiler will emit a warning.

The @Override annotation makes the compiler check that you really override a method:

public class Point {
    @Override public boolean equals(Point other) { ... }
    ...
}

The @SuppressWarnings annotation suppresses compiler warnings. Typical use:

@SuppressWarnings("unchecked") T[] result = (T[]) Array.newInstance(cl, n);

The @FunctionalInterface annotation checks that an interface has a single abstract method:
```
@FunctionalInterface public interface IntFunction<R> {
    R apply(int value);
}
```

lesson05/standardAnnotations

Meta-Annotations

A meta-annotation annotates an annotation interface.

You already saw the @Target and @Retention annotations:

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Test { ... }

The @Documented annotation indicates that the annotation should be included in documentation such as Javadoc.
- @FunctionalInterface is documented, @SuppressWarnings is not.

@Inherited applies to annotations for classes, and indicates that subclasses inherit the annotation:

@Inherited @interface Persistent { }
@Persistent class Employee { . . . }
class Manager extends Employee { . . . } // Also @Persistent

@Repeatable indicates that an annotation can be applied multiple times.

Repeatable Annotations

When an annotation is declared as @Repeatable, you can apply the same annotation multiple times :

@TestCase(params="4", expected="24")
@TestCase(params="0", expected="1")
public static long factorial(int n) { ... }

This is a Java 8 feature. Previously, one had to use a container annotation whose value is an array of annotations:

@TestCases({ 
    @TestCase(params="4", expected="24"),
    @TestCase(params="0", expected="1") })
public static long factorial(int n) { ... }

For backwards compatibility, you still need to declare a container:

@Repeatable(TestCases.class) @interface TestCase {
    String params();
    String expected();
}
@interface TestCases {
    TestCase[] value();
}

Java 9 News Flash - Deprecation

.png

@Deprecated has since and forRemoval attributes.
Deprecated java.util classes Observable, Observer (but not Vector, Hashtable).
The Object.finalize and Runtime.runFinalizersOnExit methods.

Understand how annotations are processed

Processing Annotations at Runtime

Example of runtime annotation: Automatic generation of toString format.
We can't actually add or change the code of toString methods, so we'll provide a static method ToStrings.toString(Object obj)
That method uses reflection to find the field names and values of obj and prints a string such as:
```
Point[x=5,y=10]
```

A user can use the @ToString annotation to customize the format:

@ToString(includeName=false)
public class Point {
    @ToString(includeName=false) private int x;
    @ToString(includeName=false) private int y;
    ...
}

Then Point objects are printed as [5, 10].

Implementing Runtime Annotation Processing

First, we provide the annotation interface:

@Target({ElementType.FIELD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface ToString {
    boolean includeName() default true;
}

In the implementation of ToStrings.toString, get the annotation of the class and its fields:

Class<?> cl = obj.getClass();
ToString classAnnotation = cl.getAnnotation(ToString.class);
for (Field f : cl.getDeclaredFields()) {
    ToString fieldAnnotation = f.getAnnotation(ToString.class);
    if (fieldAnnotation.includeName()) ...
    ...
}

For repeated annotations, call getAnnotationsByType(cl) to get an array of the annotations.

lesson05/runtime

Using Annotations to Generate Source Code

When you read annotations at runtime, you achieve effects through reflection.
Another approach is to generate source code and have it compiled.
Annotations can't modify existing classes, but they can generate source code for new classes.

In our ToStrings example, we can generate source code for that utility class:

public class ToStrings {
    public static String toString(Point obj) {
        Generated code
    }
    public static String toString(Rectangle obj) {
        Generated code
    }
    ...
    public static String toString(Object obj) {
        return Objects.toString(obj);
    }
}

Generating Code for the `ToStrings` Class

Consider an annotation:

@ToString public class Rectangle {
    ...
    @ToString(includeName=false) public Point getTopLeft() { return topLeft; }
    @ToString public int getWidth() { return width; }
    @ToString public int getHeight() { return height; }
}

We would like to generate this code:

public static String toString(Rectangle obj) {
    StringBuilder result = new StringBuilder();
    result.append(“Rectangle[”);
    result.append(toString(obj.getTopLeft()));
    result.append(“,width=”);
    result.append(toString(obj.getWidth()));
    result.append(“,height=”);
    result.append(toString(obj.getHeight()));
    result.append(“]”);
    return result.toString();
}

Annotation Processors

Add “annotation processor” to compiler:

javac -processor ToStringAnnotationProcessor *.java

Compiler invokes annotation processor during multiple “rounds”.
- To see the rounds, run the javac command with the -XprintRounds flag.

Processor inspects annotated elements, using javax.lang.model API:

public boolean process(Set<? extends TypeElement> annotations,
        RoundEnvironment currentRound) {
    ...
    JavaFileObject sourceFile = processingEnv.getFiler().createSourceFile(
       "com.horstmann.annotations.ToStrings");
    PrintWriter out = new PrintWriter(sourceFile.openWriter());
    Print code for package and class
    for (Element e : currentRound.getElementsAnnotatedWith(ToString.class)) {
        if (e instanceof TypeElement) {
            TypeElement te = (TypeElement) e;
            Print code for toString method
        }
    }
}

lesson05/sourcelevel

javac com/horstmann/annotations/ToStringAnnotationProcessor.java
javac -processor com.horstmann.annotations.ToStringAnnotationProcessor sourcelevel/*.java
java sourcelevel.SourceLevelAnnotationDemo

Modifying Classes at Load Time

Use the instrumentation API:

Implement a class with a method:

public static void premain(String arg, Instrumentation instr)

Make a manifest file:
```
Premain-Class: MyAgent
```
Package the agent code and manifest in a JAR file:
```
jar cvfm MyAgent.jar manifest.mf *.class
```

Run your program as

java -javaagent:MyAgent.jar=agentArgument MyProg

Agent can use “bytecode engineering” to modify classes as they are loaded.
The instrumentation API is used in server-side frameworks for dependency injection, persistence, and so on.

Bytecode Engineering

Example: Use annotations for generating logging messages.
- Methods are annoted with @LogEntry(logger=loggerName)
- Agent injects bytecodes for the call:
```
Logger.getLogger(loggerName).entering(className, methodName);
```
- Program emits messages such as:
```
May 17, 2016 10:57:59 AM Item hashCode
FINER: ENTRY
```

The agent goes through these steps when loading a class:

Locate all methods.
For each method, check if it has a LogEntry annotation.

If so, add these bytecodes:

ldc loggerName
invokestatic
java/util/logging/Logger.getLogger:(Ljava/lang/String;)Ljava/util/logging/Logger;
ldc className
ldc methodName
invokevirtual java/util/logging/Logger.entering:(Ljava/lang/String;Ljava/lang/String;)V

Uses ASM library.

lesson05/Logging agent

javac -classpath .:../asm-5.1/lib/\* bytecodeAnnotations/EntryLoggingAgent.java
jar cvfm bytecodeAnnotations/EntryLoggingAgent.jar bytecodeAnnotations/EntryLoggingAgent.mf \
bytecodeAnnotations/Entry*.class
javac set/SetTest.java
java -javaagent:bytecodeAnnotations/EntryLoggingAgent.jar=set.Item -classpath .:../asm-5.1/lib/\* set.SetTest