Merge pull request #6246 from Marcono1234/marcono1234/annotation-improvements

Java: Improve and add predicates and classes for annotations

Author: smowton

java/ql/lib/change-notes/2022-04-01-annotation-deprecations.md

@@ -0,0 +1,7 @@
+---
+category: deprecated
+---
+* The predicate `Annotation.getAValue()` has been deprecated because it might lead to obtaining the value of the wrong annotation element by accident. `getValue(string)` (or one of the value type specific predicates) should be used to explicitly specify the name of the annotation element.
+* The predicate `Annotation.getAValue(string)` has been renamed to `getAnArrayValue(string)`.
+* The predicate `SuppressWarningsAnnotation.getASuppressedWarningLiteral()` has been deprecated because it unnecessarily restricts the result type; `getASuppressedWarning()` should be used instead.
+* The predicates `TargetAnnotation.getATargetExpression()` and `RetentionAnnotation.getRetentionPolicyExpression()` have been deprecated because getting the enum constant read expression is rarely useful, instead the corresponding predicates for getting the name of the referenced enum constants should be used.

java/ql/lib/change-notes/2022-04-01-annotation-features.md

@@ -0,0 +1,9 @@
+---
+category: feature
+---
+* The predicates of the CodeQL class `Annotation` have been improved:
+  * Convenience value type specific predicates have been added, such as `getEnumConstantValue(string)` or `getStringValue(string)`.
+  * Convenience predicates for elements with array values have been added, such as `getAnEnumConstantArrayValue(string)`. While the behavior of the existing predicates has not changed, usage of them should be reviewed (or replaced with the newly added predicate) to make sure they work correctly for elements with array values.
+  * Some internal CodeQL usage of the `Annotation` predicates has been adjusted and corrected; this might affect the results of some queries.
+* New predicates have been added to the CodeQL class `Annotatable` to support getting declared and associated annotations. As part of that, `hasAnnotation()` has been changed to also consider inherited annotations, to be consistent with `hasAnnotation(string, string)` and `getAnAnnotation()`. The newly added predicate `hasDeclaredAnnotation()` can be used as replacement for the old functionality.
+* New predicates have been added to the CodeQL class `AnnotationType` to simplify getting information about usage of JDK meta-annotations, such as `@Retention`.

java/ql/lib/semmle/code/java/Annotation.qll

@@ -71,7 +71,8 @@ predicate depends(RefType t, RefType dep) {
       a.getAnnotatedElement().(Member).getDeclaringType() = t
     |
       usesType(a.getType(), dep) or
-      usesType(a.getAValue().getType(), dep)
+      usesType(a.getValue(_).getType(), dep) or
+      usesType(a.getAnArrayValue(_).getType(), dep)
     )
     or
     // the type accessed in an `instanceof` expression in `t`.

java/ql/lib/semmle/code/java/Dependency.qll

@@ -90,7 +90,7 @@ predicate numDepends(RefType t, RefType dep, int value) {
       |
         elem = a and usesType(a.getType(), dep)
         or
-        elem = a.getAValue() and
+        elem = [a.getValue(_), a.getAnArrayValue(_)] and
         elem.getFile().getExtension() = "java" and
         usesType(elem.(Expr).getType(), dep)
       )

java/ql/lib/semmle/code/java/DependencyCounts.qll

