org.checkerframework.common.wholeprograminference

Class WholeProgramInferenceScenesStorage

java.lang.Object

org.checkerframework.common.wholeprograminference.WholeProgramInferenceScenesStorage

All Implemented Interfaces:

WholeProgramInferenceStorage<scenelib.annotations.el.ATypeElement>

public class WholeProgramInferenceScenesStorage
extends Object
implements WholeProgramInferenceStorage<scenelib.annotations.el.ATypeElement>

This class stores annotations using scenelib objects.

The set of annotations inferred for a certain class is stored in an AScene, which writeScenes() can write into a file. For example, a class my.pakkage.MyClass will have its members' inferred types stored in a Scene, and later written into a file named my.pakkage.MyClass.jaif if using WholeProgramInference.OutputFormat.JAIF, or my.pakkage.MyClass.astub if using WholeProgramInference.OutputFormat.STUB.

This class populates the initial Scenes by reading existing .jaif files on the JAIF_FILES_PATH directory (regardless of output format). Having more information in those initial .jaif files means that the precision achieved by the whole-program inference analysis will be better. writeScenes(org.checkerframework.common.wholeprograminference.WholeProgramInference.OutputFormat, org.checkerframework.common.basetype.BaseTypeChecker) rewrites the initial .jaif files and may create new ones.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	WholeProgramInferenceScenesStorage.AnnotationsInContexts Maps the aTypeElementToString(scenelib.annotations.el.ATypeElement) representation of an ATypeElement and its TypeUseLocation to a set of names of annotations.

Field Summary

Fields

Modifier and Type	Field and Description
protected AnnotatedTypeFactory	atypeFactory The type factory associated with this WholeProgramInferenceScenesStorage.
static String	JAIF_FILES_PATH Directory where .jaif files will be written to and read from.
Set<String>	modifiedScenes Scenes that were modified since the last time all Scenes were written into .jaif files.
Map<String,ASceneWrapper>	scenes Maps .jaif file paths (Strings) to Scenes.

Constructor Summary

Constructors

Constructor and Description
WholeProgramInferenceScenesStorage(AnnotatedTypeFactory atypeFactory) Default constructor.

Method Summary

