Java: Deprecate error-prone and rarely used annotation predicates

Marcono1234 · smowton · commit 4ef2d156c478 · 2022-09-16T15:49:16.000+01:00
diff --git a/java/ql/lib/semmle/code/java/Annotation.qll b/java/ql/lib/semmle/code/java/Annotation.qll
@@ -45,12 +45,18 @@ class Annotation extends @annotation, Expr {
   }
 
   /**
+   * DEPRECATED: Getting the value of _any_ annotation element is error-prone because
+   * it could lead to selecting the value of the wrong element by accident (for example
+   * when an annotation type is extended in the future). Prefer the predicate `getValue(string)`
+   * and explicitly specify the element name. Use `getValue(_)` if it is really desired to
+   * get the value of any element.
+   *
    * Gets a value of an annotation element. This includes default values in case
    * no explicit value is specified. For elements with an array value type this
    * might have an `ArrayInit` as result. To properly handle array values, prefer
    * the predicate `getAnArrayValue`.
    */
-  Expr getAValue() { filteredAnnotValue(this, _, result) }
+  deprecated Expr getAValue() { filteredAnnotValue(this, _, result) }
 
   /**
    * Gets the value of the annotation element with the specified `name`.
diff --git a/java/ql/lib/semmle/code/java/Dependency.qll b/java/ql/lib/semmle/code/java/Dependency.qll
@@ -71,7 +71,7 @@ predicate depends(RefType t, RefType dep) {
       a.getAnnotatedElement().(Member).getDeclaringType() = t
     |
       usesType(a.getType(), dep) or
-      usesType(a.getAValue().getType(), dep) or
+      usesType(a.getValue(_).getType(), dep) or
       usesType(a.getAnArrayValue(_).getType(), dep)
     )
     or
diff --git a/java/ql/lib/semmle/code/java/DependencyCounts.qll b/java/ql/lib/semmle/code/java/DependencyCounts.qll
@@ -90,7 +90,7 @@ predicate numDepends(RefType t, RefType dep, int value) {
       |
         elem = a and usesType(a.getType(), dep)
         or
-        elem = [a.getAValue(), a.getAnArrayValue(_)] and
+        elem = [a.getValue(_), a.getAnArrayValue(_)] and
         elem.getFile().getExtension() = "java" and
         usesType(elem.(Expr).getType(), dep)
       )
diff --git a/java/ql/lib/semmle/code/java/JDKAnnotations.qll b/java/ql/lib/semmle/code/java/JDKAnnotations.qll
@@ -19,30 +19,31 @@ class SuppressWarningsAnnotation extends Annotation {
   SuppressWarningsAnnotation() { this.getType().hasQualifiedName("java.lang", "SuppressWarnings") }
 
   /**
-   * Gets the `StringLiteral` of a warning suppressed by this annotation. To get the name of a suppressed
-   * warning, prefer `getASuppressedWarning()`. That predicate considers more cases because it does not
-   * restrict results to `StringLiteral`.
+   * 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.
    */
-  StringLiteral getASuppressedWarningLiteral() { result = this.getAnArrayValue("value") }
+  deprecated StringLiteral getASuppressedWarningLiteral() { result = this.getAnArrayValue("value") }
 
   /** Gets the name of a warning suppressed by this annotation. */
-  string getASuppressedWarning() {
-    // Don't use getASuppressedWarningLiteral() because that restricts results to StringLiteral
-    result = this.getAStringArrayValue("value")
-  }
+  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() { result = this.getAnArrayValue("value") }
+  deprecated Expr getATargetExpression() { result = this.getAnArrayValue("value") }
 
   /**
    * Gets the name of a target element type.

Original file line number	Diff line number	Diff line change
`@@ -71,7 +71,7 @@ predicate depends(RefType t, RefType dep) {`
`71`	`71`	`a.getAnnotatedElement().(Member).getDeclaringType() = t`
`72`	`72`	`\|`
`73`	`73`	`usesType(a.getType(), dep) or`
`74`		`- usesType(a.getAValue().getType(), dep) or`
	`74`	`+ usesType(a.getValue(_).getType(), dep) or`
`75`	`75`	`usesType(a.getAnArrayValue(_).getType(), dep)`
`76`	`76`	`)`
`77`	`77`	`or`
Original file line number	Diff line number	Diff line change
`@@ -90,7 +90,7 @@ predicate numDepends(RefType t, RefType dep, int value) {`
`90`	`90`	`\|`
`91`	`91`	`elem = a and usesType(a.getType(), dep)`
`92`	`92`	`or`
`93`		`- elem = [a.getAValue(), a.getAnArrayValue(_)] and`
	`93`	`+ elem = [a.getValue(_), a.getAnArrayValue(_)] and`
`94`	`94`	`elem.getFile().getExtension() = "java" and`
`95`	`95`	`usesType(elem.(Expr).getType(), dep)`
`96`	`96`	`)`