@@ -18,76 +18,75 @@ class OverrideAnnotation extends Annotation {
 class SuppressWarningsAnnotation extends Annotation {
   SuppressWarningsAnnotation() { this.getType().hasQualifiedName("java.lang", "SuppressWarnings") }
 
-  /** Gets the `StringLiteral` of a warning suppressed by this annotation. */
-  StringLiteral getASuppressedWarningLiteral() {
-    result = this.getAValue() or
-    result = this.getAValue().(ArrayInit).getAnInit()
-  }
+  /**
+   * DEPRECATED: This predicate restricts the results to `StringLiteral`; prefer `getASuppressedWarning()`
+   * to get the name of a suppressed warning.
+   *
+   * Gets the `StringLiteral` of a warning suppressed by this annotation.
+   */
+  deprecated StringLiteral getASuppressedWarningLiteral() { result = this.getAnArrayValue("value") }
 
   /** Gets the name of a warning suppressed by this annotation. */
-  string getASuppressedWarning() { result = this.getASuppressedWarningLiteral().getValue() }
+  string getASuppressedWarning() { result = this.getAStringArrayValue("value") }
 }
 
 /** A `@Target` annotation. */
 class TargetAnnotation extends Annotation {
   TargetAnnotation() { this.getType().hasQualifiedName("java.lang.annotation", "Target") }
 
   /**
+   * DEPRECATED: Getting the field access expression is rarely useful. Use `getATargetElementType()`
+   * to get the name of the target element.
+   *
    * Gets a target expression within this annotation.
    *
    * For example, the field access `ElementType.FIELD` is a target expression in
    * `@Target({ElementType.FIELD, ElementType.METHOD})`.
    */
-  Expr getATargetExpression() {
-    not result instanceof ArrayInit and
-    (
-      result = this.getAValue() or
-      result = this.getAValue().(ArrayInit).getAnInit()
-    )
-  }
+  deprecated Expr getATargetExpression() { result = this.getAnArrayValue("value") }
 
   /**
    * Gets the name of a target element type.
    *
    * For example, `METHOD` is the name of a target element type in
    * `@Target({ElementType.FIELD, ElementType.METHOD})`.
    */
-  string getATargetElementType() {
-    exists(EnumConstant ec |
-      ec = this.getATargetExpression().(VarAccess).getVariable() and
-      ec.getDeclaringType().hasQualifiedName("java.lang.annotation", "ElementType")
-    |
-      result = ec.getName()
-    )
-  }
+  string getATargetElementType() { result = this.getAnEnumConstantArrayValue("value").getName() }
 }
 
 /** A `@Retention` annotation. */
 class RetentionAnnotation extends Annotation {
   RetentionAnnotation() { this.getType().hasQualifiedName("java.lang.annotation", "Retention") }
 
   /**
+   * DEPRECATED: Getting the field access expression is rarely useful. Use `getRetentionPolicy()`
+   * to get the name of the retention policy.
+   *
    * Gets the retention policy expression within this annotation.
    *
    * For example, the field access `RetentionPolicy.RUNTIME` is the
    * retention policy expression in `@Retention(RetentionPolicy.RUNTIME)`.
    */
-  Expr getRetentionPolicyExpression() { result = this.getValue("value") }
+  deprecated Expr getRetentionPolicyExpression() { result = this.getValue("value") }
 
   /**
    * Gets the name of the retention policy of this annotation.
    *
    * For example, `RUNTIME` is the name of the retention policy
    * in `@Retention(RetentionPolicy.RUNTIME)`.
    */
-  string getRetentionPolicy() {
-    exists(EnumConstant ec |
-      ec = this.getRetentionPolicyExpression().(VarAccess).getVariable() and
-      ec.getDeclaringType().hasQualifiedName("java.lang.annotation", "RetentionPolicy")
-    |
-      result = ec.getName()
-    )
-  }
+  string getRetentionPolicy() { result = this.getEnumConstantValue("value").getName() }
+}
+
+/** A `@Repeatable` annotation. */
+class RepeatableAnnotation extends Annotation {
+  RepeatableAnnotation() { this.getType().hasQualifiedName("java.lang.annotation", "Repeatable") }
+
+  /**
+   * Gets the annotation type which acts as _containing type_, grouping multiple
+   * repeatable annotations together.
+   */
+  AnnotationType getContainingType() { result = this.getTypeValue("value") }
 }
 
 /**
@@ -119,11 +118,7 @@ abstract class NonReflectiveAnnotation extends Annotation { }
 
 library class StandardNonReflectiveAnnotation extends NonReflectiveAnnotation {
   StandardNonReflectiveAnnotation() {
-    exists(AnnotationType anntp | anntp = this.getType() |
-      anntp.hasQualifiedName("java.lang", "Override") or
-      anntp.hasQualifiedName("java.lang", "Deprecated") or
-      anntp.hasQualifiedName("java.lang", "SuppressWarnings") or
-      anntp.hasQualifiedName("java.lang", "SafeVarargs")
-    )
+    this.getType()
+        .hasQualifiedName("java.lang", ["Override", "Deprecated", "SuppressWarnings", "SafeVarargs"])
   }
 }

java/ql/lib/semmle/code/java/JDKAnnotations.qll

@@ -120,7 +120,7 @@ private newtype TPrintAstNode =
     shouldPrint(lvde, _) and lvde.getParent() instanceof SingleLocalVarDeclParent
   } or
   TAnnotationsNode(Annotatable ann) {
-    shouldPrint(ann, _) and ann.hasAnnotation() and not partOfAnnotation(ann)
+    shouldPrint(ann, _) and ann.hasDeclaredAnnotation() and not partOfAnnotation(ann)
   } or
   TParametersNode(Callable c) { shouldPrint(c, _) and not c.hasNoParameters() } or
   TBaseTypesNode(ClassOrInterface ty) { shouldPrint(ty, _) } or

java/ql/lib/semmle/code/java/PrintAst.qll

@@ -161,15 +161,13 @@ class TestNGTestMethod extends Method {
     exists(TestNGTestAnnotation testAnnotation |
       testAnnotation = this.getAnAnnotation() and
       // The data provider must have the same name as the referenced data provider
-      result.getDataProviderName() =
-        testAnnotation.getValue("dataProvider").(StringLiteral).getValue()
+      result.getDataProviderName() = testAnnotation.getStringValue("dataProvider")
     |
       // Either the data provider should be on the current class, or a supertype
       this.getDeclaringType().getAnAncestor() = result.getDeclaringType()
       or
       // Or the data provider class should be declared
-      result.getDeclaringType() =
-        testAnnotation.getValue("dataProviderClass").(TypeLiteral).getReferencedType()
+      result.getDeclaringType() = testAnnotation.getTypeValue("dataProviderClass")
     )
   }
 }
@@ -227,9 +225,7 @@ class TestNGListenersAnnotation extends TestNGAnnotation {
   /**
    * Gets a listener defined in this annotation.
    */
-  TestNGListenerImpl getAListener() {
-    result = this.getAValue("value").(TypeLiteral).getReferencedType()
-  }
+  TestNGListenerImpl getAListener() { result = this.getATypeArrayValue("value") }
 }
 
 /**

java/ql/lib/semmle/code/java/UnitTests.qll

@@ -60,7 +60,7 @@ class JaxbType extends Class {
       this.getAnAnnotation() = a and
       a.getType().(JaxbAnnotationType).hasName("XmlAccessorType")
     |
-      result.getAnAccess() = a.getValue("value")
+      result = a.getEnumConstantValue("value")
     )
   }
 

java/ql/lib/semmle/code/java/frameworks/JAXB.qll

@@ -64,5 +64,5 @@ class RunWithAnnotation extends Annotation {
   /**
    * Gets the runner that will be used.
    */
-  Type getRunner() { result = this.getValue("value").(TypeLiteral).getReferencedType() }
+  Type getRunner() { result = this.getTypeValue("value") }
 }