Java Annotations for Types and Expressions

Mathias Ricken October 24, 2008 COMP 617 Seminar

Comments are Discarded

Source File
class C { // never null Object field; // p never null C(Object p) { field = p; } // never null Object get() { return field; } }
field p field

Parser Program

Abstract Syntax Tree (AST)

C

Program with comments

C(Object p)

Object field

Object get()

Comments

return

Annotations are Retained

Source File
class C { @NonNull Object field; C(@NonNull Object p) { field = p; } @NonNull Object get() { return field; } }
field p field

Parser Program with annotations Program with annotations

Abstract Syntax Tree

C

@NonNull

C(Object p)

Object field

Object get()

@NonNull @NonNull
= return

Annotations are part of the AST

Can be processed automatically

Annotation Definition


Structured Data
Comparable to records in OCaml

@interface MyAnnotation { String value(); // member int i() default 123; // member w. default value } @interface MarkerAnnotation { // annotation without any members }

Annotation Usage
@MyAnnotation(value="text", i=456) void method() { } // default value for i: 123 @MyAnnotation(value="text") void method2() { } // special case for members called "value" @MyAnnotation("text") void method3() { } // parenthesis can be omitted if no members @MarkerAnnotation void method4() { }

Annotation Members
@interface MyAnnotation { int String Class SomeEnum intMember(); stringMember(); classMember(); enumMember(); // // // // primitives strings class literals enums

// annotions OnlyThreadWithName annotMember(); // arrays of the above OnlyThreadWithName[] arrayMember(); }

Annotation Targets in Java 5

@A package some.package.name; @B class MyClass { @C Object field; @D MyClass(@E Object param) { field = param; } @F Object method() { @G Object localVar = field; return localVar; } }

New Annotation Targets in JSR308



Types
Type parameters HashMap<@A String, Object> m; Inheritance, bounds class MyClass<T extends @B Number> implements @C SuperClass { } Object creation new @D Integer(5); Class literals Class<@E String> c = @E String.class; Static fields @F MyClass.field Type casts String s = (@G String) myObject;

New Annotation Targets in JSR308



All Type Occurrences

HashMap<@A String, Object> m;

Arrays
String @B[][] a = new String @B[10][2];

Method Receivers
public String toString() @C { } As opposed to return type public @D String toString() { }

Backward-Compatible to pre-JSR308
Annotations can be written as comments public String toString() /*@C*/ { }

Structure of Java Compiler

Source File
class C { @NonNull Object field; C(@NonNull Object p) { field = p; } @NonNull Object get() { return field; } }

Parser

Type Checker

Class File Writer Class File

AST

Error

10

Structure of JSR308 Compiler

Source File
class C { @NonNull Object field; C(@NonNull Object p) { field = p; } @NonNull Object get() { return field; } }

Parser

Type Annotation Class File Checker Checker Writer Class File

AST

Error

Error

Annotation Checker Plugins

11

Annotation Checker Plugins

  

Nullness checker
@NonNull Object foo = null; // error: null!

Mutability checkers (Javari, IGJ)

@ReadOnly int i = 0; i = 1; // error: mutation!

Interning checker
@Interned String a = "x".intern(); String b = "x"; if (a==b) // error: identity vs. equality

Defined using extensible framework

12

Nullness Checker


Define type hierarchy

@TypeQualifier @SubtypeOf( {} ) @interface Nullable { } @TypeQualifier @SubtypeOf( { Nullable.class } ) @interface NonNull { } @Nullable

Object

@NonNull Object

@Nullable Date

@NonNull Date

13

Nullness Checker


Override processing for certain AST nodes Flow analysis

Recognizes assignment of constants
Integer i = null; // i always null from here on Integer j = 1; // j never null from here on i = 2; // i never null from here on

Recognizes simple conditionals

if (i==null) { /* i must be null */ } else { /* i can't be null */ }

14

Suggested Extensions


Annotations on Block Statements

@A { }

Annotations on Parenthetical Expressions

@B ( )

Problem: ambiguous
@interface @Sample { int value() default 0; } return @Sample(1) +1; // return @Sample(value=0) (1)+1; or // return @Sample(value=1) +1; ???

15

Resolving Ambiguity


Require parentheses for annotations with members

@interface @Sample { int value() default 0; } @interface @MarkerAnnotation {} return @Sample (1)+1; // return @Sample(value=1) +1; return @Sample() (1)+1; // return @Sample(value=0) (1)+1; return @MarkerAnnotation (1)+1; // return @MarkerAnnotation (1)+1;

16

Source Code Generation

Source File
class C { @NonNull Object field; C(@NonNull Object p) { field = p; } @NonNull Object get() { return field; } }

Parser

Type Annotation Code Class File Checker Checker Generator Writer Class File

Error

Error

Annotation Checker Plugins

Code Generator Plugins

17

AST Generation
Source File
class C { @NonNull Object field; C(@NonNull Object p) { field = p; } @NonNull Object get() { return field; } }

Parser

Type Annotation Code Class File Checker Checker Generator Writer Class File

Error

Error

Annotation Checker Plugins

Code Generator Plugins

18

Multi-Stage Java Programs

@Code double power(@Code double x, int n) { if (n==0) return @Code (1.0); @Escape (x) * else return @Code ( @Escape (power(x, n-1)) ); } double square(double x) { return @Run (power(@Code (x), 2)); // generates x * x * 1.0; }

Java
@Code @Escape @Run

MetaOCaml generate splice together run generated code

.<x>. .~x .!x

19

Multi-Stage Java Programs

@Code double power(@Code double x, int n) { if (n==0) return @Code (1.0); @Escape (x) * else return @Code ( @Escape (power(x, n-1)) ); } double square(double x) { return @Run (power(@Code (x), 2)); // generates x * x * 1.0; }

let rec power(x, n) = match n with 0 -> .<1>. | n -> .<.~x * .~(power (n-1, x))>.;; let square = .! .<fun x -> .~(power (.<x>., 2))>.;;

20

Summary


Annotations can be processed automatically

Checker plugins for enhanced systems

Add annotations on
Block statements Parenthetical expressions
@A { } @A ( )

Provide code generator stage

Use for multi-stage programs