org.checkerframework.framework.util

Class MultiGraphQualifierHierarchy

java.lang.Object

org.checkerframework.framework.util.MultiGraphQualifierHierarchy

All Implemented Interfaces:

QualifierHierarchy

Direct Known Subclasses:

GraphQualifierHierarchy

Deprecated.

Use ElementQualifierHierarchy, MostlyNoElementQualifierHierarchy, or NoElementQualifierHierarchy instead. This class will be removed in a future release.

Here are instructions on how to convert from a subclass of MultiGraphQualifierHierarchy to the new implementations:

If the subclass implements isSubtype and calls super when annotations do not have elements, then use the following instructions to convert to MostlyNoElementQualifierHierarchy.

1. Change extends MultiGraphQualifierHierarchy to extends MostlyNoElementQualifierHierarchy.
2. Create a constructor matching super.
3. Implement isSubtypeWithElements, leastUpperBoundWithElements, and greatestLowerBoundWithElements. You may be able to reuse parts of your current implementation of isSubtype, leastUpperBound, and greatestLowerBound.

If the subclass implements isSubtype and does not call super in that implementation, then use the following instructions to convert to a subclass of ElementQualifierHierarchy.

1. Change extends MultiGraphQualifierHierarchy to extends ElementQualifierHierarchy.
2. Create a constructor matching super.
3. Implement leastUpperBound(AnnotationMirror, AnnotationMirror) and greatestLowerBound(AnnotationMirror, AnnotationMirror) if missing. (In the past, it was very easy to forget to implement these, now they are abstract methods.)

