Merge pull request #2146 from oowekyala/deprecate-rvf-impls

[core] Deprecate implementations of RuleViolation[Factory]

docs/pages/release_notes.md

@@ -26,7 +26,12 @@ This is a {{ site.pmd.release_type }} release.
 * {% jdoc java::lang.java.JavaLanguageHandler %}
 * {% jdoc java::lang.java.JavaLanguageParser %}
 * {% jdoc java::lang.java.JavaDataFlowHandler %}
-
+* Implementations of {% jdoc core::lang.rule.RuleViolationFactory %} in each
+  language module, eg {% jdoc java::lang.java.rule.JavaRuleViolationFactory %}.
+  See javadoc of {% jdoc core::lang.rule.RuleViolationFactory %}.
+* Implementations of {% jdoc core::RuleViolation %} in each language module,
+  eg {% jdoc java::lang.java.rule.JavaRuleViolation %}. See javadoc of
+  {% jdoc core::RuleViolation %}.
 
 ##### For removal
 

pmd-apex/src/main/java/net/sourceforge/pmd/lang/apex/rule/ApexRuleViolation.java

@@ -6,6 +6,8 @@ package net.sourceforge.pmd.lang.apex.rule;
 
 import net.sourceforge.pmd.Rule;
 import net.sourceforge.pmd.RuleContext;
+import net.sourceforge.pmd.RuleViolation;
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.apex.ast.CanSuppressWarnings;
 import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.rule.ParametricRuleViolation;
@@ -21,8 +23,12 @@ import net.sourceforge.pmd.lang.rule.ParametricRuleViolation;
  * <li>Suppression indicator</li>
  * </ul>
  * @param <T>
+ *
+ * @deprecated See {@link RuleViolation}
  */
 @SuppressWarnings("PMD.UseUtilityClass") // we inherit non-static methods...
