org.checkerframework.javacutil.AnnotationProvider Maven / Gradle / Ivy

Go to download

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.42.0-eisop4

Show newest version

package org.checkerframework.javacutil;

import com.sun.source.tree.Tree;

import org.checkerframework.checker.nullness.qual.Nullable;

import java.lang.annotation.Annotation;

import javax.lang.model.element.AnnotationMirror;
import javax.lang.model.element.Element;
import javax.lang.model.element.ExecutableElement;

// This class exists to break a circular dependency between the dataflow framework and
// type-checkers.
/** An implementation of AnnotationProvider returns annotations on Java AST elements. */
public interface AnnotationProvider {

    /**
     * Returns the AnnotationMirror, of the given class or an alias of it, used to annotate the
     * element. Returns null if no annotation equivalent to {@code anno} exists on {@code elt}.
     *
     * @param elt the element
     * @param anno annotation class
     * @return an annotation mirror of class {@code anno} on {@code elt}, or an equivalent one, or
     *     null if none exists on {@code anno}
     */
    @Nullable AnnotationMirror getDeclAnnotation(Element elt, Class anno);

    /**
     * Return the annotation on {@code tree} that is in the hierarchy that contains the qualifier
     * {@code target}. Returns null if none exists.
     *
     * @param tree the tree of which the annotation is returned
     * @param target the class of the annotation
     * @return the annotation on {@code tree} that has the class {@code target}, or null
     */
    @Nullable AnnotationMirror getAnnotationMirror(Tree tree, Class target);

    /**
     * Returns true if the given method is side-effect-free according to this AnnotationProvider
     * — that is, if a call to the given method does not undo flow-sensitive type refinement.
     *
     * Note that this method takes account of this AnnotationProvider's semantics, whereas {@code
     * org.checkerframework.dataflow.util.PurityUtils#isSideEffectFree} does not.
     *
     * @param methodElement a method
     * @return true if a call to the method does not undo flow-sensitive type refinement
     */
    boolean isSideEffectFree(ExecutableElement methodElement);

    /**
     * Returns true if the given method is deterministic according to this AnnotationProvider
     * — that is, if multiple calls to the given method (with the same arguments) return the
     * same value.
     *
     * Note that this method takes account of this AnnotationProvider's semantics, whereas {@code
     * org.checkerframework.dataflow.util.PurityUtils#isDeterministic} does not.
     *
     * @param methodElement a method
     * @return true if multiple calls to the method (with the same arguments) return the same value
     */
    boolean isDeterministic(ExecutableElement methodElement);
}