IGJ type annotations and checker

This document summarizes the IGJ type annotations, and a checker for them.

The IGJ type annotations and checker constitute an annotation-based implementation of the IGJ immutability checker. For more details, see the IGJ language page.

The supported annotations are @ReadOnly, @Mutable, @Immutable, @Assignable, @AssignsFields, as specified in IGJ Document. @W(int) annotation is added to mimic the template behavior of Generics.

The @ReadOnly type annotation indicates that a reference provides only read-only access. The plugin issues an error whenever mutation happens through a readonly reference, when fields of a readonly reference which are not explicitly marked with @Assignable are reassigned, or when a readonly expression is assigned to a mutable variable. The plugin also emits a warning when casts increase the mutability access of a reference.

The @Mutable annotation ensures that a reference is mutable, no matter the inheritted mutability.

The @Immutable annotation ensures that a reference is immutable to an immutable object.

The @W annotation simulates mutability overloading. It can be applied to classes, methods and parameters. Read the @W javadoc for more details.

The plugin itself is built on the checkers framework and is implemented in the checkers.igj package.

Tiny example

To try the IGJ checker plugin on a source file that uses the IGJ qualifier, use the following command, where javac is the JSR 308 compiler. (You might need to specify the classpath location of checkers.jar; add the option -cp checkers.jar if needed)


  javac -typeprocessor checkers.igj.IGJChecker examples/IGJExample.java