Modifier and Type	Method and Description
boolean	addMethodDeclarationAnnotation(ExecutableElement methodElt, AnnotationMirror anno) Updates a method to add a declaration annotation.
AnnotatedTypeMirror	atmFromStorageLocation(TypeMirror typeMirror, scenelib.annotations.el.ATypeElement storageLocation) Obtain the type from a storage location.
static String	aTypeElementToString(scenelib.annotations.el.ATypeElement aType) Returns a string representation of an ATypeElement, for use as part of a key in WholeProgramInferenceScenesStorage.AnnotationsInContexts.
protected scenelib.annotations.el.AClass	getAClass(@BinaryName String className, String jaifPath) Returns the scene-lib representation of the given className in the scene identified by the given jaifPath.
protected scenelib.annotations.el.AClass	getAClass(@BinaryName String className, String jaifPath, @Nullable com.sun.tools.javac.code.Symbol.ClassSymbol classSymbol) Returns the scene-lib representation of the given className in the scene identified by the given jaifPath.
scenelib.annotations.el.ATypeElement	getFieldAnnotations(Element element, String fieldName, AnnotatedTypeMirror lhsATM, AnnotatedTypeFactory atypeFactory) Get the annotations for a field type.
String	getFileForElement(Element elt) Returns the file corresponding to the given element.
protected String	getJaifPath(String className) Returns the String representing the .jaif path of a class given its name.
scenelib.annotations.el.ATypeElement	getParameterAnnotations(ExecutableElement methodElt, int i, AnnotatedTypeMirror paramATM, VariableElement ve, AnnotatedTypeFactory atypeFactory) Get the annotations for a formal parameter type.
AnnotatedTypeMirror	getPostconditionDeclaredType(scenelib.annotations.el.AMethod m, String expression) Fetches the declared type of an expression for which a postcondition was inferred, for the given AMethod.
AnnotatedTypeMirror	getPreconditionDeclaredType(scenelib.annotations.el.AMethod m, String expression) Fetches the declared type of an expression for which a precondition was inferred, for the given AMethod.
scenelib.annotations.el.ATypeElement	getPreOrPostconditions(Analysis.BeforeOrAfter preOrPost, ExecutableElement methodElement, String expression, AnnotatedTypeMirror declaredType, AnnotatedTypeFactory atypeFactory) Returns the pre- or postcondition annotations for an expression.
scenelib.annotations.el.ATypeElement	getReceiverAnnotations(ExecutableElement methodElt, AnnotatedTypeMirror paramATM, AnnotatedTypeFactory atypeFactory) Get the annotations for the receiver type.
scenelib.annotations.el.ATypeElement	getReturnAnnotations(ExecutableElement methodElt, AnnotatedTypeMirror atm, AnnotatedTypeFactory atypeFactory) Get the annotations for the return type.
boolean	hasStorageLocationForMethod(ExecutableElement methodElt) Given an ExecutableElement in a compilation unit that has already been read into storage, returns whether there exists a stored method matching elt.
void	prepareClassForWriting(scenelib.annotations.el.AClass classAnnos) Side-effects the class annotations to make any desired changes before writing to a file.
void	prepareMethodForWriting(scenelib.annotations.el.AMethod methodAnnos) Side-effects the method or constructor annotations to make any desired changes before writing to a file.
void	prepareSceneForWriting(scenelib.annotations.el.AScene compilationUnitAnnos) Side-effects the compilation unit annotations to make any desired changes before writing to a file.
void	preprocessClassTree(ClassTree classTree) Performs any preparation required for inference on the elements of a class.
void	setFileModified(String path) Indicates that inferred annotations for the file at path have changed since last written.
protected void	updateAnnotationSetInScene(scenelib.annotations.el.ATypeElement type, TypeUseLocation defLoc, AnnotatedTypeMirror rhsATM, AnnotatedTypeMirror lhsATM, String jaifPath, boolean ignoreIfAnnotated) Updates the set of annotations in a location of a Scene, as the result of a pseudo-assignment.
void	updateStorageLocationFromAtm(AnnotatedTypeMirror newATM, AnnotatedTypeMirror curATM, scenelib.annotations.el.ATypeElement typeToUpdate, TypeUseLocation defLoc, boolean ignoreIfAnnotated) Updates a storage location to have the annotations of the given AnnotatedTypeMirror.
void	writeResultsToFile(WholeProgramInference.OutputFormat outputFormat, BaseTypeChecker checker) Writes the inferred results to a file.
void	writeScenes(WholeProgramInference.OutputFormat outputFormat, BaseTypeChecker checker) Write all modified scenes into files.

Methods inherited from class java.lang.Object

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

Field Detail

JAIF_FILES_PATH

public static final String JAIF_FILES_PATH

Directory where .jaif files will be written to and read from. This directory is relative to where the CF's javac command is executed.

atypeFactory

protected final AnnotatedTypeFactory atypeFactory

The type factory associated with this WholeProgramInferenceScenesStorage.

scenes

public final Map<String,ASceneWrapper> scenes

Maps .jaif file paths (Strings) to Scenes. Relative to JAIF_FILES_PATH.

modifiedScenes

public final Set<String> modifiedScenes

Scenes that were modified since the last time all Scenes were written into .jaif files. Each String element of this set is a path (relative to JAIF_FILES_PATH) to the .jaif file of the corresponding Scene in the set. It is obtained by passing a class name as argument to the getJaifPath(java.lang.String) method.

Modifying a Scene means adding (or changing) a type annotation for a field, method return type, or method parameter type in the Scene. (Scenes are modified by the method updateAnnotationSetInScene(scenelib.annotations.el.ATypeElement, org.checkerframework.framework.qual.TypeUseLocation, org.checkerframework.framework.type.AnnotatedTypeMirror, org.checkerframework.framework.type.AnnotatedTypeMirror, java.lang.String, boolean).)

Constructor Detail

WholeProgramInferenceScenesStorage

public WholeProgramInferenceScenesStorage(AnnotatedTypeFactory atypeFactory)

Default constructor.

Parameters:

atypeFactory - the type factory associated with this WholeProgramInferenceScenesStorage

Method Detail

getFileForElement

public String getFileForElement(Element elt)

Description copied from interface: WholeProgramInferenceStorage

Returns the file corresponding to the given element. This may side-effect the storage to load the file if it hasn't been read yet.

Specified by:

getFileForElement in interface WholeProgramInferenceStorage<scenelib.annotations.el.ATypeElement>

Parameters:

elt - an element

Returns:

the path to the file where inference results for the element will be written

hasStorageLocationForMethod

public boolean hasStorageLocationForMethod(ExecutableElement methodElt)

