org.checkerframework.framework.type.MostlyNoElementQualifierHierarchy Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of checker Show documentation
The Checker Framework enhances Java's type system to make it more powerful and useful. This lets software developers detect and prevent errors in their Java programs. The Checker Framework includes compiler plug-ins ("checkers") that find bugs or verify their absence. It also permits you to write your own compiler plug-ins.
There is a newer version: 3.44.0
Show newest version
package org.checkerframework.framework.type;

import java.lang.annotation.Annotation;
import java.util.Collection;
import javax.lang.model.element.AnnotationMirror;
import javax.lang.model.util.Elements;
import org.checkerframework.checker.nullness.qual.Nullable;
import org.checkerframework.framework.qual.AnnotatedFor;
import org.checkerframework.framework.util.QualifierKind;
import org.checkerframework.framework.util.QualifierKindHierarchy;

/**
 * A {@link org.checkerframework.framework.type.QualifierHierarchy} where qualifiers may be
 * represented by annotations with elements, but most of the qualifiers do not have elements. In
 * contrast to {@link org.checkerframework.framework.type.ElementQualifierHierarchy}, this class
 * partially implements {@link #isSubtype(AnnotationMirror, AnnotationMirror)}, {@link
 * #leastUpperBound(AnnotationMirror, AnnotationMirror)}, and {@link
 * #greatestLowerBound(AnnotationMirror, AnnotationMirror)} and calls *WithElements when the result
 * cannot be computed from the meta-annotations {@link
 * org.checkerframework.framework.qual.SubtypeOf}.
 *
 * Subclasses must implement the following methods when annotations have elements:
 *
 * 

 *   {@link #isSubtypeWithElements(AnnotationMirror, QualifierKind, AnnotationMirror,
 *       QualifierKind)}
 *   
{@link #leastUpperBoundWithElements(AnnotationMirror, QualifierKind, AnnotationMirror,
 *       QualifierKind,QualifierKind)}
 *   
{@link #greatestLowerBoundWithElements(AnnotationMirror, QualifierKind, AnnotationMirror,
 *       QualifierKind,QualifierKind)}
 * 
 *
 * MostlyNoElementQualifierHierarchy uses a {@link QualifierKindHierarchy} to model the
 * relationships between qualifiers. Subclasses can override {@link
 * #createQualifierKindHierarchy(Collection)} to return a subclass of QualifierKindHierarchy.
 */
@AnnotatedFor("nullness")
public abstract class MostlyNoElementQualifierHierarchy extends ElementQualifierHierarchy {

  /**
   * Creates a MostlyNoElementQualifierHierarchy from the given classes.
   *
   * @param qualifierClasses classes of annotations that are the qualifiers for this hierarchy
   * @param elements element utils
   */
  protected MostlyNoElementQualifierHierarchy(
      Collection> qualifierClasses, Elements elements) {
    super(qualifierClasses, elements);
  }

  @Override
  public final boolean isSubtype(AnnotationMirror subAnno, AnnotationMirror superAnno) {
    QualifierKind subKind = getQualifierKind(subAnno);
    QualifierKind superKind = getQualifierKind(superAnno);
    if (subKind.isSubtypeOf(superKind)) {
      if (superKind.hasElements() && subKind.hasElements()) {
        return isSubtypeWithElements(subAnno, subKind, superAnno, superKind);
      } else {
        return true;
      }
    }
    return false;
  }

  /**
   * Returns true if {@code subAnno} is a subtype of {@code superAnno}. Both {@code subAnno} and
   * {@code superAnno} are annotations with elements. {@code subKind} is a sub qualifier kind of
   * {@code superKind}.
   *
   * @param subAnno possible subtype annotation; has elements
   * @param subKind QualifierKind of {@code subAnno}
   * @param superAnno possible super annotation; has elements
   * @param superKind QualifierKind of {@code superAnno}
   * @return true if {@code subAnno} is a subtype of {@code superAnno}
   */
  protected abstract boolean isSubtypeWithElements(
      AnnotationMirror subAnno,
      QualifierKind subKind,
      AnnotationMirror superAnno,
      QualifierKind superKind);

  @Override
  public final @Nullable AnnotationMirror leastUpperBound(
      AnnotationMirror a1, AnnotationMirror a2) {
    QualifierKind qual1 = getQualifierKind(a1);
    QualifierKind qual2 = getQualifierKind(a2);
    QualifierKind lub = qualifierKindHierarchy.leastUpperBound(qual1, qual2);
    if (lub == null) {
      // Qualifiers are not in the same hierarchy.
      return null;
    }
    if (lub.hasElements()) {
      return leastUpperBoundWithElements(a1, qual1, a2, qual2, lub);
    }
    return kindToElementlessQualifier.get(lub);
  }

  /**
   * Returns the least upper bound of {@code a1} and {@code a2} in cases where the lub of {@code
   * qualifierKind1} and {@code qualifierKind2} is a qualifier kind that has elements. If the lub of
   * {@code qualifierKind1} and {@code qualifierKind2} does not have elements, then {@link
   * #leastUpperBound(AnnotationMirror, AnnotationMirror)} returns the correct {@code
   * AnnotationMirror} without calling this method.
   *
   * @param a1 first annotation
   * @param qualifierKind1 QualifierKind for {@code a1}
   * @param a2 second annotation
   * @param qualifierKind2 QualifierKind for {@code a2}
   * @param lubKind the kind of the lub of {@code qualifierKind1} and {@code qualifierKind2}
   * @return the least upper bound of {@code a1} and {@code a2}
   */
  protected abstract AnnotationMirror leastUpperBoundWithElements(
      AnnotationMirror a1,
      QualifierKind qualifierKind1,
      AnnotationMirror a2,
      QualifierKind qualifierKind2,
      QualifierKind lubKind);

  @Override
  public final @Nullable AnnotationMirror greatestLowerBound(
      AnnotationMirror a1, AnnotationMirror a2) {
    QualifierKind qual1 = getQualifierKind(a1);
    QualifierKind qual2 = getQualifierKind(a2);
    QualifierKind glb = qualifierKindHierarchy.greatestLowerBound(qual1, qual2);
    if (glb == null) {
      // Qualifiers are not in the same hierarchy.
      return null;
    }
    if (glb.hasElements()) {
      return greatestLowerBoundWithElements(a1, qual1, a2, qual2, glb);
    }
    return kindToElementlessQualifier.get(glb);
  }

  /**
   * Returns the greatest lower bound of {@code a1} and {@code a2} in cases where the glb of {@code
   * qualifierKind1} and {@code qualifierKind2} is a qualifier kind that has elements. If the glb of
   * {@code qualifierKind1} and {@code qualifierKind2} does not have elements, then {@link
   * #greatestLowerBound(AnnotationMirror, AnnotationMirror)} returns the correct {@code
   * AnnotationMirror} without calling this method.
   *
   * @param a1 first annotation
   * @param qualifierKind1 QualifierKind for {@code a1}
   * @param a2 second annotation
   * @param qualifierKind2 QualifierKind for {@code a2}
   * @return the greatest lower bound between {@code a1} and {@code a2}
   */
  protected abstract AnnotationMirror greatestLowerBoundWithElements(
      AnnotationMirror a1,
      QualifierKind qualifierKind1,
      AnnotationMirror a2,
      QualifierKind qualifierKind2,
      QualifierKind glbKind);
}