Documente Academic
Documente Profesional
Documente Cultură
an introduction to
Java Annotations
Walter Harley
BEA Systems Inc.
© 2008 by BEA Systems Inc.; made available under the EPL v1.0 | 3/18/2008 | Java Annotations
@ Introduction
• Who am I?
Walter Harley, BEA Systems Inc.
JDT APT lead; Eclipse committer since 2005
Caveat: I am not a J2EE developer
2
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Quickly, what’s an annotation?
@interface Author {
String name();
declaration
int year();
}
3
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Where did annotations come from?
4
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Agenda
• Introduction
• How are annotations used?
• How do annotations fit into the language?
• What’s on the horizon?
• Q&A
5
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
How are annotations used?
6
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Annotations as fancy comments
7
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Using annotations with IDE support
8
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Annotation processing at compile time
9
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Processing annotations on class files
• Can modify existing class – which APT doesn’t let you do.
• Practical example: Resin app server
@TransactionAttribute(REQUIRED) inserts transaction locking code
around calls that need to be atomic.
10
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Reading annotations at runtime (JUnit 4)
@Test(expected = IndexOutOfBoundsException.class)
public void empty() {
List l = new ArrayList<Object>();
l.get(0); // should throw exception
}
11
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Reading annotations at runtime
(Hibernate)
edit compile deploy classload run
@NotEmpty
@Length(min = 2, max = 50)
public String getLastName () {
return “”; // runtime exception!
}
12
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Agenda
• Introduction
• How are annotations used?
• How do annotations fit into the language?
• What’s on the horizon?
• Q&A
13
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Declaring a marker annotation type
package p;
declaration
(MyAnno.java) @interface MyAnno {}
import p.MyAnno;
usage
(MyClass.java @MyAnno class MyClass {}
)
14
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Declaring a full annotation type
@interface Since {
int major();
declaration
int minor() default 0;
}
@Since(major = 3,
usage minor = 4)
class MyClass {}
15
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Declaring a single-valued annotation type
@interface MaxLength {
declaration int value() default 80;
}
interface Foo {
usage @MaxLength(25) String getFirstName();
@MaxLength String getLastName();
}
16
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Annotation types look like interfaces...
@interface ScreenFormat {
enum COLOR { RED, BLUE, GREEN, BLACK }
COLOR background() default BLACK;
17
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Annotation types can be used like
interfaces...
@interface MyAnno {}
...
class X implements MyAnno { // discouraged
Class<? extends Annotation> annotationType() {
MyAnno a = this;
return a.getClass();
}
}
18
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
...but with many restrictions
@interface MyAnno<T>
extends IFoo
{
int intVal(int x);
Class<T> type(); // Class<?> is okay
String name() throws MyException;
}
• Cannot be generic.
• Cannot explicitly extend any other interfaces.
• Methods cannot have any parameters
• Methods cannot have any type parameters
• Method declarations cannot have a throws clause
19
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Members can only be of certain types
package p;
@interface MyAnno {
String[] names();
Class<? extends SomeType> type();
AnotherAnno[] nestedAnnos();
Object bean(); // not a legal member type
}
20
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
How do you annotate code?
@A class X {
@A @B(“quux”) public void foo(@C x) { ... }
@B private String s;
}
21
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Package annotations
// file package-info.java:
@Deprecated
package p;
// no other contents in file
22
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Using an annotation: member restrictions
23
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Where do you get annotations?
24
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Built-in annotations
@Deprecated class Y {
public abstract int foo();
}
class X extends Y {
@SuppressWarnings(“unchecked”) List numbers;
@Override public int foo() { ... }
}
25
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Built-in annotations for annotations
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.FIELD, ElementType.PARAMETER })
@Documented
@Inherited
@interface MyAnno { }
• @Retention: does MyAnno get compiled into class file, and does it
get loaded into the VM so it can be reflected on? Default is CLASS.
• @Target: to which elements can MyAnno be applied?
• @Documented: will MyAnno be mentioned in javadoc of the
classes it is present on? (Is it part of the API contract?)
• @Inherited: if MyAnno is present on a class, is it inherited by
subclasses?
26
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Processing annotations at compile time
27
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
The APT APIs
28
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Reflecting on annotations at runtime
@interface MaxLength { int value(); }
class ValidatingMethodCaller {
String validate(java.lang.reflect.Method m, …) {
MaxLength maxAnno = m.getAnnotation(MaxLength.class);
String s = (String)m.invoke(…);
if (maxAnno != null && s.length() > maxAnno.value() {
throw new ValidationException(“exceeded max length”);
}
return s;
}
}
29
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Agenda
• Introduction
• How are annotations used?
• How do annotations fit into the language?
• What’s on the horizon?
• Q&A
30
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
JSR-305: annotations for software quality
31
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
JSR-308: annotations in more places
• Declarations are the only thing that can be annotated, now.
• Proposal is to support annotations on many other elements
Casts (@NonNull)
Throws clauses (@Critical)
Switch statements (@NoFallThrough)
Array elements
Type parameters
Type bounds
etc...
• Making use of such annotations, however, requires much
deeper APIs for code inspection than we have now.
• Emphasis on compile-time checking; many of these
constructs don’t even exist at runtime.
32
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
SWAGs about the future
33
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
Agenda
• Introduction
• How are annotations used?
• How do annotations fit into the language?
• What’s on the horizon?
• Q&A
34
Java Annotations | © 2008 by BEA Systems Inc.; made available under the EPL v1.0
@
an introduction to
Java Annotations
Walter Harley
BEA Systems Inc.
© 2008 by BEA Systems Inc.; made available under the EPL v1.0 | 3/18/2008 | Java Annotations