checkers.igj
Class IGJChecker

java.lang.Object
  javax.annotation.processing.AbstractProcessor
      com.sun.source.util.AbstractTypeProcessor
          checkers.source.SourceChecker
              checkers.basetype.BaseTypeChecker
                  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 Checker Framework manual:

IGJ Checker

Field Summary

Modifier and Type	Field and Description
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

currentPath, currentRoot, env, messager, messages, trees

Fields inherited from class javax.annotation.processing.AbstractProcessor

processingEnv

Constructor and Description

IGJChecker()

Method Summary

Modifier and Type	Method and Description
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

fullMessageOf, getLintOption, getLintOption, getMessages, getProcessingEnvironment, getShouldSkip, getSupportedAnnotationTypes, getSupportedOptions, getSupportedSourceVersion, getSuppressWarningsKey, message, report, typeProcess

Methods inherited from class com.sun.source.util.AbstractTypeProcessor

process, typeProcessingOver

Methods inherited from class javax.annotation.processing.AbstractProcessor

getCompletions, isInitialized, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, 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