Description copied from interface: WholeProgramInferenceStorage

Given an ExecutableElement in a compilation unit that has already been read into storage, returns whether there exists a stored method matching elt.

An implementation is permitted to return false if elt represents a method that was synthetically added by javac, such as zero-argument constructors or valueOf(String) methods for enum types.

Specified by:

hasStorageLocationForMethod in interface WholeProgramInferenceStorage<scenelib.annotations.el.ATypeElement>

Parameters:

methodElt - a method or constructor Element

Returns:

true if the storage has a method corresponding to elt

getParameterAnnotations

public scenelib.annotations.el.ATypeElement getParameterAnnotations(ExecutableElement methodElt,
                                                                    int i,
                                                                    AnnotatedTypeMirror paramATM,
                                                                    VariableElement ve,
                                                                    AnnotatedTypeFactory atypeFactory)

Description copied from interface: WholeProgramInferenceStorage

Get the annotations for a formal parameter type.

Specified by:

getParameterAnnotations in interface WholeProgramInferenceStorage<scenelib.annotations.el.ATypeElement>

Parameters:

methodElt - the method or constructor Element

i - the parameter index (0-based)

paramATM - the parameter type

ve - the parameter variable

atypeFactory - the type factory

Returns:

the annotations for a formal parameter type

getReceiverAnnotations

public scenelib.annotations.el.ATypeElement getReceiverAnnotations(ExecutableElement methodElt,
                                                                   AnnotatedTypeMirror paramATM,
                                                                   AnnotatedTypeFactory atypeFactory)

Description copied from interface: WholeProgramInferenceStorage

Get the annotations for the receiver type.

Specified by:

getReceiverAnnotations in interface WholeProgramInferenceStorage<scenelib.annotations.el.ATypeElement>

Parameters:

methodElt - the method or constructor Element

paramATM - the receiver type

atypeFactory - the type factory

Returns:

the annotations for the receiver type

getReturnAnnotations

public scenelib.annotations.el.ATypeElement getReturnAnnotations(ExecutableElement methodElt,
                                                                 AnnotatedTypeMirror atm,
                                                                 AnnotatedTypeFactory atypeFactory)

Description copied from interface: WholeProgramInferenceStorage

Get the annotations for the return type.

Specified by:

getReturnAnnotations in interface WholeProgramInferenceStorage<scenelib.annotations.el.ATypeElement>

Parameters:

methodElt - the method or constructor Element

atm - the return type

atypeFactory - the type factory

Returns:

the annotations for the return type

getFieldAnnotations

public scenelib.annotations.el.ATypeElement getFieldAnnotations(Element element,
                                                                String fieldName,
                                                                AnnotatedTypeMirror lhsATM,
                                                                AnnotatedTypeFactory atypeFactory)

Description copied from interface: WholeProgramInferenceStorage

Get the annotations for a field type.

Specified by:

getFieldAnnotations in interface WholeProgramInferenceStorage<scenelib.annotations.el.ATypeElement>

Parameters:

element - the element for the field

fieldName - the simple field name

lhsATM - the field type

atypeFactory - the annotated type factory

Returns:

the annotations for a field type

getPreOrPostconditions

public scenelib.annotations.el.ATypeElement getPreOrPostconditions(Analysis.BeforeOrAfter preOrPost,
                                                                   ExecutableElement methodElement,
                                                                   String expression,
                                                                   AnnotatedTypeMirror declaredType,
                                                                   AnnotatedTypeFactory atypeFactory)

Description copied from interface: WholeProgramInferenceStorage

Returns the pre- or postcondition annotations for an expression. The format of the expression is the same as a programmer would write in a RequiresQualifier or EnsuresQualifier annotation.

This method may return null if the given expression is not a supported expression type. Currently, the supported expression types are: fields of "this" (e.g. "this.f", pre- and postconditions), "this" (postconditions only), and method parameters (e.g. "#1", "#2", postconditions only).

Specified by:

getPreOrPostconditions in interface WholeProgramInferenceStorage<scenelib.annotations.el.ATypeElement>

Parameters:

preOrPost - whether to get the precondition or postcondition

methodElement - the method

expression - the expression

declaredType - the declared type of the expression

atypeFactory - the type factory

Returns:

the pre- or postcondition annotations for an expression, or null if the given expression is not a supported expression type

getPreconditionDeclaredType

