[core] Deprecate CharStream & generated classes

docs/pages/release_notes.md

@@ -129,6 +129,16 @@ You can identify them with the `@InternalApi` annotation. You'll also get a depr
 methods on {% jdoc apex::lang.apex.ast.ApexParserVisitor %} and its implementations.
  Use {% jdoc apex::lang.apex.ast.ApexNode %} instead, now considers comments too.
 
+* {% jdoc core::lang.ast.CharStream %}, {% jdoc core::lang.ast.JavaCharStream %},
+{% jdoc core::lang.ast.SimpleCharStream %}: these are APIs used by our JavaCC
+implementations and that will be moved/refactored for PMD 7.0.0. They should not
+be used, extended or implemented directly.
+* All classes generated by JavaCC, eg {% jdoc java::lang.ast.JJTJavaParserState %}.
+This includes token classes, which will be replaced with a single implementation, and
+subclasses of {% jdoc core::lang.ast.ParseException %}, whose usages will be replaced
+by just that superclass.
+
+
 ##### For removal
 
 * pmd-core

pmd-core/src/main/ant/alljavacc.xml

@@ -42,6 +42,9 @@
         <replace file="${target}/net/sourceforge/pmd/lang/ast/dummy/CharStream.java"
                  token="net.sourceforge.pmd.lang.ast.dummy"
                  value="net.sourceforge.pmd.lang.ast" />
+        <replace file="${target}/net/sourceforge/pmd/lang/ast/dummy/CharStream.java"
+                 token="interface"
+                 value="@Deprecated @net.sourceforge.pmd.annotation.InternalApi interface" />
         <move overwrite="true"
               file="${target}/net/sourceforge/pmd/lang/ast/dummy/CharStream.java"
               tofile="${target}/net/sourceforge/pmd/lang/ast/CharStream.java" />
@@ -59,7 +62,7 @@
                  value="net.sourceforge.pmd.lang.ast" />
         <replace file="${target}/net/sourceforge/pmd/lang/ast/dummy/JavaCharStream.java"
                  token="class JavaCharStream"
-                 value="class JavaCharStream implements CharStream" />
+                 value="@Deprecated @net.sourceforge.pmd.annotation.InternalApi class JavaCharStream implements CharStream" />
         <move overwrite="true"
               file="${target}/net/sourceforge/pmd/lang/ast/dummy/JavaCharStream.java"
               tofile="${target}/net/sourceforge/pmd/lang/ast/JavaCharStream.java" />
@@ -77,7 +80,7 @@
                  value="net.sourceforge.pmd.lang.ast" />
         <replace file="${target}/net/sourceforge/pmd/lang/ast/dummy/SimpleCharStream.java"
                  token="public class SimpleCharStream"
-                 value="public class SimpleCharStream implements CharStream" />
+                 value="@Deprecated @net.sourceforge.pmd.annotation.InternalApi public class SimpleCharStream implements CharStream" />
         <move overwrite="true"
               file="${target}/net/sourceforge/pmd/lang/ast/dummy/SimpleCharStream.java"
               tofile="${target}/net/sourceforge/pmd/lang/ast/SimpleCharStream.java" />

pmd-cpp/src/main/ant/alljavacc.xml

@@ -91,6 +91,21 @@ public class Token implements GenericToken, java.io.Serializable]]></replacevalu
 ]]></replacevalue>
         </replace>
 
+
+
+        <replaceregexp>
+            <regexp pattern="class|interface" />
+            <substitution expression="@Deprecated @net.sourceforge.pmd.annotation.InternalApi \0" />
+            <fileset dir="${target}/net/sourceforge/pmd/lang/cpp/ast"/>
+        </replaceregexp>
+
+        <replaceregexp>
+            <regexp pattern="public class ParseException " />
+            <substitution expression=" /** @deprecated Use superclass {@link net.sourceforge.pmd.lang.ast.ParseException} */
+@Deprecated @net.sourceforge.pmd.annotation.InternalApi \0" />
+            <fileset file="${target}/net/sourceforge/pmd/lang/cpp/ast/ParseException.java"/>
+        </replaceregexp>
+
     </target>
