1. Java Annotations for Invariant Specification
Mathias Ricken
September 22, 2008
COMP 617 Seminar

2. NullPointerException at runtime:
Comments are dumb
class HashMap {
// returns null if no mapping for key
Object get(Object key) { … } }
HashMap m = new HashMap();
Object o = m.get("foo");
String s = o.toString();
NullPointerException at runtime:
o is null

3. Return type Object|null incompatible with type Object
Types are smart
class HashMap {
// returns null if no mapping for key
Object|null get(Object key) { … } }
HashMap m = new HashMap();
Object o = m.get("foo");
String s = o.toString();
Compiler Error:
Return type Object|null incompatible with type Object
This is not Java!

4. Annotations can make Java smarter
class HashMap {
// returns null if no mapping for key
@Nullable Object get(Object key) { … } }
HashMap m = new HashMap();
Object o = m.get("foo");
String s = o.toString();
Compiler Warning:
Return value may be null, assigned to non-null variable.
Pluggable type systems in Java 5 7?

5. Annotation Targets in Java 5
@A package some.package.name;
@B class MyClass {
@NonNull Object field;
@C Object param) {
field = param; }
@NonNull Object method() {
@NonNull Object localVar = field;
return localVar;
Note: Local variable annotations are completely ignored.

6. Concurrency Invariants
interface TableModel {
// may only be called from event thread
void setValueAt(…); }
TableModel m;
// from outside event thread…
m.setValueAt(…);
Possible race condition.

7. Invariant Specification
interface TableModel {
@OnlyEventThread
void setValueAt(…); }
TableModel m;
// from outside event thread…
m.setValueAt(…);
Invariant Violation Warning at Runtime
(but still possible race condition)

8. Comparison to assert Similarity
void setValueAt(…) {
assert (EventQueue.isDispatchThread()); …
Similarity
Debug mode – disabled in production code
@OnlyEventThread
void setValueAt(…) { … }

9. Annotations are Easier to Find
Javadoc produces invariant index

10. Inherited Invariants TableModel Object getValueAt(…)
@OnlyEventThread void setValueAt(…)
Implied
@OnlyEventThread
AbstractTableModel
Object getValueAt(…)
void setValueAt(…)
DefaultTableModel
MySpecialTableModel
Object getValueAt(…)
void setValueAt(…)
Object getValueAt(…)
void setValueAt(…)
Implied
@OnlyEventThread
Implied
@OnlyEventThread

11. @OnlyEventThread TableModel
Inherited Invariants
@OnlyEventThread TableModel
Object getValueAt(…)
void setValueAt(…)
Implied
@OnlyEventThread
AbstractTableModel
Object getValueAt(…)
void setValueAt(…)
Implied
@OnlyEventThread
DefaultTableModel
MySpecialTableModel
Object getValueAt(…)
void setValueAt(…)
Object getValueAt(…)
void setValueAt(…)
Implied
@OnlyEventThread
Implied
@OnlyEventThread

12. Limited Universality A few supplied invariant annotations
@OnlyEventThread
@OnlyThreadWithName
@OnlySynchronizedThis
@NotEventThread
@NotThreadWithName
@NotSynchronizedThis
assert can test an arbitrary predicate
assert (someComplexPredicate());

13. Predicate Invariant Annotations
@PredicateLink(value=Predicates.class, method="eval")
OnlyThreadWithName {
String value; }
Find predicate method 1.
@OnlyThreadWithName("main")
void myMethod() { … } 2.
Call predicate method and
pass as arguments:
this (nor null if static)
data in invariant annotation
Return true or false to indicate violation 3.
public class Predicates {
public static boolean eval(Object this0, String name) {
return Thread.currentThread().getName().
equals(name); }

14. Further Limitation of Annotations
One occurrence of an annotation class per target
@OnlyThreadWithName("main") // illegal; and is
@OnlyThreadWithName("other") // this "and" or "or"?
void myMethod() { … }
Suggestion
@Or({
@OnlyThreadWithName("main"),
@OnlyThreadWithName("other") })
void myMethod() { … }

15. Annotation Members @interface MyAnnotation {
extends OtherAnnotation
not allowed  no subtyping
@interface MyAnnotation {
int intMember; // primitives
String stringMember; // strings
Class classMember; // class literals
SomeEnum enumMember; // enums
// annotions
OnlyThreadWithName annotMember;
// arrays of the above
OnlyThreadWithName[] arrayMember; }

16. No Annotation Subtyping in Java
@interface Or { OnlyThreadWithName[] value; }
@OnlyThreadWithName("other")})
void myMethod() { … } // legal
@NotThreadWithName("other")})
void otherMethod() { … } // illegal
No common supertype for annotations

17. xajavac Modified Compiler
@interface Base {}
@interface OnlyThreadWithName extends Base {
String value; }
@interface NotThreadWithName extends Base {
@interface Or extends Base {
Base[] value;

18. Results Annotations with Subtyping Minimal changes to the compiler
No changes to class file format
Reduced invariant checker by ~1500 lines
Improved code reuse

19. Results Invariant Annotations Annotated part of Swing and DrJava
Discovered and fixed some bugs in DrJava
Hard to do retroactively and without inside knowledge

20. Future Work Reflection library for annotations with subtyping
Annotation getAnnotation(Class c) currently returns the annotation of class c
Annotation[] getAnnotations(Class c) should be added to return all annotations of class c and its subclasses
Modify JSR 308 prototype compiler to support subtyping

21. More Information and Download
Invariant Specification
Annotations with Subtyping