public AnnotatedTypeMirror getPreconditionDeclaredType(scenelib.annotations.el.AMethod m,
                                                       String expression)

Fetches the declared type of an expression for which a precondition was inferred, for the given AMethod.

Parameters:

m - a method

expression - the expression

Returns:

the declared type

getPostconditionDeclaredType

public AnnotatedTypeMirror getPostconditionDeclaredType(scenelib.annotations.el.AMethod m,
                                                        String expression)

Fetches the declared type of an expression for which a postcondition was inferred, for the given AMethod.

Parameters:

m - a method

expression - the expression

Returns:

the declared type

addMethodDeclarationAnnotation

public boolean addMethodDeclarationAnnotation(ExecutableElement methodElt,
                                              AnnotationMirror anno)

Description copied from interface: WholeProgramInferenceStorage

Updates a method to add a declaration annotation.

Specified by:

addMethodDeclarationAnnotation in interface WholeProgramInferenceStorage<scenelib.annotations.el.ATypeElement>

Parameters:

methodElt - the method to annotate

anno - the declaration annotation to add to the method

Returns:

true if anno is a new declaration annotation for methodElt, false otherwise

writeScenes

public void writeScenes(WholeProgramInference.OutputFormat outputFormat,
                        BaseTypeChecker checker)

Write all modified scenes into files. (Scenes are modified by the method updateAnnotationSetInScene(scenelib.annotations.el.ATypeElement, org.checkerframework.framework.qual.TypeUseLocation, org.checkerframework.framework.type.AnnotatedTypeMirror, org.checkerframework.framework.type.AnnotatedTypeMirror, java.lang.String, boolean).)

Parameters:

outputFormat - the output format to use when writing files

checker - the checker from which this method is called, for naming stub files

getJaifPath

protected String getJaifPath(String className)

Returns the String representing the .jaif path of a class given its name.

Parameters:

className - the simple name of a class

Returns:

the path to the .jaif file

getAClass

protected scenelib.annotations.el.AClass getAClass(@BinaryName String className,
                                                   String jaifPath,
                                                   @Nullable com.sun.tools.javac.code.Symbol.ClassSymbol classSymbol)

Returns the scene-lib representation of the given className in the scene identified by the given jaifPath.

Parameters:

className - the name of the class to get, in binary form

jaifPath - the path to the jaif file that would represent that class (must end in ".jaif")

classSymbol - optionally, the ClassSymbol representing the class. Used to set the symbol information stored on an AClass.

Returns:

a version of the scene-lib representation of the class, augmented with symbol information if classSymbol was non-null

getAClass

protected scenelib.annotations.el.AClass getAClass(@BinaryName String className,
                                                   String jaifPath)

Returns the scene-lib representation of the given className in the scene identified by the given jaifPath.

Parameters:

className - the name of the class to get, in binary form

jaifPath - the path to the jaif file that would represent that class (must end in ".jaif")

Returns:

the scene-lib representation of the class, possibly augmented with symbol information if getAClass(String, String, com.sun.tools.javac.code.Symbol.ClassSymbol) has already been called with a non-null third argument

updateAnnotationSetInScene

protected void updateAnnotationSetInScene(scenelib.annotations.el.ATypeElement type,
                                          TypeUseLocation defLoc,
                                          AnnotatedTypeMirror rhsATM,
                                          AnnotatedTypeMirror lhsATM,
                                          String jaifPath,
                                          boolean ignoreIfAnnotated)

Updates the set of annotations in a location of a Scene, as the result of a pseudo-assignment.

• If there was no previous annotation for that location, then the updated set will be the annotations in rhsATM.
• If there was a previous annotation, the updated set will be the LUB between the previous annotation and rhsATM.

Parameters:

type - ATypeElement of the Scene which will be modified

jaifPath - path to a .jaif file for a Scene; used for marking the scene as modified (needing to be written to disk)

rhsATM - the RHS of the annotated type on the source code

lhsATM - the LHS of the annotated type on the source code

defLoc - the location where the annotation will be added

ignoreIfAnnotated - if true, don't update any type that is explicitly annotated in the source code

atmFromStorageLocation

public AnnotatedTypeMirror atmFromStorageLocation(TypeMirror typeMirror,
                                                  scenelib.annotations.el.ATypeElement storageLocation)

Description copied from interface: WholeProgramInferenceStorage

Obtain the type from a storage location.

Specified by:

atmFromStorageLocation in interface WholeProgramInferenceStorage<scenelib.annotations.el.ATypeElement>

