Java: move original files

Author: Jami Cogswell

java/ql/src/Violations of Best Practice/Undesirable Calls/DoNotUseFinalizers.md

@@ -0,0 +1,34 @@
+# J-FIN-002: Calling garbage collection methods in application code may cause inconsistent program state
+
+Calling garbage collection or finalizer methods in application code may cause inconsistent program state or unpredicatable behavior.
+
+## Overview
+
+Triggering garbage collection explicitly may either have no effect or may trigger unnecessary garbage collection, leading to erratic behavior or deadlock.
+
+## Recommendation
+
+Avoid calling finalizers and garbage collection methods in application code. Allow the JVM to determine a garbage collection schedule instead.
+
+## Example
+
+```java
+public class Test {
+    void f() throws Throwable {
+        System.gc(); // NON_COMPLIANT
+        Runtime.getRuntime().gc(); // NON_COMPLIANT
+        System.runFinalizersOnExit(true); //NON_COMPLIANT
+        this.finalize(); // NON_COMPLIANT
+    }
+}
+
+```
+
+# Implementation Notes
+
+This rule covers a concept related to J-FIN-001; this rule is focused on the use of existing finalizer invocations rather than attempts to write a custom implementation (J-FIN-001).
+
+## References
+
+- [Do not use finalizers](https://wiki.sei.cmu.edu/confluence/display/java/MET12-J.+Do+not+use+finalizers)
+- [CWE-586](https://cwe.mitre.org/data/definitions/586)

java/ql/src/Violations of Best Practice/Undesirable Calls/DoNotUseFinalizers.ql

@@ -0,0 +1,25 @@
+/**
+ * @id java/do-not-use-finalizers
+ * @name J-D-004: Calling garbage collection methods in application code may cause inconsistent program state
+ * @description Calling garbage collection or finalizer methods in application code may cause
+ *              inconsistent program state or unpredicatable behavior.
+ * @kind problem
+ * @precision high
+ * @problem.severity error
+ * @tags correctness
+ *       external/cwe/cwe-586
+ */
+
+import java
+
+from MethodCall c, Method m
+where
+  c.getMethod() = m and
+  (
+    m.hasQualifiedName("java.lang", "System", ["gc", "runFinalizersOnExit"])
+    or
+    m.hasQualifiedName("java.lang", "Runtime", "gc")
+    or
+    m.hasQualifiedName(_, _, "finalize")
+  )
+select c, "Call to prohibited method that may modify the JVM's garbage collection process."

java/ql/test/query-tests/DoNotUseFinalizers/DoNotUseFinalizers.expected

@@ -0,0 +1,3 @@
+| Test.java:3:9:3:19 | gc(...) | Call to prohibited method that may modify the JVM's garbage collection process. |
+| Test.java:4:9:4:33 | gc(...) | Call to prohibited method that may modify the JVM's garbage collection process. |
+| Test.java:5:9:5:23 | finalize(...) | Call to prohibited method that may modify the JVM's garbage collection process. |

java/ql/test/query-tests/DoNotUseFinalizers/DoNotUseFinalizers.qlref

@@ -0,0 +1 @@
+rules/J-FIN-002/DoNotUseFinalizers.ql

java/ql/test/query-tests/DoNotUseFinalizers/Test.java

@@ -0,0 +1,13 @@
+public class Test {
+    void f() throws Throwable {
+        System.gc(); // NON_COMPLIANT
+        Runtime.getRuntime().gc(); // NON_COMPLIANT
+        this.finalize(); // NON_COMPLIANT
+        // this is removed in Java 11
+        //System.runFinalizersOnExit(true); // NON_COMPLIANT
+    }
+
+    void f1() throws Throwable {
+        f(); // COMPLIANT
+    }
+}