-	
+
 </project>

pmd-cpp/src/main/java/net/sourceforge/pmd/lang/cpp/CppCharStream.java

@@ -8,6 +8,7 @@
 import java.io.Reader;
 import java.util.regex.Pattern;
 
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.SimpleCharStream;
 
 /**
@@ -16,6 +17,8 @@
  *
  * @author Andreas Dangel
  */
+@Deprecated
+@InternalApi
 public class CppCharStream extends SimpleCharStream {
 
     private static final Pattern CONTINUATION = Pattern.compile("\\\\\\n|\\\\\\r\\n");

pmd-java/src/main/ant/alljavacc.xml

@@ -138,5 +138,19 @@ public class Token implements GenericToken, java.io.Serializable]]></replacevalu
                 <include name="AST*.java" />
             </fileset>
         </delete>
+
+
+        <replaceregexp>
+            <regexp pattern="class|interface" />
+            <substitution expression="@Deprecated @net.sourceforge.pmd.annotation.InternalApi \0" />
+            <fileset dir="${target}/net/sourceforge/pmd/lang/java/ast"/>
+        </replaceregexp>
+
+        <replaceregexp>
+            <regexp pattern="public class ParseException " />
+            <substitution expression=" /** @deprecated Use superclass {@link net.sourceforge.pmd.lang.ast.ParseException} */
+@Deprecated @net.sourceforge.pmd.annotation.InternalApi \0" />
+            <fileset file="${target}/net/sourceforge/pmd/lang/java/ast/ParseException.java"/>
+        </replaceregexp>
     </target>
 </project>

pmd-javascript/src/main/ant/alljavacc.xml

@@ -90,5 +90,20 @@ public class Token implements GenericToken, java.io.Serializable]]></replacevalu
 
 ]]></replacevalue>
         </replace>
+
+
+
+        <replaceregexp>
+            <regexp pattern="class|interface" />
+            <substitution expression="@Deprecated @net.sourceforge.pmd.annotation.InternalApi \0" />
+            <fileset dir="${target}/net/sourceforge/pmd/lang/ecmascript5/ast"/>
+        </replaceregexp>
+
+        <replaceregexp>
+            <regexp pattern="public class ParseException " />
+            <substitution expression=" /** @deprecated Use superclass {@link net.sourceforge.pmd.lang.ast.ParseException} */
+@Deprecated @net.sourceforge.pmd.annotation.InternalApi \0" />
+            <fileset file="${target}/net/sourceforge/pmd/lang/ecmascript5/ast/ParseException.java"/>
+        </replaceregexp>
     </target>
 </project>

pmd-jsp/src/main/ant/alljavacc.xml

@@ -116,6 +116,21 @@ public class Token implements GenericToken, java.io.Serializable]]></replacevalu
                 <include name="AST*.java" />
             </fileset>
         </delete>
+
+
+
+        <replaceregexp>
+            <regexp pattern="class|interface" />
+            <substitution expression="@Deprecated @net.sourceforge.pmd.annotation.InternalApi \0" />
+            <fileset dir="${target}/net/sourceforge/pmd/lang/jsp/ast"/>
+        </replaceregexp>
+
+        <replaceregexp>
+            <regexp pattern="public class ParseException " />
+            <substitution expression=" /** @deprecated Use superclass {@link net.sourceforge.pmd.lang.ast.ParseException} */
+@Deprecated @net.sourceforge.pmd.annotation.InternalApi \0" />
+            <fileset file="${target}/net/sourceforge/pmd/lang/jsp/ast/ParseException.java"/>
+        </replaceregexp>
     </target>
 
 </project>

pmd-matlab/src/main/ant/alljavacc.xml

@@ -90,6 +90,21 @@ public class Token implements GenericToken, java.io.Serializable]]></replacevalu
 
 ]]></replacevalue>
         </replace>
