checkers.igj
Class IGJChecker

java.lang.Object
  extended by javax.annotation.processing.AbstractProcessor
      extended by checkers.source.SourceChecker
          extended by checkers.basetype.BaseTypeChecker
              extended by checkers.igj.IGJChecker
All Implemented Interfaces:
Processor

@TypeQualifiers(value={ReadOnly.class,Mutable.class,Immutable.class,I.class,AssignsFields.class,checkers.igj.IGJBottom.class})
public class IGJChecker
extends BaseTypeChecker

A type-checker plug-in for the IGJ immutability type system that finds (and verifies the absence of) undesired side-effect errors. The IGJ language is a Java language extension that expresses immutability constraints, using six annotations: ReadOnly, Mutable, Immutable, I -- a polymorphic qualifier, Assignable, and AssignsFields. The language is specified by the FSE 2007 paper.

See the checkers manual:
IGJ Checker

Field Summary
protected  AnnotationMirror ASSIGNS_FIELDS
          Supported Annotations for IGJ.
protected  AnnotationMirror BOTTOM_QUAL
          Supported Annotations for IGJ.
protected  AnnotationMirror I
          Supported Annotations for IGJ.
protected  AnnotationMirror IMMUTABLE
          Supported Annotations for IGJ.
protected  AnnotationMirror MUTABLE
          Supported Annotations for IGJ.
protected  AnnotationMirror READONLY
          Supported Annotations for IGJ.
 
Fields inherited from class checkers.source.SourceChecker
currentRoot, env, messager, messages, skipPattern, trees
 
Fields inherited from class javax.annotation.processing.AbstractProcessor
processingEnv
 
Constructor Summary
IGJChecker()
           
 
Method Summary
protected  QualifierHierarchy createQualifierHierarchy()
          Returns the type qualifier hierarchy graph to be used by this processor.
protected  TypeHierarchy createTypeHierarchy()
          Creates the type subtyping checker using the current type qualifier hierarchy.
 void init(ProcessingEnvironment env)
          
 boolean isAssignable(AnnotatedTypeMirror varType, AnnotatedTypeMirror receiverType, Tree varTree)
          Return true if the assignment variable is an assignable field or variable, and returns false otherwise.
 boolean isValidUse(AnnotatedTypeMirror.AnnotatedDeclaredType elemType, AnnotatedTypeMirror.AnnotatedDeclaredType use)
          Tests that the qualifiers present on the useType are valid qualifiers, given the qualifiers on the declaration of the type, declarationType.
 
Methods inherited from class checkers.basetype.BaseTypeChecker
createFactory, createSourceVisitor, createSupportedTypeQualifiers, getQualifierHierarchy, getSupportedLintOptions, getSupportedTypeQualifiers, isSubtype
 
Methods inherited from class checkers.source.SourceChecker
attribute, getLintOption, getLintOption, getMessages, getProcessingEnvironment, getShouldSkip, getSupportedAnnotationTypes, getSupportedOptions, getSupportedSourceVersion, getSuppressWarningsKey, message, process, report, shouldSkip
 
Methods inherited from class javax.annotation.processing.AbstractProcessor
getCompletions, isInitialized
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

READONLY

protected AnnotationMirror READONLY
Supported Annotations for IGJ. Used for subtyping rules


MUTABLE

protected AnnotationMirror MUTABLE
Supported Annotations for IGJ. Used for subtyping rules


IMMUTABLE

protected AnnotationMirror IMMUTABLE
Supported Annotations for IGJ. Used for subtyping rules


I

protected AnnotationMirror I
Supported Annotations for IGJ. Used for subtyping rules


ASSIGNS_FIELDS

protected AnnotationMirror ASSIGNS_FIELDS
Supported Annotations for IGJ. Used for subtyping rules


BOTTOM_QUAL

protected AnnotationMirror BOTTOM_QUAL
Supported Annotations for IGJ. Used for subtyping rules

Constructor Detail

IGJChecker

public IGJChecker()
Method Detail

init

public void init(ProcessingEnvironment env)
Description copied from class: SourceChecker

Specified by:
init in interface Processor
Overrides:
init in class BaseTypeChecker
See Also:
AbstractProcessor.init(ProcessingEnvironment)

isAssignable

public boolean isAssignable(AnnotatedTypeMirror varType,
                            AnnotatedTypeMirror receiverType,
                            Tree varTree)
Return true if the assignment variable is an assignable field or variable, and returns false otherwise. A field is assignable if it is 1. a static field 2. marked Assignable 3. accessed through a mutable reference 4. reassigned with an AssignsFields method and owned by 'this'

Overrides:
isAssignable in class BaseTypeChecker
Parameters:
varType - the annotated variable type
varTree - tree used to access the variable
Returns:
true iff variable is assignable in the current scope

isValidUse

public boolean isValidUse(AnnotatedTypeMirror.AnnotatedDeclaredType elemType,
                          AnnotatedTypeMirror.AnnotatedDeclaredType use)
Description copied from class: BaseTypeChecker
Tests that the qualifiers present on the useType are valid qualifiers, given the qualifiers on the declaration of the type, declarationType.

The check is shallow, as it does not descend into generic or array types (i.e. only performing the validity check on the raw type or outmost array dimension). BaseTypeVisitor.validateTypeOf(Tree) would call this for each type argument or array dimention separately.

For instance, in the IGJ type system, a @Mutable is an invalid qualifier for String, as String is declared as @Immutable String.

In most cases, useType simply needs to be a subtype of declarationType, but there are exceptions. In IGJ, a variable may be declared @ReadOnly String, even though String is @Immutable String; ReadOnly is not a subtype of Immutable.

Overrides:
isValidUse in class BaseTypeChecker
Parameters:
elemType - the type of the class (TypeElement)
use - the use of the class (instance type)
Returns:
if the useType is a valid use of elemType

createQualifierHierarchy

protected QualifierHierarchy createQualifierHierarchy()
Description copied from class: BaseTypeChecker
Returns the type qualifier hierarchy graph to be used by this processor. The implementation builds the type qualifier hierarchy for the BaseTypeChecker.getSupportedTypeQualifiers() using the meta-annotations found in them. The current implementation returns an instance of GraphQualifierHierarchy. Subclasses may override this method to express any relationships that cannot be inferred using meta-annotations (e.g. due to lack of meta-annotations).

Overrides:
createQualifierHierarchy in class BaseTypeChecker
Returns:
an annotation relation tree representing the supported qualifiers

createTypeHierarchy

protected TypeHierarchy createTypeHierarchy()
Description copied from class: BaseTypeChecker
Creates the type subtyping checker using the current type qualifier hierarchy. Subclasses may override this method to specify new type checking rules beyond the typical java subtyping rules.

Overrides:
createTypeHierarchy in class BaseTypeChecker
Returns:
the type relations class to check type subtyping