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

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

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

4. Annotation Definition • Structured Data • Comparable to records in OCaml @interfaceMyAnnotation { String value(); // member int i() default 123; // member w. default value } @interfaceMarkerAnnotation { // annotation without any members }

5. 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. Annotation Targets in Java 5 @Apackage some.package.name; @BclassMyClass { @CObject field; @DMyClass(@EObject param) { field = param; } @FObject method() { @GObject localVar = field; return localVar; } }

7. New Annotation Targets in JSR308 • All Type Occurrences HashMap<@AString, Object> m; • Arrays String @B[][] a = new String @B[10][2]; • Method Receivers publicString toString() @C { … } • As opposed to return type public@D String toString() { … } • Backward-Compatible to pre-JSR308 • Annotations can be written as comments publicString toString() /*@C*/ { … }

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

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

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

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

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

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

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

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

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

17. Multi-Stage Java Programs @Codedouble power(@Codedouble x, int n) { if (n==0) return @Code (1.0); else return @Code( @Escape(x) * @Escape (power(x, n-1)) ); } double square(doublex) { 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))>.;;

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