+
+
+
+        <replaceregexp>
+            <regexp pattern="class|interface" />
+            <substitution expression="@Deprecated @net.sourceforge.pmd.annotation.InternalApi \0" />
+            <fileset dir="${target}/net/sourceforge/pmd/lang/matlab/ast"/>
+        </replaceregexp>
+
+        <replaceregexp>
+            <regexp pattern="public class ParseException " />
+            <substitution expression=" /** @deprecated Use superclass {@link net.sourceforge.pmd.lang.ast.ParseException} */
+@Deprecated @net.sourceforge.pmd.annotation.InternalApi \0" />
+            <fileset file="${target}/net/sourceforge/pmd/lang/matlab/ast/ParseException.java"/>
+        </replaceregexp>
     </target>
 
 </project>

pmd-modelica/src/main/ant/alljavacc.xml

@@ -153,5 +153,20 @@ public class Token implements GenericToken, java.io.Serializable]]></replacevalu
             </fileset>
         </delete>
 
+
+
+        <replaceregexp>
+            <regexp pattern="class|interface" />
+            <substitution expression="@Deprecated @net.sourceforge.pmd.annotation.InternalApi \0" />
+            <fileset dir="${target}/net/sourceforge/pmd/lang/modelica/ast"/>
+        </replaceregexp>
+
+        <replaceregexp>
+            <regexp pattern="public class ParseException " />
+            <substitution expression=" /** @deprecated Use superclass {@link net.sourceforge.pmd.lang.ast.ParseException} */
+@Deprecated @net.sourceforge.pmd.annotation.InternalApi \0" />
+            <fileset file="${target}/net/sourceforge/pmd/lang/modelica/ast/ParseException.java"/>
+        </replaceregexp>
+
     </target>
 </project>

pmd-objectivec/src/main/ant/alljavacc.xml

@@ -90,6 +90,21 @@ public class Token implements GenericToken, java.io.Serializable]]></replacevalu
 
 ]]></replacevalue>
         </replace>
+
+
+
+        <replaceregexp>
+            <regexp pattern="class|interface" />
+            <substitution expression="@Deprecated @net.sourceforge.pmd.annotation.InternalApi \0" />
+            <fileset dir="${target}/net/sourceforge/pmd/lang/objectivec/ast"/>
+        </replaceregexp>
+
+        <replaceregexp>
+            <regexp pattern="public class ParseException " />
+            <substitution expression=" /** @deprecated Use superclass {@link net.sourceforge.pmd.lang.ast.ParseException} */
+@Deprecated @net.sourceforge.pmd.annotation.InternalApi \0" />
+            <fileset file="${target}/net/sourceforge/pmd/lang/objectivec/ast/ParseException.java"/>
+        </replaceregexp>
     </target>
 
 </project>

pmd-plsql/src/main/ant/alljavacc.xml

@@ -141,5 +141,18 @@ public class Token implements GenericToken, java.io.Serializable]]></replacevalu
 ]]></replacevalue>
         </replace>
 
+
+        <replaceregexp>
+            <regexp pattern="class|interface" />
+            <substitution expression="@Deprecated @net.sourceforge.pmd.annotation.InternalApi \0" />
+            <fileset dir="${target}/net/sourceforge/pmd/lang/plsql/ast"/>
+        </replaceregexp>
+
+        <replaceregexp>
+            <regexp pattern="public class ParseException " />
+            <substitution expression=" /** @deprecated Use superclass {@link net.sourceforge.pmd.lang.ast.ParseException} */
+@Deprecated @net.sourceforge.pmd.annotation.InternalApi \0" />
+            <fileset file="${target}/net/sourceforge/pmd/lang/plsql/ast/ParseException.java"/>
+        </replaceregexp>
     </target>
 </project>

pmd-python/src/main/ant/alljavacc.xml

@@ -90,6 +90,21 @@ public class Token implements GenericToken, java.io.Serializable]]></replacevalu
 
 ]]></replacevalue>
         </replace>
