checkers.javari

Class JavariAnnotatedTypeFactory

@NonNull java.lang.Object

checkers.types.AnnotatedTypeFactory

checkers.javari.JavariAnnotatedTypeFactory

public class JavariAnnotatedTypeFactory
extends AnnotatedTypeFactory

Adds implicit and default Javari annotations, only if the user does not annotate the type explicitly. The default annotations are designed to minimize the need to write ReadOnly in the source code.

Implicit Annotations: All literals are implicitly treated as Mutable, including the null literal. While they are indeed immutable, this implicit type helps interfacing with non-annotated libraries.

Default Annotations:

• This factory will add the ReadOnly annotation to a type if the tree or element is
  1. a use of a known ReadOnly class (i.e. class whose declaration is annotated with ReadOnly, including a method receiver of a ReadOnly class, or
  2. the upper bound type of a type parameter declaration, or a wildcard appearing on a class or method declaration
  3. an access of a ThisMutable field using a ReadOnly reference (e.g. readOnlyRef.thisMutableField with the obvious declarations)
• This factory will add the ThisMutable annotation to a type if the input is a field of a mutable class.
• In all other cases, the Mutable annotation is inserted by default.

Nested Class Summary

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

AnnotatedTypeFactory.InheritedFromClassAnnotator

Field Summary

Fields inherited from class checkers.types.AnnotatedTypeFactory

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

Constructor Summary

Constructors

Constructor and Description
JavariAnnotatedTypeFactory(JavariChecker checker, @Nullable CompilationUnitTree root) Creates a new JavariAnnotatedTypeFactory that operates on a particular AST.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	annotateImplicit(@Nullable Element element, @Mutable AnnotatedTypeMirror type) Adds annotations to qualified types according to their provided element, as follows: 1.
protected void	annotateImplicit(Iterable<? extends @Nullable Tree> trees, Iterable<? extends @Mutable AnnotatedTypeMirror> types) Convenience method for annotating two corresponding iterables.
protected void	annotateImplicit(@Nullable Tree tree, @Mutable AnnotatedTypeMirror type) Adds implicit annotations to a qualified type, based on its tree, as follows: 1.
Pair<AnnotatedTypeMirror.AnnotatedExecutableType,List<@Mutable AnnotatedTypeMirror>>	constructorFromUse(NewClassTree tree) Determines the type of the constructed object based on the parameters passed to the constructor.
boolean	hasImmutabilityAnnotation(@Mutable AnnotatedTypeMirror type)
Pair<AnnotatedTypeMirror.AnnotatedExecutableType,List<@Mutable AnnotatedTypeMirror>>	methodFromUse(MethodInvocationTree tree) Determines the type of the invoked method based on the passed method invocation tree.
void	postAsMemberOf(@Mutable AnnotatedTypeMirror type, @Mutable AnnotatedTypeMirror owner, @Nullable Element element) We modify this callback method to replace @ThisMutable implicit annotations with the qualified supertype annotation, if the owner doesn't have a @ReadOnly annotation.
protected void	postDirectSuperTypes(@Mutable AnnotatedTypeMirror type, List<? extends @Mutable AnnotatedTypeMirror> supertypes) A callback method for the AnnotatedTypeFactory subtypes to customize directSuperTypes().
Collection<@Nullable AnnotationMirror>	unify(Collection<@Nullable AnnotationMirror> c1, Collection<@Nullable AnnotationMirror> c2) Returns a singleton collection with the most restrictive immutability annotation that is a supertype of the annotations on both collections.

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, getDefaultedAnnotatedType, getEnclosingType, getImplicitReceiverType, getPath, getQualifierHierarchy, getReceiverType, getSelfType, getUnboxedType, getVisitorState, isAnyEnclosingThisDeref, isMostEnclosingThisDeref, isSupportedQualifier, isWithinConstructor, postInit, toAnnotatedType, toString, typeVariablesFromUse

Methods inherited from class java.lang.Object

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

Constructor Detail

JavariAnnotatedTypeFactory

public JavariAnnotatedTypeFactory(JavariChecker checker,
                          @Nullable CompilationUnitTree root)

Creates a new JavariAnnotatedTypeFactory that operates on a particular AST.

Parameters:

checker - the checker to which this factory belongs

root - the AST on which this type factory operates

Method Detail

hasImmutabilityAnnotation

public boolean hasImmutabilityAnnotation(@Mutable AnnotatedTypeMirror type)

Parameters:

type - an annotated type mirror

Returns:

true iff the type is specified an immutability type other than this-mutable, false otherwise

annotateImplicit

protected void annotateImplicit(@Nullable Tree tree,
                    @Mutable AnnotatedTypeMirror type)

Adds implicit annotations to a qualified type, based on its tree, as follows:

• 1. Resolves qualified types from MemberSelectTree, inheritting from the expression to the identifier if the identifier is @ThisMutable.
• 2. Qualified class types without annotations receive the @Mutable annotation.
• 3. Qualified executable types receivers without annotations are annotated with the qualified executable type owner's annotation.
• 4. Qualified executable types parameters and return values without annotations are annotated with @Mutable.
• 5. Qualified declared types are annotated with their underlying type's element annotations.
• 6. Qualified types whose elements correspond to fields, and all its subtypes, are annotated with @ReadOnly, @Mutable or @PolyRead, according to the qualified type of this.

Overrides:

annotateImplicit in class AnnotatedTypeFactory

Parameters:

tree - an AST node

type - the type obtained from tree

annotateImplicit

protected void annotateImplicit(Iterable<? extends @Nullable Tree> trees,
                    Iterable<? extends @Mutable AnnotatedTypeMirror> types)

Convenience method for annotating two corresponding iterables. Both arguments must iterate through the same number of elements.

annotateImplicit

protected void annotateImplicit(@Nullable Element element,
                    @Mutable AnnotatedTypeMirror type)

Adds annotations to qualified types according to their provided element, as follows:

• 1. Qualified class types without annotations corresponding to class or interface elements receive the @Mutable annotation.
• 2. Unannotated receivers of qualified executable types are annotated with the qualified type owner's annotation.
• 3. Unannotated qualified declared types are annotated with their underlying type's element annotations.
• 4. Qualified types whose elements correspond to fields, and all its subtypes, are annotated with @ReadOnly or @ThisMutable, according to the supertype.

Overrides:

annotateImplicit in class AnnotatedTypeFactory

Parameters:

element - an element

type - the type obtained from elt

postDirectSuperTypes

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

Description copied from class: AnnotatedTypeFactory

A callback method for the AnnotatedTypeFactory subtypes to customize directSuperTypes(). Overriding methods should merely change the annotations on the supertypes, without adding or removing new types. The default provided implementation adds type annotations to supertypes. This allows the type and its supertypes to have the qualifiers, e.g. the supertypes of an Immutable type are also Immutable.

Overrides:

postDirectSuperTypes in class AnnotatedTypeFactory

Parameters:

type - the type whose supertypes are desired

supertypes - the supertypes as specified by the base AnnotatedTypeFactory

unify

public Collection<@Nullable AnnotationMirror> unify(Collection<@Nullable AnnotationMirror> c1,
                                           Collection<@Nullable AnnotationMirror> c2)

Returns a singleton collection with the most restrictive immutability annotation that is a supertype of the annotations on both collections.

Overrides:

unify in class AnnotatedTypeFactory

Parameters:

c1 - type qualifiers for the first type

c2 - type qualifiers for the second type

Returns:

the least restrictive qualifiers for both types

constructorFromUse

public Pair<AnnotatedTypeMirror.AnnotatedExecutableType,List<@Mutable AnnotatedTypeMirror>> constructorFromUse(NewClassTree tree)

Determines the type of the constructed object based on the parameters passed to the constructor. The new object has the same mutability as the annotation marked on the constructor receiver, as resolved by this method. @PolyRead receiver values are resolved by looking at the mutability of any parameters marked as @PolyRead. The rules are similar to the ones applicable to method invocation resolution, but without looking at this.

• 1. If all parameters marked as @PolyRead receive @Mutable arguments, the receiver value is resolved as @Mutable.
• 2. If all parameters marked as @PolyRead receive @Mutable or @ThisMutable arguments and the condition above is not satisfied, the receiver value is resolved as @ThisMutable.
• 3. If all parameters marked as @PolyRead receive @Mutable or @PolyRead arguments and none of the condition above is satisfied, the receiver value is resolved as @PolyRead.
• 4. If none of the conditions above is satisfied, the receiver value is resolved as @ReadOnly.

Overrides:

constructorFromUse in class AnnotatedTypeFactory

Parameters:

tree - the new class tree

Returns:

AnnotatedExecutableType corresponding to the type being constructed, with the resolved type on its receiver.

methodFromUse

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

Determines the type of the invoked method based on the passed method invocation tree. Invokes the super method, then resolves annotations @PolyRead at the raw level on return values by looking at the mutability of any parameters marked as @PolyRead. For this purpose, a @PolyRead annotation on the receiver counts as if this were being passed as an argument to a parameter marked as @PolyRead.

• 1. If all parameters marked as @PolyRead receive @Mutable arguments, the return value is resolved as @Mutable.
• 2. If all parameters marked as @PolyRead receive @Mutable or @ThisMutable arguments and the condition above is not satisfied, the return value is resolved as @ThisMutable.
• 3. If all parameters marked as @PolyRead receive @Mutable or @PolyRead arguments and none of the condition above is satisfied, the return value is resolved as @PolyRead.
• 4. If none of the conditions above is satisfied, the return value is resolved as @ReadOnly.

Overrides:

methodFromUse in class AnnotatedTypeFactory

Parameters:

tree - the method invocation tree

Returns:

AnnotatedExecutableType with return value resolved as described.

postAsMemberOf

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

We modify this callback method to replace @ThisMutable implicit annotations with the qualified supertype annotation, if the owner doesn't have a @ReadOnly annotation.

Note on the given example that, if @ThisMutable tmObject were resolved as @ReadOnly tmObject, the code snippet would be legal. Such a class could then be created to obtain @Mutable access to tmObject from a @ReadOnly reference to it, without typechecker errors.

@PolyRead Object breakJavari(@ReadOnly MyClass this, @PolyRead Object s) {
   tmObject = s;
   return null;
  }
 

Overrides:

postAsMemberOf in class AnnotatedTypeFactory

Parameters:

type - 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