[java] Deprecate AST internal API

docs/pages/release_notes.md

@@ -18,6 +18,30 @@ This is a {{ site.pmd.release_type }} release.
 
 ### API Changes
 
+#### Deprecated APIs
+
+> Reminder: Please don't use members marked with the annotation {% jdoc core::annotation.InternalApi %}, as they will likely be removed, hidden, or otherwise intentionally broken with 7.0.0.
+
+
+##### In ASTs
+
+As part of the changes we'd like to do to AST classes for 7.0.0, we would like to
+hide some methods and constructors that rule writers should not have access to.
+The following usages are now deprecated **in the Java AST** (with other languages to come):
+
+* Manual instantiation of nodes. **Constructors of node classes are deprecated** and marked {% jdoc core::annotation.InternalApi %}. Nodes should only be obtained from the parser, which for rules, means that never need to instantiate node themselves. Those constructors will be made package private with 7.0.0.
+* **Subclassing of abstract node classes, or usage of their type**. Version 7.0.0 will bring a new set of abstractions that will be public API, but the base classes are and will stay internal. You should not couple your code to them.
+  * In the meantime you should use interfaces like {% jdoc java::lang.java.ast.JavaNode %} or  {% jdoc core::lang.ast.Node %}, or the other published interfaces in this package, to refer to nodes generically.
+  * Concrete node classes will **be made final** with 7.0.0.
+* Setters found in any node class or interface. **Rules should consider the AST immutable**. We will make those setters package private with 7.0.0.
+
+Please look at {% jdoc_package java::lang.java.ast %} to find out the full list
+of deprecations.
+
+
+
+
+
 ### External Contributions
 
 {% endtocmaker %}

pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTAdditiveExpression.java

@@ -1,10 +1,11 @@
 /**
  * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
  */