If you wish to continue to use a subclass of MultiGraphQualifierHierarchy or GraphQualifierHierarchy, you may do so by adding the following to AnnotatedTypeFactory. (It's better to convert to one of the new classes because MultiGraphQualifierHierarchy and GraphQualifierHierarchy are buggy and no longer supported.)

If any qualifier has an annotation element without a default value, you will need to convert to one of the new subclasses. If you do not, then MultiGraphQualifierHierarchy will throw an exception with a message like "AnnotationBuilder.fromName: no value for element value() of checkers.inference.qual.VarAnnot".

  @Override
  @SuppressWarnings("deprecation")
  public QualifierHierarchy createQualifierHierarchy() {
      return org.checkerframework.framework.util.MultiGraphQualifierHierarchy
              .createMultiGraphQualifierHierarchy(this);
   }
 
  @Override
  @SuppressWarnings("deprecation")
  public QualifierHierarchy createQualifierHierarchyWithMultiGraphFactory(
          org.checkerframework.framework.util.MultiGraphQualifierHierarchy.MultiGraphFactory
                  factory) {
      return new YourSubclassQualifierHierarchy(factory);
  }
 

@Deprecated
public class MultiGraphQualifierHierarchy
extends Object
implements QualifierHierarchy

Represents the type qualifier hierarchy of a type system that supports multiple separate subtype hierarchies.

This class is immutable and can be only created through MultiGraphQualifierHierarchy.MultiGraphFactory.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MultiGraphQualifierHierarchy.MultiGraphFactory Deprecated. Use ElementQualifierHierarchy instead.

Field Summary

Fields

Modifier and Type	Field and Description
protected Set<AnnotationMirror>	bottoms Deprecated. The bottom qualifiers of the type hierarchies.
protected Map<AnnotationMirror,AnnotationMirror>	polyQualifiers Deprecated. See MultiGraphQualifierHierarchy.MultiGraphFactory.polyQualifiers.
protected Map<AnnotationMirror,Set<AnnotationMirror>>	supertypesDirect Deprecated. The declared, direct supertypes for each qualifier, without added transitive relations.
protected Map<AnnotationMirror,Set<AnnotationMirror>>	supertypesTransitive Deprecated. The transitive closure of the supertypesDirect.
protected Set<AnnotationMirror>	tops Deprecated. The top qualifiers of the individual type hierarchies.

Constructor Summary

Constructors

Constructor and Description
MultiGraphQualifierHierarchy(MultiGraphQualifierHierarchy.MultiGraphFactory f) Deprecated.
MultiGraphQualifierHierarchy(MultiGraphQualifierHierarchy.MultiGraphFactory f, Object... args) Deprecated.

Method Summary

Modifier and Type	Method and Description
protected void	addPolyRelations(QualifierHierarchy qualHierarchy, Map<AnnotationMirror,Set<AnnotationMirror>> fullMap, Map<AnnotationMirror,AnnotationMirror> polyQualifiers, Set<AnnotationMirror> tops, Set<AnnotationMirror> bottoms) Deprecated. Add the relationships for polymorphic qualifiers.
static QualifierHierarchy	createMultiGraphQualifierHierarchy(AnnotatedTypeFactory annotatedTypeFactory) Deprecated. Use ElementQualifierHierarchy instead.
protected Set<AnnotationMirror>	findBottoms(Map<AnnotationMirror,Set<AnnotationMirror>> supertypes) Deprecated. Infer the bottoms of the subtype hierarchy.
protected AnnotationMirror	findLub(AnnotationMirror a1, AnnotationMirror a2) Deprecated. Finds and returns the Least Upper Bound (LUB) of two annotation mirrors a1 and a2 by recursively climbing the qualifier hierarchy of a1 until one of them is a subtype of the other, or returns null if no subtype relationships can be found.
protected Set<AnnotationMirror>	findTops(Map<AnnotationMirror,Set<AnnotationMirror>> supertypes) Deprecated. Infer the tops of the subtype hierarchy.
protected void	finish(QualifierHierarchy qualHierarchy, Map<AnnotationMirror,Set<AnnotationMirror>> supertypesTransitive, Map<AnnotationMirror,AnnotationMirror> polyQualifiers, Set<AnnotationMirror> tops, Set<AnnotationMirror> bottoms, Object... args) Deprecated. Method to finalize the qualifier hierarchy before it becomes unmodifiable.
AnnotationMirror	getBottomAnnotation(AnnotationMirror start) Deprecated. Return the bottom for the given qualifier, that is, the qualifier that is a subtype of qualifier but no further subtypes exist.
Set<? extends AnnotationMirror>	getBottomAnnotations() Deprecated. Returns the bottom type qualifiers in the hierarchy.
AnnotationMirror	getPolymorphicAnnotation(AnnotationMirror start) Deprecated. Returns the polymorphic qualifier for the hierarchy containing qualifier, or null if there is no polymorphic qualifier in that hierarchy.
AnnotationMirror	getTopAnnotation(AnnotationMirror start) Deprecated. Return the top qualifier for the given qualifier, that is, the qualifier that is a supertype of qualifier but no further supertypes exist.
Set<? extends AnnotationMirror>	getTopAnnotations() Deprecated. Returns the top (ultimate super) type qualifiers in the type system.
AnnotationMirror	greatestLowerBound(AnnotationMirror a1, AnnotationMirror a2) Deprecated. Returns the greatest lower bound for the qualifiers qualifier1 and qualifier2.
boolean	isPolymorphicQualifier(AnnotationMirror qual) Deprecated. Returns true if the qualifier is a polymorphic qualifier; otherwise, returns false.
boolean	isSubtype(AnnotationMirror subAnno, AnnotationMirror superAnno) Deprecated. Tests whether subQualifier is equal to or a sub-qualifier of superQualifier, according to the type qualifier hierarchy.
boolean	isSubtype(Collection<? extends AnnotationMirror> rhs, Collection<? extends AnnotationMirror> lhs) Deprecated. Tests whether all qualifiers in subQualifiers are a subqualifier or equal to the qualifier in the same hierarchy in superQualifiers.
boolean	isValid() Deprecated. Determine whether this is valid.
AnnotationMirror	leastUpperBound(AnnotationMirror a1, AnnotationMirror a2) Deprecated. Returns the least upper bound (LUB) of the qualifiers qualifier1 and qualifier2.
String	toString() Deprecated.
protected Map<AnnotationMirror,Set<AnnotationMirror>>	transitiveClosure(Map<AnnotationMirror,Set<AnnotationMirror>> supertypes) Deprecated. Computes the transitive closure of the given map and returns it.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.checkerframework.framework.type.QualifierHierarchy

assertSameSize, assertSameSize, canHaveEmptyAnnotationSet, findAnnotationInHierarchy, findAnnotationInSameHierarchy, getWidth, greatestLowerBound, greatestLowerBounds, greatestLowerBounds, greatestLowerBoundsTypeVariable, greatestLowerBoundTypeVariable, isSubtype, isSubtype, isSubtypeTypeVariable, isSubtypeTypeVariable, leastUpperBound, leastUpperBounds, leastUpperBounds, leastUpperBoundsTypeVariable, leastUpperBoundTypeVariable, numberOfIterationsBeforeWidening, updateMappingToMutableSet, widenedUpperBound

Field Detail

supertypesDirect

protected final Map<AnnotationMirror,Set<AnnotationMirror>> supertypesDirect

Deprecated.

The declared, direct supertypes for each qualifier, without added transitive relations. Immutable after construction finishes. No polymorphic qualifiers are contained in this map.

See Also:

MultiGraphQualifierHierarchy.MultiGraphFactory.supertypesDirect

supertypesTransitive

protected final Map<AnnotationMirror,Set<AnnotationMirror>> supertypesTransitive

Deprecated.

The transitive closure of the supertypesDirect. Immutable after construction finishes.

tops

protected final Set<AnnotationMirror> tops

Deprecated.

The top qualifiers of the individual type hierarchies.

bottoms

protected final Set<AnnotationMirror> bottoms

Deprecated.

The bottom qualifiers of the type hierarchies. TODO: clarify relation to tops.

polyQualifiers

protected final Map<AnnotationMirror,AnnotationMirror> polyQualifiers

Deprecated.

See MultiGraphQualifierHierarchy.MultiGraphFactory.polyQualifiers.

See Also:

MultiGraphQualifierHierarchy.MultiGraphFactory.polyQualifiers

Constructor Detail

MultiGraphQualifierHierarchy

public MultiGraphQualifierHierarchy(MultiGraphQualifierHierarchy.MultiGraphFactory f)

Deprecated.

MultiGraphQualifierHierarchy

public MultiGraphQualifierHierarchy(MultiGraphQualifierHierarchy.MultiGraphFactory f,
                                    Object... args)

Deprecated.

Method Detail

createMultiGraphQualifierHierarchy

@Deprecated
public static QualifierHierarchy createMultiGraphQualifierHierarchy(AnnotatedTypeFactory annotatedTypeFactory)

Deprecated. Use ElementQualifierHierarchy instead.

Creates the QualifierHierarchy using MultiGraphQualifierHierarchy

Parameters:

annotatedTypeFactory - annotated type factory

Returns:

qualifier hierarchy

isValid

public boolean isValid()

Deprecated.

Description copied from interface: QualifierHierarchy

Determine whether this is valid.

Specified by:

isValid in interface QualifierHierarchy

Returns:

whether this is valid

finish

protected void finish(QualifierHierarchy qualHierarchy,
                      Map<AnnotationMirror,Set<AnnotationMirror>> supertypesTransitive,
                      Map<AnnotationMirror,AnnotationMirror> polyQualifiers,
                      Set<AnnotationMirror> tops,
                      Set<AnnotationMirror> bottoms,
                      Object... args)

Deprecated.

Method to finalize the qualifier hierarchy before it becomes unmodifiable. The parameters pass all fields and allow modification.

toString

@SideEffectFree
public String toString()

Deprecated.

Overrides:

toString in class Object

getTopAnnotations

public Set<? extends AnnotationMirror> getTopAnnotations()

Deprecated.

Description copied from interface: QualifierHierarchy

Returns the top (ultimate super) type qualifiers in the type system. The size of this set is equal to QualifierHierarchy.getWidth().

Specified by:

getTopAnnotations in interface QualifierHierarchy

Returns:

the top (ultimate super) type qualifiers in the type system

getTopAnnotation

public AnnotationMirror getTopAnnotation(AnnotationMirror start)

Deprecated.

Description copied from interface: QualifierHierarchy

Return the top qualifier for the given qualifier, that is, the qualifier that is a supertype of qualifier but no further supertypes exist.

Specified by:

getTopAnnotation in interface QualifierHierarchy

Parameters:

start - any qualifier from one of the qualifier hierarchies represented by this

Returns:

the top qualifier of qualifier's hierarchy

getBottomAnnotations

public Set<? extends AnnotationMirror> getBottomAnnotations()

Deprecated.

Description copied from interface: QualifierHierarchy

Returns the bottom type qualifiers in the hierarchy. The size of this set is equal to QualifierHierarchy.getWidth().

Specified by:

getBottomAnnotations in interface QualifierHierarchy

Returns:

the bottom type qualifiers in the hierarchy

getBottomAnnotation

public AnnotationMirror getBottomAnnotation(AnnotationMirror start)

Deprecated.

Description copied from interface: QualifierHierarchy

Return the bottom for the given qualifier, that is, the qualifier that is a subtype of qualifier but no further subtypes exist.

Specified by:

getBottomAnnotation in interface QualifierHierarchy

Parameters:

start - any qualifier from one of the qualifier hierarchies represented by this

Returns:

the bottom qualifier of qualifier's hierarchy

getPolymorphicAnnotation

public AnnotationMirror getPolymorphicAnnotation(AnnotationMirror start)

Deprecated.

Description copied from interface: QualifierHierarchy

Returns the polymorphic qualifier for the hierarchy containing qualifier, or null if there is no polymorphic qualifier in that hierarchy.

Specified by:

getPolymorphicAnnotation in interface QualifierHierarchy

Parameters:

start - any qualifier from one of the qualifier hierarchies represented by this

Returns:

the polymorphic qualifier for the hierarchy containing qualifier, or null if there is no polymorphic qualifier in that hierarchy

isSubtype

public boolean isSubtype(Collection<? extends AnnotationMirror> rhs,
                         Collection<? extends AnnotationMirror> lhs)

Deprecated.

Description copied from interface: QualifierHierarchy

Tests whether all qualifiers in subQualifiers are a subqualifier or equal to the qualifier in the same hierarchy in superQualifiers.

Specified by:

isSubtype in interface QualifierHierarchy

Parameters:

rhs - set of qualifiers; exactly one per hierarchy

lhs - set of qualifiers; exactly one per hierarchy

Returns:

true iff all qualifiers in subQualifiers are a subqualifier or equal to the qualifier in the same hierarchy in superQualifiers

leastUpperBound

public AnnotationMirror leastUpperBound(AnnotationMirror a1,
                                        AnnotationMirror a2)

Deprecated.

Description copied from interface: QualifierHierarchy

Returns the least upper bound (LUB) of the qualifiers qualifier1 and qualifier2. Returns null if the qualifiers are not from the same qualifier hierarchy.

Examples:

• For NonNull, leastUpperBound('Nullable', 'NonNull') ⇒ Nullable

Specified by:

leastUpperBound in interface QualifierHierarchy

Parameters:

a1 - the first qualifier; may not be in the same hierarchy as qualifier2

a2 - the second qualifier; may not be in the same hierarchy as qualifier1

Returns:

the least upper bound of the qualifiers, or null if the qualifiers are from different hierarchies

greatestLowerBound

public AnnotationMirror greatestLowerBound(AnnotationMirror a1,
                                           AnnotationMirror a2)

Deprecated.

Description copied from interface: QualifierHierarchy

Returns the greatest lower bound for the qualifiers qualifier1 and qualifier2. Returns null if the qualifiers are not from the same qualifier hierarchy.

Specified by:

greatestLowerBound in interface QualifierHierarchy

Parameters:

a1 - first qualifier

a2 - second qualifier

Returns:

greatest lower bound of the two annotations or null if the two annotations are not from the same hierarchy

isSubtype

public boolean isSubtype(AnnotationMirror subAnno,
                         AnnotationMirror superAnno)

Deprecated.

Tests whether subQualifier is equal to or a sub-qualifier of superQualifier, according to the type qualifier hierarchy.

Most qualifiers have no value fields. However, two annotations with values are subtype of each other only if they have the same values. i.e. I(m) is a subtype of I(n) iff m = n.

When client specifies an annotation, a1, to be a subtype of annotation with values, a2, then a1 is a subtype of all instances of a2 regardless of a2 values.

Specified by:

isSubtype in interface QualifierHierarchy

Parameters:

subAnno - the sub qualifier

superAnno - the super qualifier

Returns:

true iff subQualifier is a subqualifier of, or equal to, superQualifier

findTops

protected Set<AnnotationMirror> findTops(Map<AnnotationMirror,Set<AnnotationMirror>> supertypes)

Deprecated.

Infer the tops of the subtype hierarchy. Simply finds the qualifiers that have no supertypes.

findBottoms

protected Set<AnnotationMirror> findBottoms(Map<AnnotationMirror,Set<AnnotationMirror>> supertypes)

Deprecated.

Infer the bottoms of the subtype hierarchy. Simple finds the qualifiers that are not supertypes of other qualifiers.

transitiveClosure

protected Map<AnnotationMirror,Set<AnnotationMirror>> transitiveClosure(Map<AnnotationMirror,Set<AnnotationMirror>> supertypes)

Deprecated.

Computes the transitive closure of the given map and returns it.

addPolyRelations

protected void addPolyRelations(QualifierHierarchy qualHierarchy,
                                Map<AnnotationMirror,Set<AnnotationMirror>> fullMap,
                                Map<AnnotationMirror,AnnotationMirror> polyQualifiers,
                                Set<AnnotationMirror> tops,
                                Set<AnnotationMirror> bottoms)

Deprecated.

Add the relationships for polymorphic qualifiers.

A polymorphic qualifier, such as PolyNull, needs to be:

1. a subtype of the top qualifier (e.g. Nullable)
2. a supertype of all the bottom qualifiers (e.g. NonNull)

Field supertypesTransitive is not set yet when this method is called -- use parameter fullMap instead.

findLub

protected AnnotationMirror findLub(AnnotationMirror a1,
                                   AnnotationMirror a2)

Deprecated.

Finds and returns the Least Upper Bound (LUB) of two annotation mirrors a1 and a2 by recursively climbing the qualifier hierarchy of a1 until one of them is a subtype of the other, or returns null if no subtype relationships can be found.

Parameters:

a1 - first annotation mirror

a2 - second annotation mirror

Returns:

the LUB of a1 and a2, or null if none can be found

isPolymorphicQualifier

public boolean isPolymorphicQualifier(AnnotationMirror qual)

Deprecated.

Description copied from interface: QualifierHierarchy

Returns true if the qualifier is a polymorphic qualifier; otherwise, returns false.

Specified by:

isPolymorphicQualifier in interface QualifierHierarchy

Parameters:

qual - qualifier

Returns:

true if the qualifier is a polymorphic qualifier; otherwise, returns false.