checkers.oigj

Class ImmutabilityAnnotatedTypeFactory

@NonNull java.lang.Object

checkers.types.AnnotatedTypeFactory

checkers.types.BasicAnnotatedTypeFactory<ImmutabilitySubchecker>

checkers.oigj.ImmutabilityAnnotatedTypeFactory

public class ImmutabilityAnnotatedTypeFactory
extends BasicAnnotatedTypeFactory<ImmutabilitySubchecker>

Adds implicit and default OIGJ annotations, only if the user does not annotate the type explicitly. The default annotations are designed to minimize the number of Immutable or ReadOnly appearing in the source code.

Implicit Annotations for literals:
Immutable - any primitive literal (e.g. integer, long, boolean, etc.)
OIGJMutabilityBottom - a null literal

However, due to the default setting being similar to the implicit annotations, there is no significant distinction between the two in implementation.

Default Annotations:

This factory will add the Immutable annotation to a type if the input is

1. (*)a primitive type,
2. a known immutable type, if the class type is annotated as Immutable

It will add the ReadOnly annotation to a type if the input is

3. a method receiver for an immutable class
4. a result of unification of different immutabilities (e.g. within Conditional Expressions)
5. supertype of a wildcard/type parameter in a class/method declaration

It will add OIGJMutabilityBottom, a special bottom annotation to a type if the input can be assigned to anything, like the following cases:

6. (*)the input is a null literal
7. (*)the input is an unannotated new array tree
8. the input is an unannotated new class tree invoking a constructor of ReadOnly or AssignsFields receiver type
9. the input is the class or interface declaration

It will add the Mutable annotation to a type if

10. any remaining unqualified types (i.e. Mutable is the default)

Implementation detail: (*) cases are handled with a meta annotation rather than in this class.

Furthermore, it resolves I annotation to the proper annotation, according to its specification (described in I javadoc).

Nested Class Summary

Nested classes/interfaces inherited from class checkers.types.AnnotatedTypeFactory

AnnotatedTypeFactory.InheritedFromClassAnnotator

Field Summary

Fields

Modifier and Type	Field and Description
protected static @ReadOnly String	IMMUTABILITY_KEY the I annotation value key

Fields inherited from class checkers.types.BasicAnnotatedTypeFactory

checker, defaults, flow, FLOW_BY_DEFAULT, poly, treeAnnotator, typeAnnotator, useFlow

Fields inherited from class checkers.types.AnnotatedTypeFactory

annotations, atypes, elements, env, fromTreeCache, qualHierarchy, root, trees, types, uid, visitorState

Constructor Summary

Constructors

Constructor and Description
ImmutabilityAnnotatedTypeFactory(ImmutabilitySubchecker checker, @Nullable CompilationUnitTree root) Constructor for IGJAnnotatedTypeFactory object.

Method Summary

Methods

Modifier and Type	Method and Description
protected Set<@Nullable AnnotationMirror>	createFlowQualifiers(ImmutabilitySubchecker checker) Returns the set of annotations to be inferred in flow analysis
protected TreeAnnotator	createTreeAnnotator(ImmutabilitySubchecker checker) Returns a TreeAnnotator that adds annotations to a type based on the contents of a tree.
protected TypeAnnotator	createTypeAnnotator(ImmutabilitySubchecker checker) Returns a TypeAnnotator that adds annotations to a type based on the content of the type itself.
protected AnnotatedTypeMirror.AnnotatedDeclaredType	getImplicitReceiverType(ExpressionTree tree) Return the implicit receiver type of an expression tree.
AnnotatedTypeMirror.AnnotatedDeclaredType	getSelfType(@Nullable Tree tree) Returns the type of field this, for the scope of this tree.
Pair<AnnotatedTypeMirror.AnnotatedExecutableType,List<@Mutable AnnotatedTypeMirror>>	methodFromUse(MethodInvocationTree tree) Resolves @I in the type of the method type base on the method invocation tree parameters.
void	postAsMemberOf(@Mutable AnnotatedTypeMirror elementType, @Mutable AnnotatedTypeMirror owner, @Nullable Element element) Resolve the instances of @I in the elementType based on owner, according to is specification.
protected void	postDirectSuperTypes(@Mutable AnnotatedTypeMirror type, List<? extends @Mutable AnnotatedTypeMirror> supertypes) Replace all instances of @I in the super types with the immutability of the current type

Methods inherited from class checkers.types.BasicAnnotatedTypeFactory

annotateImplicit, annotateImplicit, annotateImplicit, constructorFromUse, createFlow, getDefaultedAnnotatedType, postInit

Methods inherited from class checkers.types.AnnotatedTypeFactory