+@Deprecated
+@InternalApi
 public class ApexRuleViolation<T> extends ParametricRuleViolation<Node> {
 
     public ApexRuleViolation(Rule rule, RuleContext ctx, Node node, String message, int beginLine, int endLine) {

pmd-apex/src/main/java/net/sourceforge/pmd/lang/apex/rule/ApexRuleViolationFactory.java

@@ -7,9 +7,16 @@ package net.sourceforge.pmd.lang.apex.rule;
 import net.sourceforge.pmd.Rule;
 import net.sourceforge.pmd.RuleContext;
 import net.sourceforge.pmd.RuleViolation;
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.rule.AbstractRuleViolationFactory;
+import net.sourceforge.pmd.lang.rule.RuleViolationFactory;
 
+/**
+ * @deprecated See {@link RuleViolationFactory}
+ */
+@Deprecated
+@InternalApi
 public final class ApexRuleViolationFactory extends AbstractRuleViolationFactory {
 
     public static final ApexRuleViolationFactory INSTANCE = new ApexRuleViolationFactory();

pmd-core/src/main/java/net/sourceforge/pmd/RuleViolation.java

@@ -6,7 +6,11 @@ package net.sourceforge.pmd;
 
 /**
  * A RuleViolation is created by a Rule when it identifies a violation of the
- * Rule constraints.
+ * Rule constraints. RuleViolations are simple data holders that are collected
+ * into a {@link Report}.
+ *
+ * <p>Since PMD 6.21.0, implementations of this interface are considered internal
+ * API and hence deprecated. Clients should exclusively use this interface.
  *
  * @see Rule
  */

pmd-core/src/main/java/net/sourceforge/pmd/lang/rule/RuleViolationFactory.java

@@ -6,11 +6,16 @@ package net.sourceforge.pmd.lang.rule;
 
 import net.sourceforge.pmd.Rule;
 import net.sourceforge.pmd.RuleContext;
+import net.sourceforge.pmd.lang.LanguageVersionHandler;
 import net.sourceforge.pmd.lang.ast.Node;
 
 /**
  * This class handles of producing a Language specific RuleViolation and adding
  * to a Report.
+ *
+ * <p>Since PMD 6.21.0, implementations of this interface are considered internal
+ * API and hence deprecated. Clients should exclusively use this interface and obtain
+ * instances through {@link LanguageVersionHandler#getRuleViolationFactory()}.
  */
 public interface RuleViolationFactory {
     /**

pmd-java/src/main/java/net/sourceforge/pmd/lang/java/rule/JavaRuleViolation.java

@@ -9,6 +9,7 @@ import java.util.Set;
 
 import net.sourceforge.pmd.Rule;
 import net.sourceforge.pmd.RuleContext;
+import net.sourceforge.pmd.RuleViolation;
 import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.java.ast.ASTCompilationUnit;
 import net.sourceforge.pmd.lang.java.ast.ASTFieldDeclaration;
@@ -37,7 +38,9 @@ import net.sourceforge.pmd.lang.symboltable.Scope;
  * <li>Variable name</li>
  * <li>Suppression indicator</li>
  * </ul>
+ * @deprecated See {@link RuleViolation}
  */
+@Deprecated
 public class JavaRuleViolation extends ParametricRuleViolation<JavaNode> {
 
     public JavaRuleViolation(Rule rule, RuleContext ctx, JavaNode node, String message, int beginLine, int endLine) {

pmd-java/src/main/java/net/sourceforge/pmd/lang/java/rule/JavaRuleViolationFactory.java

@@ -7,11 +7,17 @@ package net.sourceforge.pmd.lang.java.rule;
 import net.sourceforge.pmd.Rule;
 import net.sourceforge.pmd.RuleContext;
 import net.sourceforge.pmd.RuleViolation;
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.java.ast.JavaNode;
 import net.sourceforge.pmd.lang.rule.AbstractRuleViolationFactory;
 import net.sourceforge.pmd.lang.rule.RuleViolationFactory;
 
+/**
+ * @deprecated See {@link RuleViolationFactory}
+ */
+@Deprecated
+@InternalApi
 public final class JavaRuleViolationFactory extends AbstractRuleViolationFactory {
 
     public static final RuleViolationFactory INSTANCE = new JavaRuleViolationFactory();

pmd-java/src/main/java/net/sourceforge/pmd/lang/java/rule/errorprone/DaaRuleViolation.java

@@ -6,6 +6,7 @@ package net.sourceforge.pmd.lang.java.rule.errorprone;
 
 import net.sourceforge.pmd.Rule;
 import net.sourceforge.pmd.RuleContext;
+import net.sourceforge.pmd.RuleViolation;
 import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.java.ast.JavaNode;
 import net.sourceforge.pmd.lang.java.rule.JavaRuleViolation;
@@ -16,7 +17,9 @@ import net.sourceforge.pmd.lang.java.rule.JavaRuleViolation;
  *
  * @author Sven Jacob
  * @author Brian Remedios
+ * @deprecated See {@link RuleViolation}
  */
+@Deprecated
 public class DaaRuleViolation extends JavaRuleViolation {
 
     private final String variableName;

pmd-javascript/src/main/java/net/sourceforge/pmd/lang/ecmascript/rule/EcmascriptRuleViolationFactory.java

@@ -7,11 +7,18 @@ package net.sourceforge.pmd.lang.ecmascript.rule;
 import net.sourceforge.pmd.Rule;
 import net.sourceforge.pmd.RuleContext;
 import net.sourceforge.pmd.RuleViolation;
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.ecmascript.ast.EcmascriptNode;
 import net.sourceforge.pmd.lang.rule.AbstractRuleViolationFactory;
 import net.sourceforge.pmd.lang.rule.ParametricRuleViolation;
+import net.sourceforge.pmd.lang.rule.RuleViolationFactory;
 
+/**
+ * @deprecated See {@link RuleViolationFactory}
+ */
+@Deprecated
+@InternalApi
 public final class EcmascriptRuleViolationFactory extends AbstractRuleViolationFactory {
 
     public static final EcmascriptRuleViolationFactory INSTANCE = new EcmascriptRuleViolationFactory();
@@ -27,7 +34,7 @@ public final class EcmascriptRuleViolationFactory extends AbstractRuleViolationF
 
     @Override
     protected RuleViolation createRuleViolation(Rule rule, RuleContext ruleContext, Node node, String message,
-            int beginLine, int endLine) {
+                                                int beginLine, int endLine) {
         return null; // FIXME
     }
 }

pmd-jsp/src/main/java/net/sourceforge/pmd/lang/jsp/rule/JspRuleViolationFactory.java

@@ -7,12 +7,18 @@ package net.sourceforge.pmd.lang.jsp.rule;
 import net.sourceforge.pmd.Rule;
 import net.sourceforge.pmd.RuleContext;
 import net.sourceforge.pmd.RuleViolation;
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.jsp.ast.JspNode;
 import net.sourceforge.pmd.lang.rule.AbstractRuleViolationFactory;
 import net.sourceforge.pmd.lang.rule.ParametricRuleViolation;
 import net.sourceforge.pmd.lang.rule.RuleViolationFactory;
 
+/**
+ * @deprecated See {@link RuleViolationFactory}
+ */
+@Deprecated
+@InternalApi
 public final class JspRuleViolationFactory extends AbstractRuleViolationFactory {
 
     public static final RuleViolationFactory INSTANCE = new JspRuleViolationFactory();

pmd-plsql/src/main/java/net/sourceforge/pmd/lang/plsql/rule/PLSQLRuleViolationFactory.java

@@ -7,11 +7,17 @@ package net.sourceforge.pmd.lang.plsql.rule;
 import net.sourceforge.pmd.Rule;
 import net.sourceforge.pmd.RuleContext;
 import net.sourceforge.pmd.RuleViolation;
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.rule.AbstractRuleViolationFactory;
 import net.sourceforge.pmd.lang.rule.ParametricRuleViolation;
 import net.sourceforge.pmd.lang.rule.RuleViolationFactory;
 
+/**
+ * @deprecated See {@link RuleViolationFactory}
+ */
+@Deprecated
+@InternalApi
 public final class PLSQLRuleViolationFactory extends AbstractRuleViolationFactory {
 
     public static final RuleViolationFactory INSTANCE = new PLSQLRuleViolationFactory();

pmd-scala/src/main/java/net/sourceforge/pmd/lang/scala/rule/ScalaRuleViolationFactory.java

@@ -7,14 +7,17 @@ package net.sourceforge.pmd.lang.scala.rule;
 import net.sourceforge.pmd.Rule;
 import net.sourceforge.pmd.RuleContext;
 import net.sourceforge.pmd.RuleViolation;
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.rule.AbstractRuleViolationFactory;
 import net.sourceforge.pmd.lang.rule.ParametricRuleViolation;
 import net.sourceforge.pmd.lang.rule.RuleViolationFactory;
 
 /**
- * A RuleViolationFactory for Scala.
+ * @deprecated See {@link RuleViolationFactory}
  */
+@Deprecated
+@InternalApi
 public class ScalaRuleViolationFactory extends AbstractRuleViolationFactory {
     /**
      * The shared singleton of this RuleViolationFactory.

pmd-visualforce/src/main/java/net/sourceforge/pmd/lang/vf/rule/VfRuleViolationFactory.java

@@ -7,12 +7,18 @@ package net.sourceforge.pmd.lang.vf.rule;
 import net.sourceforge.pmd.Rule;
 import net.sourceforge.pmd.RuleContext;
 import net.sourceforge.pmd.RuleViolation;
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.rule.AbstractRuleViolationFactory;
 import net.sourceforge.pmd.lang.rule.ParametricRuleViolation;
 import net.sourceforge.pmd.lang.rule.RuleViolationFactory;
 import net.sourceforge.pmd.lang.vf.ast.VfNode;
 
+/**
+ * @deprecated See {@link RuleViolationFactory}
+ */
+@Deprecated
+@InternalApi
 public final class VfRuleViolationFactory extends AbstractRuleViolationFactory {
 
     public static final RuleViolationFactory INSTANCE = new VfRuleViolationFactory();

pmd-vm/src/main/java/net/sourceforge/pmd/lang/vm/rule/VmRuleViolationFactory.java

@@ -7,12 +7,18 @@ package net.sourceforge.pmd.lang.vm.rule;
 import net.sourceforge.pmd.Rule;
 import net.sourceforge.pmd.RuleContext;
 import net.sourceforge.pmd.RuleViolation;
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.rule.AbstractRuleViolationFactory;
 import net.sourceforge.pmd.lang.rule.ParametricRuleViolation;
 import net.sourceforge.pmd.lang.rule.RuleViolationFactory;
 import net.sourceforge.pmd.lang.vm.ast.AbstractVmNode;
 
+/**
+ * @deprecated See {@link RuleViolationFactory}
+ */
+@Deprecated
+@InternalApi
 public final class VmRuleViolationFactory extends AbstractRuleViolationFactory {
 
     public static final RuleViolationFactory INSTANCE = new VmRuleViolationFactory();

pmd-xml/src/main/java/net/sourceforge/pmd/lang/xml/rule/XmlRuleViolationFactory.java

@@ -7,12 +7,18 @@ package net.sourceforge.pmd.lang.xml.rule;
 import net.sourceforge.pmd.Rule;
 import net.sourceforge.pmd.RuleContext;
 import net.sourceforge.pmd.RuleViolation;
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.rule.AbstractRuleViolationFactory;
 import net.sourceforge.pmd.lang.rule.ParametricRuleViolation;
 import net.sourceforge.pmd.lang.rule.RuleViolationFactory;
 import net.sourceforge.pmd.lang.xml.ast.XmlNode;
 
+/**
+ * @deprecated See {@link RuleViolationFactory}
+ */
+@Deprecated
+@InternalApi
 public final class XmlRuleViolationFactory extends AbstractRuleViolationFactory {
 
     public static final RuleViolationFactory INSTANCE = new XmlRuleViolationFactory();