-/* Generated By:JJTree: Do not edit this line. ASTAdditiveExpression.java */
 
 package net.sourceforge.pmd.lang.java.ast;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
 /**
  * Represents an addition operation on two or more values, or string concatenation.
  * This has a precedence greater than {@link ASTShiftExpression}, and lower
@@ -20,10 +21,15 @@
  * </pre>
  */
 public class ASTAdditiveExpression extends AbstractJavaTypeNode {
+
+    @InternalApi
+    @Deprecated
     public ASTAdditiveExpression(int id) {
         super(id);
     }
 
+    @InternalApi
+    @Deprecated
     public ASTAdditiveExpression(JavaParser p, int id) {
         super(p, id);
     }

pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTAllocationExpression.java

@@ -1,28 +1,29 @@
 /**
  * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
  */
-/* Generated By:JJTree: Do not edit this line. ASTAllocationExpression.java */
 
 package net.sourceforge.pmd.lang.java.ast;
 
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.java.qname.JavaTypeQualifiedName;
 
 
 public class ASTAllocationExpression extends AbstractJavaTypeNode implements JavaQualifiableNode {
 
     private JavaTypeQualifiedName qualifiedName;
 
+    @InternalApi
+    @Deprecated
     public ASTAllocationExpression(int id) {
         super(id);
     }
 
+    @InternalApi
+    @Deprecated
     public ASTAllocationExpression(JavaParser p, int id) {
         super(p, id);
     }
 
-    /**
-     * Accept the visitor. *
-     */
     @Override
     public Object jjtAccept(JavaParserVisitor visitor, Object data) {
         return visitor.visit(this, data);
@@ -54,6 +55,8 @@ public JavaTypeQualifiedName getQualifiedName() {
         return qualifiedName;
     }
 
+    @InternalApi
+    @Deprecated
     public void setQualifiedName(JavaTypeQualifiedName qname) {
         this.qualifiedName = qname;
     }

pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTAndExpression.java

@@ -1,10 +1,11 @@
 /**
  * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
  */
-/* Generated By:JJTree: Do not edit this line. ASTAndExpression.java */
 
 package net.sourceforge.pmd.lang.java.ast;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
 /**
  * Represents a non-shortcut boolean AND-expression.
  * This has a precedence greater than {@link ASTExclusiveOrExpression},
@@ -21,10 +22,15 @@
  * </pre>
  */
 public class ASTAndExpression extends AbstractJavaTypeNode {
+
+    @InternalApi
+    @Deprecated
     public ASTAndExpression(int id) {
         super(id);
     }
 
+    @InternalApi
+    @Deprecated
     public ASTAndExpression(JavaParser p, int id) {
         super(p, id);
     }

pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTAnnotation.java

@@ -1,14 +1,14 @@
 /**
  * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
  */
-/* Generated By:JJTree: Do not edit this line. ASTAnnotation.java */
 
 package net.sourceforge.pmd.lang.java.ast;
 
 import java.util.Arrays;
 import java.util.List;
 
 import net.sourceforge.pmd.Rule;
+import net.sourceforge.pmd.annotation.InternalApi;
 
 
 /**
@@ -22,19 +22,22 @@
  *              | {@linkplain ASTMarkerAnnotation MarkerAnnotation}
  *
  * </pre>
- *
  */
 public class ASTAnnotation extends AbstractJavaTypeNode {
 
     private static final List<String> UNUSED_RULES
-            = Arrays.asList("UnusedPrivateField", "UnusedLocalVariable", "UnusedPrivateMethod", "UnusedFormalParameter");
+        = Arrays.asList("UnusedPrivateField", "UnusedLocalVariable", "UnusedPrivateMethod", "UnusedFormalParameter");
 
     private static final List<String> SERIAL_RULES = Arrays.asList("BeanMembersShouldSerialize", "MissingSerialVersionUID");
 
+    @InternalApi
+    @Deprecated
     public ASTAnnotation(int id) {
         super(id);
     }
 
+    @InternalApi
+    @Deprecated
     public ASTAnnotation(JavaParser p, int id) {
         super(p, id);
     }
@@ -82,10 +85,10 @@ public boolean suppresses(Rule rule) {
         if (isSuppressWarnings()) {
             for (ASTLiteral element : findDescendantsOfType(ASTLiteral.class)) {
                 if (element.hasImageEqualTo("\"PMD\"") || element.hasImageEqualTo("\"PMD." + rule.getName() + "\"")
-                        // Check for standard annotations values
-                        || element.hasImageEqualTo("\"all\"")
-                        || element.hasImageEqualTo("\"serial\"") && SERIAL_RULES.contains(rule.getName())
-                        || element.hasImageEqualTo("\"unused\"") && UNUSED_RULES.contains(rule.getName())) {
+                    // Check for standard annotations values
+                    || element.hasImageEqualTo("\"all\"")
+                    || element.hasImageEqualTo("\"serial\"") && SERIAL_RULES.contains(rule.getName())
+                    || element.hasImageEqualTo("\"unused\"") && UNUSED_RULES.contains(rule.getName())) {
                     return true;
                 }
             }
@@ -96,7 +99,8 @@ public boolean suppresses(Rule rule) {
 
 
     private boolean isSuppressWarnings() {
-        return "SuppressWarnings".equals(getAnnotationName()) || "java.lang.SuppressWarnings".equals(getAnnotationName());
+        return "SuppressWarnings".equals(getAnnotationName())
+            || "java.lang.SuppressWarnings".equals(getAnnotationName());
     }
 
     @Override

pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTAnnotationMethodDeclaration.java

@@ -1,21 +1,25 @@
 /**
  * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
  */
-/* Generated By:JJTree: Do not edit this line. ASTAnnotationMethodDeclaration.java Version 4.1 */
-/* JavaCCOptions:MULTI=true,NODE_USES_PARSER=true,VISITOR=true,TRACK_TOKENS=false,NODE_PREFIX=AST,NODE_EXTENDS=,NODE_FACTORY= */
 
 package net.sourceforge.pmd.lang.java.ast;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
 public class ASTAnnotationMethodDeclaration extends AbstractMethodLikeNode {
+
+    @InternalApi
+    @Deprecated
     public ASTAnnotationMethodDeclaration(int id) {
         super(id);
     }
 
+    @InternalApi
+    @Deprecated
     public ASTAnnotationMethodDeclaration(JavaParser p, int id) {
         super(p, id);
     }
 
-    /** Accept the visitor. **/
     @Override
     public Object jjtAccept(JavaParserVisitor visitor, Object data) {
         return visitor.visit(this, data);
@@ -27,7 +31,3 @@ public MethodLikeKind getKind() {
         return MethodLikeKind.METHOD;
     }
 }
-/*
- * JavaCC - OriginalChecksum=f6dd440446f8aa5c9c191ae760080ee0 (do not edit this
- * line)
- */

pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTAnnotationTypeBody.java

@@ -1,22 +1,25 @@
 /**
  * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
  */
-/* Generated By:JJTree: Do not edit this line. ASTAnnotationTypeBody.java */
 
 package net.sourceforge.pmd.lang.java.ast;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
 public class ASTAnnotationTypeBody extends AbstractJavaNode {
+
+    @InternalApi
+    @Deprecated
     public ASTAnnotationTypeBody(int id) {
         super(id);
     }
 
+    @InternalApi
+    @Deprecated
     public ASTAnnotationTypeBody(JavaParser p, int id) {
         super(p, id);
     }
 
-    /**
-     * Accept the visitor. *
-     */
     @Override
     public Object jjtAccept(JavaParserVisitor visitor, Object data) {
         return visitor.visit(this, data);

pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTAnnotationTypeDeclaration.java

@@ -1,26 +1,28 @@
 /**
  * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
  */
-/* Generated By:JJTree: Do not edit this line. ASTAnnotationTypeDeclaration.java */
 
 package net.sourceforge.pmd.lang.java.ast;
 
 import java.util.List;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
 public class ASTAnnotationTypeDeclaration extends AbstractAnyTypeDeclaration {
 
 
+    @InternalApi
+    @Deprecated
     public ASTAnnotationTypeDeclaration(int id) {
         super(id);
     }
 
+    @InternalApi
+    @Deprecated
     public ASTAnnotationTypeDeclaration(JavaParser p, int id) {
         super(p, id);
     }
 
-    /**
-     * Accept the visitor.
-     */
     @Override
     public Object jjtAccept(JavaParserVisitor visitor, Object data) {
         return visitor.visit(this, data);

pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTAnnotationTypeMemberDeclaration.java

@@ -1,22 +1,25 @@
 /**
  * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
  */
-/* Generated By:JJTree: Do not edit this line. ASTAnnotationTypeMemberDeclaration.java */
 
 package net.sourceforge.pmd.lang.java.ast;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
 public class ASTAnnotationTypeMemberDeclaration extends AbstractTypeBodyDeclaration {
+
+    @InternalApi
+    @Deprecated
     public ASTAnnotationTypeMemberDeclaration(int id) {
         super(id);
     }
 
+    @InternalApi
+    @Deprecated
     public ASTAnnotationTypeMemberDeclaration(JavaParser p, int id) {
         super(p, id);
     }
 
-    /**
-     * Accept the visitor. *
-     */
     @Override
     public Object jjtAccept(JavaParserVisitor visitor, Object data) {
         return visitor.visit(this, data);

pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTArgumentList.java

@@ -1,22 +1,25 @@
 /**
  * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
  */
-/* Generated By:JJTree: Do not edit this line. ASTArgumentList.java */
 
 package net.sourceforge.pmd.lang.java.ast;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
 public class ASTArgumentList extends AbstractJavaNode {
+
+    @InternalApi
+    @Deprecated
     public ASTArgumentList(int id) {
         super(id);
     }
 
+    @InternalApi
+    @Deprecated
     public ASTArgumentList(JavaParser p, int id) {
         super(p, id);
     }
 
-    /**
-     * Accept the visitor. *
-     */
     @Override
     public Object jjtAccept(JavaParserVisitor visitor, Object data) {
         return visitor.visit(this, data);

pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTArguments.java

@@ -1,15 +1,21 @@
 /**
  * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
  */
-/* Generated By:JJTree: Do not edit this line. ASTArguments.java */
 
 package net.sourceforge.pmd.lang.java.ast;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
 public class ASTArguments extends AbstractJavaNode {
+
+    @InternalApi
+    @Deprecated
     public ASTArguments(int id) {
         super(id);
     }
 
+    @InternalApi
+    @Deprecated
     public ASTArguments(JavaParser p, int id) {
         super(p, id);
     }
@@ -21,9 +27,6 @@ public int getArgumentCount() {
         return this.jjtGetChild(0).jjtGetNumChildren();
     }
 
-    /**
-     * Accept the visitor. *
-     */
     @Override
     public Object jjtAccept(JavaParserVisitor visitor, Object data) {
         return visitor.visit(this, data);