1. Java Annotations for Types and Expressions Mathias Ricken October 24, 2008 COMP 617 Seminar

2. 1 // never null // p never null // never null class C { Object field; C(Object p) { field = p; } Object get() { return field; } Comments are Discarded Parser Source File Program with comments Program Comments Abstract Syntax Tree (AST) C Object field C(Object p) = fieldp Object get() return field

3. 2 class C { @NonNull Object field; C(@NonNull Object p) { field = p; } @NonNull Object get() { return field; } Annotations are Retained Parser Source File Abstract Syntax Tree C Object field C(Object p) = fieldp Object get() return field Program with annotations Program with annotations @NonNull Annotations are part of the AST  Can be processed automatically

4. 3 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 }

5. 4 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() { … }

6. 5 Annotation Members @interface MyAnnotation { int intMember(); // primitives String stringMember(); // strings Class classMember(); // class literals SomeEnum enumMember(); // enums // annotions OnlyThreadWithName annotMember(); // arrays of the above OnlyThreadWithName[] arrayMember(); }

7. 6 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; }

8. 7 New Annotation Targets in JSR308 Types  Type parameters HashMap m;  Inheritance, bounds class MyClass implements @C SuperClass { … }  Object creation new @D Integer(5);  Class literals Class c = @E String.class;  Static fields @F MyClass.field  Type casts String s = (@G String) myObject;

9. 8 New Annotation Targets in JSR308 All Type Occurrences HashMap 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*/ { … }

10. 9 class C { @NonNull Object field; C(@NonNull Object p) { field = p; } @NonNull Object get() { return field; } Structure of Java Compiler Parser Source File Class File Writer Class File Error p Type Checker AST

11. 10 class C { @NonNull Object field; C(@NonNull Object p) { field = p; } @NonNull Object get() { return field; } Structure of JSR308 Compiler Parser Annotation Checker Plugins AST p Annotation Checker Class File Writer Class File Type Checker Error Source File

12. 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

13. 12 Nullness Checker Define type hierarchy @TypeQualifier @SubtypeOf( {} ) @interface Nullable { } @TypeQualifier @SubtypeOf( { Nullable.class } ) @interface NonNull { } @Nullable Object @NonNull Date @NonNull Object@Nullable Date

14. 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 */ }

15. 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; ???

16. 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;

17. 16 class C { @NonNull Object field; C(@NonNull Object p) { field = p; } @NonNull Object get() { return field; } Source Code Generation Parser Annotation Checker Class File Writer Class File Type Checker Error Source File Code Generator Annotation Checker Plugins Code Generator Plugins

18. 17 class C { @NonNull Object field; C(@NonNull Object p) { field = p; } @NonNull Object get() { return field; } AST Generation Parser Annotation Checker Plugins Annotation Checker Class File Writer Class File Type Checker Error Source File Code Generator Code Generator Plugins

19. 18 Multi-Stage Java Programs @Code double power(@Code double x, int n) { if (n==0) return @Code (1.0); else return @Code (@Escape (x) * @Escape (power(x, n-1)) ); } double square(double x) { return @Run (power(@Code (x), 2)); // generates x * x * 1.0; } Java MetaOCaml @Code generate.. @Escape splice together.~x @Run run generated code.!x

20. 19 Multi-Stage Java Programs @Code double power(@Code double x, int n) { if (n==0) return @Code (1.0); else return @Code (@Escape (x) * @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 ->.. | n ->..;; let square =.!..~(power (.., 2))>.;;

21. 20 Summary Annotations can be processed automatically  Checker plugins for enhanced systems Add annotations on  Block statements @A { … }  Parenthetical expressions @A ( … ) Provide code generator stage  Use for multi-stage programs