Parameters:

typeMirror - the underlying type for the result

storageLocation - the storage location from which to obtain annotations

Returns:

an annotated type mirror with underlying type typeMirror and annotations from storageLocation

updateStorageLocationFromAtm

public void updateStorageLocationFromAtm(AnnotatedTypeMirror newATM,
                                         AnnotatedTypeMirror curATM,
                                         scenelib.annotations.el.ATypeElement typeToUpdate,
                                         TypeUseLocation defLoc,
                                         boolean ignoreIfAnnotated)

Description copied from interface: WholeProgramInferenceStorage

Updates a storage location to have the annotations of the given AnnotatedTypeMirror. Annotations in the original set that should be ignored are not added to the resulting set. If ignoreIfAnnotated is true, doesn't add annotations for locations with explicit annotations in source code.

This method removes from the storage location all annotations supported by the AnnotatedTypeFactory before inserting new ones. It is assumed that every time this method is called, the new AnnotatedTypeMirror has a better type estimate for the given location. Therefore, it is not a problem to remove all annotations before inserting the new annotations.

The update* methods in WholeProgramInference perform LUB. This one just does replacement. (Thus, the naming may be a bit confusing.)

Specified by:

updateStorageLocationFromAtm in interface WholeProgramInferenceStorage<scenelib.annotations.el.ATypeElement>

Parameters:

newATM - the type whose annotations will be added to the AnnotatedTypeMirror

curATM - the annotations currently stored at the location, used to check if the element that will be updated has explicit annotations in source code

typeToUpdate - the storage location that will be updated

defLoc - the location where the annotation will be added

ignoreIfAnnotated - if true, don't update any type that is explicitly annotated in the source code

prepareSceneForWriting

public void prepareSceneForWriting(scenelib.annotations.el.AScene compilationUnitAnnos)

Side-effects the compilation unit annotations to make any desired changes before writing to a file.

Parameters:

compilationUnitAnnos - the compilation unit annotations to modify

prepareClassForWriting

public void prepareClassForWriting(scenelib.annotations.el.AClass classAnnos)

Side-effects the class annotations to make any desired changes before writing to a file.

Parameters:

classAnnos - the class annotations to modify

prepareMethodForWriting

public void prepareMethodForWriting(scenelib.annotations.el.AMethod methodAnnos)

Side-effects the method or constructor annotations to make any desired changes before writing to a file.

Parameters:

methodAnnos - the method or constructor annotations to modify

writeResultsToFile

public void writeResultsToFile(WholeProgramInference.OutputFormat outputFormat,
                               BaseTypeChecker checker)

Description copied from interface: WholeProgramInferenceStorage

Writes the inferred results to a file. Ideally, it should be called at the end of the type-checking process. In practice, it is called after each class, because we don't know which class will be the last one in the type-checking process.

Specified by:

writeResultsToFile in interface WholeProgramInferenceStorage<scenelib.annotations.el.ATypeElement>

Parameters:

outputFormat - the file format in which to write the results

checker - the checker from which this method is called, for naming annotation files

setFileModified

public void setFileModified(String path)

Description copied from interface: WholeProgramInferenceStorage

Indicates that inferred annotations for the file at path have changed since last written. This causes output files for path to be written out next time WholeProgramInferenceStorage.writeResultsToFile(org.checkerframework.common.wholeprograminference.WholeProgramInference.OutputFormat, org.checkerframework.common.basetype.BaseTypeChecker) is called.

Specified by:

setFileModified in interface WholeProgramInferenceStorage<scenelib.annotations.el.ATypeElement>

Parameters:

path - path to the file with annotations that have been modified

preprocessClassTree

public void preprocessClassTree(ClassTree classTree)

Description copied from interface: WholeProgramInferenceStorage

Performs any preparation required for inference on the elements of a class. Should be called on each top-level class declaration in a compilation unit before processing it.

Specified by:

preprocessClassTree in interface WholeProgramInferenceStorage<scenelib.annotations.el.ATypeElement>

Parameters:

classTree - the class to preprocess

aTypeElementToString

public static String aTypeElementToString(scenelib.annotations.el.ATypeElement aType)

Returns a string representation of an ATypeElement, for use as part of a key in WholeProgramInferenceScenesStorage.AnnotationsInContexts.

Parameters:

aType - an ATypeElement to convert to a string representation

Returns:

a string representation of the argument