+
+
+
+        <replaceregexp>
+            <regexp pattern="class|interface" />
+            <substitution expression="@Deprecated @net.sourceforge.pmd.annotation.InternalApi \0" />
+            <fileset dir="${target}/net/sourceforge/pmd/lang/python/ast"/>
+        </replaceregexp>
+
+        <replaceregexp>
+            <regexp pattern="public class ParseException " />
+            <substitution expression=" /** @deprecated Use superclass {@link net.sourceforge.pmd.lang.ast.ParseException} */
+@Deprecated @net.sourceforge.pmd.annotation.InternalApi \0" />
+            <fileset file="${target}/net/sourceforge/pmd/lang/python/ast/ParseException.java"/>
+        </replaceregexp>
     </target>
 
 </project>

pmd-visualforce/src/main/ant/alljavacc.xml

@@ -33,7 +33,7 @@
                 javacchome="${javacc-home.path}" />
         <!-- Ensure generated using CharStream interface debugparser="true"
         		debugtokenmanager="true"-->
-        <javacc static="false"        	
+        <javacc static="false"
                 usercharstream="true"
                 unicodeinput="true"
                 javaunicodeescape="false"
@@ -116,6 +116,21 @@ public class Token implements GenericToken, java.io.Serializable]]></replacevalu
                 <include name="AST*.java" />
             </fileset>
         </delete>
+
+
+
+        <replaceregexp>
+            <regexp pattern="class|interface" />
+            <substitution expression="@Deprecated @net.sourceforge.pmd.annotation.InternalApi \0" />
+            <fileset dir="${target}/net/sourceforge/pmd/lang/vf/ast"/>
+        </replaceregexp>
+
+        <replaceregexp>
+            <regexp pattern="public class ParseException " />
+            <substitution expression=" /** @deprecated Use superclass {@link net.sourceforge.pmd.lang.ast.ParseException} */
+@Deprecated @net.sourceforge.pmd.annotation.InternalApi \0" />
+            <fileset file="${target}/net/sourceforge/pmd/lang/vf/ast/ParseException.java"/>
+        </replaceregexp>
     </target>
 
 </project>

pmd-vm/src/main/ant/alljavacc.xml

@@ -123,5 +123,20 @@ public class Token implements GenericToken, java.io.Serializable]]></replacevalu
 
 ]]></replacevalue>
         </replace>
+
+
+
+        <replaceregexp>
+            <regexp pattern="class|interface" />
+            <substitution expression="@Deprecated @net.sourceforge.pmd.annotation.InternalApi \0" />
+            <fileset dir="${target}/net/sourceforge/pmd/lang/vm/ast"/>
+        </replaceregexp>
+
+        <replaceregexp>
+            <regexp pattern="public class ParseException " />
+            <substitution expression=" /** @deprecated Use superclass {@link net.sourceforge.pmd.lang.ast.ParseException} */
+@Deprecated @net.sourceforge.pmd.annotation.InternalApi \0" />
+            <fileset file="${target}/net/sourceforge/pmd/lang/vm/ast/ParseException.java"/>
+        </replaceregexp>
     </target>
 </project>

pmd-vm/src/main/java/net/sourceforge/pmd/lang/vm/ast/TemplateParseException.java

@@ -32,6 +32,7 @@
  *          $
  * @since 1.5
  */
+@Deprecated
 public class TemplateParseException extends ParseException {
     private static final long serialVersionUID = -3146323135623083918L;
 

pmd-vm/src/main/java/net/sourceforge/pmd/lang/vm/util/VelocityCharStream.java

@@ -19,7 +19,7 @@
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  * KIND, either express or implied.  See the License for the
  * specific language governing permissions and limitations
- * under the License.    
+ * under the License.
  */
 
 /**
@@ -36,8 +36,10 @@
 /**
  * An implementation of interface CharStream, where the stream is assumed to
  * contain only ASCII characters (without unicode processing).
+ *
+ * @deprecated Will be removed, replaced with SimpleCharStream
  */
-
+@Deprecated
 public final class VelocityCharStream implements CharStream {
     public static final boolean STATIC_FLAG = false;
     int bufsize;
@@ -401,7 +403,7 @@ public void Done() {
 
     /**
      * Method to adjust line and column numbers for the start of a token.<BR>
-     * 
+     *
      * @param newLine
      * @param newCol
      */