addAliasedAnnotation, aliasedAnnotation, annotateInheritedFromClass, canHaveAnnotatedTypeParameters, createLRUCache, declarationFromElement, fromClass, fromElement, fromElement, fromElement, fromExpression, fromMember, fromNewClass, fromTypeTree, getAnnotatedType, getAnnotatedType, getAnnotatedType, getAnnotatedType, getAnnotatedType, getAnnotatedType, getAnnotatedType, getAnnotatedType, getAnnotatedTypeFromTypeTree, getBoxedType, getCurrentClassTree, getCurrentClassType, getCurrentMethodReceiver, getDeclAnnotation, getEnclosingType, getPath, getQualifierHierarchy, getReceiverType, getUnboxedType, getVisitorState, isAnyEnclosingThisDeref, isMostEnclosingThisDeref, isSupportedQualifier, isWithinConstructor, toAnnotatedType, toString, typeVariablesFromUse, unify

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

IMMUTABILITY_KEY

protected static final @ReadOnly String IMMUTABILITY_KEY

the I annotation value key

See Also:

Constant Field Values

Constructor Detail

ImmutabilityAnnotatedTypeFactory

public ImmutabilityAnnotatedTypeFactory(ImmutabilitySubchecker checker,
                                @Nullable CompilationUnitTree root)

Constructor for IGJAnnotatedTypeFactory object.

Parameters:

checker - the checker to which this factory belongs

root - the compilation unit the annotation processor is processing currently

Method Detail

createFlowQualifiers

protected Set<@Nullable AnnotationMirror> createFlowQualifiers(ImmutabilitySubchecker checker)

Description copied from class: BasicAnnotatedTypeFactory

Returns the set of annotations to be inferred in flow analysis

Overrides:

createFlowQualifiers in class BasicAnnotatedTypeFactory<ImmutabilitySubchecker>

createTreeAnnotator

protected TreeAnnotator createTreeAnnotator(ImmutabilitySubchecker checker)

Description copied from class: BasicAnnotatedTypeFactory

Returns a TreeAnnotator that adds annotations to a type based on the contents of a tree. Subclasses may override this method to specify more appriopriate TreeAnnotator

Overrides:

createTreeAnnotator in class BasicAnnotatedTypeFactory<ImmutabilitySubchecker>

Returns:

a tree annotator

createTypeAnnotator

protected TypeAnnotator createTypeAnnotator(ImmutabilitySubchecker checker)

Description copied from class: BasicAnnotatedTypeFactory

Returns a TypeAnnotator that adds annotations to a type based on the content of the type itself.

Overrides:

createTypeAnnotator in class BasicAnnotatedTypeFactory<ImmutabilitySubchecker>

Returns:

a type annotator

getImplicitReceiverType

protected AnnotatedTypeMirror.AnnotatedDeclaredType getImplicitReceiverType(ExpressionTree tree)

Description copied from class: AnnotatedTypeFactory

Return the implicit receiver type of an expression tree. The result is null for expressions that don't have a receiver, e.g. for a local variable or method parameter access. TODO: receiver annotations on outer this. TODO: Better document the difference between getImplicitReceiverType and getSelfType?

Overrides:

getImplicitReceiverType in class AnnotatedTypeFactory

Parameters:

tree - The expression that might have an implicit receiver.

Returns:

The type of the receiver.

getSelfType

public AnnotatedTypeMirror.AnnotatedDeclaredType getSelfType(@Nullable Tree tree)

Returns the type of field this, for the scope of this tree. In IGJ, the self type is the method receiver in this scope.

Overrides:

getSelfType in class AnnotatedTypeFactory

postDirectSuperTypes

protected void postDirectSuperTypes(@Mutable AnnotatedTypeMirror type,
                        List<? extends @Mutable AnnotatedTypeMirror> supertypes)

Replace all instances of @I in the super types with the immutability of the current type

Overrides:

postDirectSuperTypes in class BasicAnnotatedTypeFactory<ImmutabilitySubchecker>

Parameters:

type - the type whose supertypes are requested

supertypes - the supertypes of type

postAsMemberOf

public void postAsMemberOf(@Mutable AnnotatedTypeMirror elementType,
                  @Mutable AnnotatedTypeMirror owner,
                  @Nullable Element element)

Resolve the instances of @I in the elementType based on owner, according to is specification.

Overrides:

postAsMemberOf in class AnnotatedTypeFactory

Parameters:

elementType - the annotated type of the element

owner - the annotated type of the receiver of the accessing tree

element - the element of the field or method

methodFromUse

public Pair<AnnotatedTypeMirror.AnnotatedExecutableType,List<@Mutable AnnotatedTypeMirror>> methodFromUse(MethodInvocationTree tree)

Resolves @I in the type of the method type base on the method invocation tree parameters. Any unresolved @Is is resolved to a place holder type. It resolves @I annotation in the following way:

• based on the tree receiver, done automatically through implicit invocation of AnnotatedTypes.asMemberOf(AnnotatedTypeMirror, Element)
• based on the invocation passed parameters
• if any yet unresolved immutability variables get resolved to a wildcard type

Overrides:

methodFromUse in class BasicAnnotatedTypeFactory<ImmutabilitySubchecker>

Parameters:

tree - the method invocation tree

Returns:

the method type being invoked with tree and the (inferred) type arguments