Merge pull request #4809 from adangel:issue-4348-internal-api

[core] Consolidate @internalapi classes #4809

docs/pages/pmd/projectdocs/decisions/adr-1.md

@@ -63,7 +63,7 @@ However, this also adds additional tasks, and it takes time to write down and do
 
 ## Change History
 
-2022-09-30: Status changed to "Accepted".
+2022-09-30: Status changed to "Accepted". ([#4072](https://github.com/pmd/pmd/pull/4072))
 
 2022-09-06: Added section "Change History" to the template. Added "Last updated" to "Status" section.
 

docs/pages/pmd/projectdocs/decisions/adr-2.md

@@ -66,6 +66,6 @@ Maintaining a polyglot code base with multiple languages is likely to be more ch
 
 ## Change History
 
-2022-09-30: Changed status to "Accepted".
+2022-09-30: Changed status to "Accepted". ([#4072](https://github.com/pmd/pmd/pull/4072))
 
 2022-07-28: Proposed initial version.

docs/pages/pmd/projectdocs/decisions/adr-3.md

@@ -5,8 +5,8 @@ permalink: pmd_projectdocs_decisions_adr_3.html
 sidebaractiveurl: /pmd_projectdocs_decisions.html
 adr: true
 # Proposed / Accepted / Deprecated / Superseded
-adr_status: "Proposed"
-last_updated: December 2023
+adr_status: "Accepted"
+last_updated: February 2024
 ---
 
 <!-- https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/templates/decision-record-template-by-michael-nygard/index.md -->
@@ -184,4 +184,6 @@ Non-concrete AST classes (like base classes or common interfaces) should follow
 
 ## Change History
 
+2024-02-01: Changed status to "Accepted". ([#4756](https://github.com/pmd/pmd/pull/4756))
+
 2023-12-01: Proposed initial version.

docs/pages/release_notes.md

@@ -180,6 +180,7 @@ The rules have been moved into categories with PMD 6.
   * [#4312](https://github.com/pmd/pmd/issues/4312): \[core] Remove unnecessary property `color` and system property `pmd.color` in `TextColorRenderer`
   * [#4313](https://github.com/pmd/pmd/issues/4313): \[core] Remove support for <lang>-<ruleset> hyphen notation for ruleset references
   * [#4314](https://github.com/pmd/pmd/issues/4314): \[core] Remove ruleset compatibility filter (RuleSetFactoryCompatibility) and CLI option `--no-ruleset-compatibility`
+  * [#4348](https://github.com/pmd/pmd/issues/4348): \[core] Consolidate @<!-- -->InternalApi classes
   * [#4378](https://github.com/pmd/pmd/issues/4378): \[core] Ruleset loading processes commented rules
   * [#4674](https://github.com/pmd/pmd/issues/4674): \[core] WARNING: Illegal reflective access by org.codehaus.groovy.reflection.CachedClass
   * [#4694](https://github.com/pmd/pmd/pull/4694):   \[core] Fix line/col numbers in TokenMgrError
@@ -267,20 +268,110 @@ in the migration guide for details.
     * {%jdoc core::reporting.RuleContext %}
     * {%jdoc core::reporting.RuleViolation %}
     * {%jdoc core::reporting.ViolationSuppressor %}
-    * {%jdoc core::reporting.ParametricRuleViolation %} (moved from `net.sourcceforge.pmd.lang.rule`)
   * {%jdoc core::lang.rule.xpath.XPathRule %} has been moved into subpackage {% jdoc_package core::lang.rule.xpath %}.
 
-**Internalized classes**
+**Internalized classes and interfaces and methods**
 
-These were marked as `@InternalApi` previously.
+The following classes/methods have been marked as @<!-- -->InternalApi before and are now moved into a `internal`
+package or made (package) private and are _not accessible_ anymore.
 
 * pmd-core
-  * `RuleFactory`: moved from `net.sourceforge.pmd.rules` into subpackage `lang.rule`.
+  * `net.sourceforge.pmd.cache.AbstractAnalysisCache` (moved to internal, now package private)
+  * `net.sourceforge.pmd.cache.AnalysisCache` (moved to internal)
+  * `net.sourceforge.pmd.cache.AnalysisCacheListener` (moved to internal)
+  * `net.sourceforge.pmd.cache.AnalysisResult` (moved to internal)
+  * `net.sourceforge.pmd.cache.CachedRuleMapper` (moved to internal, now package private)
+  * `net.sourceforge.pmd.cache.CachedRuleViolation` (moved to internal, now package private)
+  * `net.sourceforge.pmd.cache.ChecksumAware` (moved to internal)
+  * `net.sourceforge.pmd.cache.FileAnalysisCache` (moved to internal)
+  * `net.sourceforge.pmd.cache.NoopAnalysisCache` (moved to internal)
+  * `net.sourceforge.pmd.util.ResourceLoader` (moved to internal)
+  * {%jdoc !!core::cpd.Tokens %}
+    * Constructor is now package private.
+  * {%jdoc !!core::lang.LanguageProcessor.AnalysisTask %}
+    * Constructor is now package private.
+    * Method `withFiles(java.util.List)` is now package private. Note: it was not previously marked with @<!-- -->InternalApi.
+  * {%jdoc !!core::lang.rule.RuleTargetSelector %}
+    * Method `isRuleChain()` has been removed.
+  * {%jdoc !!core::renderers.AbstractAccumulatingRenderer %}
+    * {%jdoc core::renderers.AbstractAccumulatingRenderer#renderFileReport(core::reporting.Report) %} - this method is now final
+      and can't be overridden anymore.
+  * {%jdoc !!core::reporting.Report %}
+    * Constructor as well as the methods `addRuleViolation`, `addConfigError`, `addError` are now private.
+  * {%jdoc !!core::reporting.RuleContext %}
+    * Method `getRule()` is now package private.
+    * Method `create(FileAnalysisListener listener, Rule rule)` has been removed.
+  * `net.sourceforge.pmd.rules.RuleFactory`: moved into subpackage `lang.rule` and made package private.
     It has now been hidden completely from public API.
-  * Many types have been moved from the base package `net.sourceforge.pmd` into subpackage `lang.rule.internal`.
-      * `RuleSetReference`
-      * `RuleSetReferenceId`
-      * `RuleSets`
+  * Many types have been moved from into subpackage `lang.rule.internal`.
+    * `net.sourceforge.pmd.RuleSetReference`
+    * `net.sourceforge.pmd.RuleSetReferenceId`
+    * `net.sourceforge.pmd.RuleSets`
+  * `net.sourceforge.pmd.lang.rule.ParametricRuleViolation` is now package private and moved to `net.sourceforge.pmd.reporting.ParametricRuleViolation`.
+    The only public API is {%jdoc core::reporting.RuleViolation %}.
+  * {%jdoc !!core::lang.rule.RuleSet %}
+    * Method `applies(Rule,LanguageVersion)` is now package private.
+    * Method `applies(TextFile)` has been removed.
+    * Method `applies(FileId)` is now package private.
+  * {%jdoc !!core::lang.rule.RuleSetLoader %}
+    * Method `loadRuleSetsWithoutException(java.util.List)` is now package private.
+  * {%jdoc !!core::lang.rule.RuleSetLoadException %}
+    * All constructors are package private now.
+  * {%jdoc !!core::lang.ast.LexException %} - the constructor `LexException(boolean, String, int, int, String, char)` is now package private.
+    It is only used by JavaCC-generated token managers.
+  * {%jdoc !!core::PMDConfiguration %}
+    * Method `setAnalysisCache(AnalysisCache)` is now package private. Use {%jdoc core::PMDConfiguration#setAnalysisCacheLocation(java.lang.String) %} instead.
+    * Method `getAnalysisCache()` is now package private.
+  * {%jdoc !!core::lang.document.FileCollector %}
+    * Method `newCollector(LanguageVersionDiscoverer, PmdReporter)` is now package private.
+    * Method `newCollector(PmdReporter)` is now package private.
+    * In order to create a FileCollector, use {%jdoc core::PmdAnalysis#files() %} instead.
+  * {%jdoc !!core::lang.rule.xpath.Attribute %}
+    * Method `replacementIfDeprecated()` is now package private.
+  * `net.sourceforge.pmd.properties.PropertyTypeId` - moved in subpackage `internal`.
+  * {%jdoc !!core::properties.PropertyDescriptor %} - method `getTypeId()` is now package private.
+* pmd-ant
+  * {%jdoc !!ant::ant.Formatter %}
+    * Method `getRenderer()` has been removed.
+    * Method `start(String)` is private now.
+    * Method `end(Report)` has been removed.
+    * Method `isNoOutputSupplied()` is now package private.
+    * Method `newListener(Project)` is now package private.
+  * {%jdoc !!ant::ant.PMDTask %}
+    * Method `getRelativizeRoots()` has been removed.
+  * `net.sourceforge.pmd.ant.ReportException` is now package private. Note: It was not marked with @<!-- -->InternalApi before.
+* pmd-apex
+  * {%jdoc !!apex::ast.ApexNode %}
+    * Method `getNode()` has been removed. It was only deprecated before and not marked with @<!-- -->InternalApi.
+      However, it gave access to the wrapped Jorje node and was thus internal API.
+  * {%jdoc !!apex::ast.AbstractApexNode %}
+    * Method `getNode()` is now package private.
+  * {%jdoc !!apex::multifile.ApexMultifileAnalysis %}
+    * Constructor is now package private.
+  * `net.sourceforge.pmd.lang.apex.rule.design.AbstractNcssCountRule` (now package private)
+  * `net.sourceforge.pmd.lang.apex.rule.AbstractApexUnitTestRule` (moved to package `net.sourceforge.pmd.apex.rule.bestpractices`, now package private)
+* pmd-java
+  * `net.sourceforge.pmd.lang.java.rule.AbstractIgnoredAnnotationRule` (moved to internal)
+  * `net.sourceforge.pmd.lang.java.types.ast.LazyTypeResolver` (moved to internal)
+  * {%jdoc !!java::types.JMethodSig %}
+    * Method `internalApi()` has been removed.
+  * {%jdoc !!java::types.TypeOps %}
+    * Method `isSameTypeInInference(JTypeMirror,JTypeMirror)` is now package private.
+* pmd-jsp
+  * {%jdoc !!jsp::ast.JspParser %}
+    * Method `getTokenBehavior()` has been removed.
+* pmd-modelica
+  * {%jdoc !!modelica::ast.InternalApiBridge %} renamed from `InternalModelicaNodeApi`.
+  * {%jdoc !!modelica::resolver.InternalApiBridge %} renamed from `InternalModelicaResolverApi`.
+  * `net.sourceforge.pmd.lang.modelica.resolver.ModelicaSymbolFacade` has been removed.
+  * `net.sourceforge.pmd.lang.modelica.resolver.ResolutionContext` (moved to internal)
+  * `net.sourceforge.pmd.lang.modelica.resolver.ResolutionState` (moved to internal). Note: it was not previously marked with @<!-- -->InternalApi.
+  * `net.sourceforge.pmd.lang.modelica.resolver.Watchdog` (moved to internal). Note: it was not previously marked with @<!-- -->InternalApi.
+* pmd-plsql
+  * `net.sourceforge.pmd.lang.plsql.rule.design.AbstractNcssCountRule` is now package private.
+* pmd-scala
+  * {%jdoc !!scala::ScalaLanguageModule %}
+    * Method `dialectOf(LanguageVersion)` has been removed.
 
 **Removed classes and methods (previously deprecated)**
 
@@ -309,6 +400,9 @@ The following previously deprecated classes have been removed:
 
 **Renamed classes, interfaces**
 
+* pmd-core
+  * {%jdoc core::util.log.PmdReporter %} - has been renamed from `net.sourceforge.pmd.util.log.MessageReporter`
+
 * pmd-java
   * The interface `AccessNode` has been renamed to {% jdoc java::lang.ast.ModifierOwner %}. This is only relevant
     for Java rules, which use that type directly e.g. through downcasting.
@@ -771,6 +865,7 @@ See also [Detailed Release Notes for PMD 7]({{ baseurl }}pmd_release_notes_pmd7.
     * [#4313](https://github.com/pmd/pmd/issues/4313): \[core] Remove support for &lt;lang&gt;-&lt;ruleset&gt; hyphen notation for ruleset references
     * [#4314](https://github.com/pmd/pmd/issues/4314): \[core] Remove ruleset compatibility filter (RuleSetFactoryCompatibility) and CLI option `--no-ruleset-compatibility`
     * [#4323](https://github.com/pmd/pmd/issues/4323): \[core] Refactor CPD integration
+    * [#4348](https://github.com/pmd/pmd/issues/4348): \[core] Consolidate @<!-- -->InternalApi classes
     * [#4353](https://github.com/pmd/pmd/pull/4353):   \[core] Micro optimizations for Node API
     * [#4365](https://github.com/pmd/pmd/pull/4365):   \[core] Improve benchmarking
     * [#4397](https://github.com/pmd/pmd/pull/4397):   \[core] Refactor CPD

docs/pages/release_notes_old.md

@@ -225,8 +225,8 @@ The following previously deprecated methods have been removed:
 * pmd-core
   * `net.sourceforge.pmd.properties.PropertyBuilder.GenericCollectionPropertyBuilder#delim(char)`
   * `net.sourceforge.pmd.properties.PropertySource#setProperty(...)`
-  * `net.sourceforge.pmd.properties.PropertyTypeId#factoryFor(...)`
-  * `net.sourceforge.pmd.properties.PropertyTypeId#typeIdFor(...)`
+  * `net.sourceforge.pmd.properties.internal.PropertyTypeId#factoryFor(...)`
+  * `net.sourceforge.pmd.properties.internal.PropertyTypeId#typeIdFor(...)`
   * `net.sourceforge.pmd.properties.PropertyDescriptor`: removed methods errorFor, type, isMultiValue,
      uiOrder, compareTo, isDefinedExternally, valueFrom, asDelimitedString
 

docs/pages/release_notes_pmd7.md

@@ -816,8 +816,8 @@ The following previously deprecated methods have been removed:
 * pmd-core
   * `net.sourceforge.pmd.properties.PropertyBuilder.GenericCollectionPropertyBuilder#delim(char)`
   * `net.sourceforge.pmd.properties.PropertySource#setProperty(...)`
-  * `net.sourceforge.pmd.properties.PropertyTypeId#factoryFor(...)`
-  * `net.sourceforge.pmd.properties.PropertyTypeId#typeIdFor(...)`
+  * `net.sourceforge.pmd.properties.internal.PropertyTypeId#factoryFor(...)`
+  * `net.sourceforge.pmd.properties.internal.PropertyTypeId#typeIdFor(...)`
   * `net.sourceforge.pmd.properties.PropertyDescriptor`: removed methods errorFor, type, isMultiValue,
     uiOrder, compareTo, isDefinedExternally, valueFrom, asDelimitedString
 
@@ -900,7 +900,7 @@ The following classes have been removed:
 ##### Internal APIs
 
 * {% jdoc core::cpd.Tokens %}
-* {% jdoc core::net.sourceforge.pmd.properties.PropertyTypeId %}
+* {% jdoc core::net.sourceforge.pmd.properties.internal.PropertyTypeId %}
 
 ##### Deprecated API
 

javacc-wrapper.xml

@@ -283,7 +283,7 @@
         <!-- Use own LexException instead of JavaCC's TokenMgrError -->
         <replaceregexp>
             <regexp pattern='throw new TokenMgrError\(EOFSeen' />
-            <substitution expression='throw new net.sourceforge.pmd.lang.ast.LexException(EOFSeen' />
+            <substitution expression='throw net.sourceforge.pmd.lang.ast.InternalApiBridge.newLexException(EOFSeen' />
             <file name="${tokenmgr-file}" />
         </replaceregexp>
 

pmd-ant/src/main/java/net/sourceforge/pmd/ant/Formatter.java

@@ -26,7 +26,6 @@
 import org.apache.tools.ant.Project;
 import org.apache.tools.ant.types.Parameter;
 
-import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.internal.util.IOUtil;
 import net.sourceforge.pmd.lang.document.TextFile;
 import net.sourceforge.pmd.renderers.Renderer;
@@ -35,9 +34,22 @@
 import net.sourceforge.pmd.reporting.FileNameRenderer;
 import net.sourceforge.pmd.reporting.GlobalAnalysisListener;
 import net.sourceforge.pmd.reporting.ListenerInitializer;
-import net.sourceforge.pmd.reporting.Report;
 
-@InternalApi
+/**
+ * Part of PMD Ant task configuration. Setters of this class are interpreted by Ant as properties
+ * settable in the XML. This is therefore published API.
+ *
+ * <p>This class is used to configure a specific {@link Renderer} for outputting the violations. This is called
+ * a formatter in PMD Ant task configuration and might look like this:
+ *
+ * <pre>{@code
+ * <pmd>
+ *   <formatter type="html" toFile="${build}/pmd_report.html"/>
+ * </pmd>
+ * }</pre>
+ *
+ * @see PMDTask#addFormatter(Formatter)
+ */
 public class Formatter {
 
     private File toFile;
@@ -68,15 +80,7 @@ public void addConfiguredParam(Parameter parameter) {
         this.parameters.add(parameter);
     }
 
-    @Deprecated
-    @InternalApi
-    public Renderer getRenderer() {
-        return renderer;
-    }
-
-    @Deprecated
-    @InternalApi
-    public void start(String baseDir) {
+    private void start(String baseDir) {
 
         Properties properties = createProperties();
 
@@ -122,25 +126,7 @@ public void start(String baseDir) {
         }
     }
 
-    @Deprecated
-    @InternalApi
-    public void end(Report errorReport) {
-        try {
-            renderer.renderFileReport(errorReport);
-            renderer.end();
-            if (toConsole) {
-                writer.flush();
-            } else {
-                writer.close();
-            }
-        } catch (IOException ioe) {
-            throw new BuildException(ioe.getMessage(), ioe);
-        }
-    }
-
-    @Deprecated
-    @InternalApi
-    public boolean isNoOutputSupplied() {
+    boolean isNoOutputSupplied() {
         return toFile == null && !toConsole;
     }
 
@@ -248,12 +234,8 @@ private static String getNativeConsoleEncoding() {
         return null;
     }
 
-    @Deprecated
-    @InternalApi
-    public GlobalAnalysisListener newListener(Project project) throws IOException {
+    GlobalAnalysisListener newListener(Project project) throws IOException {
         start(project.getBaseDir().toString());
-        Renderer renderer = getRenderer();
-
         return new GlobalAnalysisListener() {
             final GlobalAnalysisListener listener = renderer.newListener();
 

pmd-ant/src/main/java/net/sourceforge/pmd/ant/InternalApiBridge.java

@@ -0,0 +1,32 @@
+/*
+ * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
+ */
+
+package net.sourceforge.pmd.ant;
+
+import java.io.IOException;
+
+import org.apache.tools.ant.Project;
+
+import net.sourceforge.pmd.annotation.InternalApi;
+import net.sourceforge.pmd.reporting.GlobalAnalysisListener;
+
+/**
+ * Internal API.
+ *
+ * <p>Acts as a bridge between outer parts of PMD and the restricted access
+ * internal API of this package.
+ *
+ * <p><b>None of this is published API, and compatibility can be broken anytime!</b>
+ * Use this only at your own risk.
+ *
+ * @apiNote Internal API
+ */
+@InternalApi
+public final class InternalApiBridge {
+    private InternalApiBridge() {}
+
+    public static GlobalAnalysisListener newListener(Formatter formatter, Project project) throws IOException {
+        return formatter.newListener(project);
+    }
+}

pmd-ant/src/main/java/net/sourceforge/pmd/ant/PMDTask.java

@@ -4,7 +4,6 @@
 
 package net.sourceforge.pmd.ant;
 
-import java.nio.file.Paths;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Iterator;
@@ -15,9 +14,7 @@
 import org.apache.tools.ant.types.FileSet;
 import org.apache.tools.ant.types.Path;
 import org.apache.tools.ant.types.Reference;
-import org.apache.tools.ant.types.Resource;
 
-import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.ant.internal.PMDTaskImpl;
 import net.sourceforge.pmd.lang.rule.RulePriority;
 
@@ -290,15 +287,4 @@ public void addRelativizePathsWith(Path relativizePathsWith) {
     public List<Path> getRelativizePathsWith() {
         return relativizePathsWith;
     }
-
-    @InternalApi
-    public List<java.nio.file.Path> getRelativizeRoots() {
-        List<java.nio.file.Path> paths = new ArrayList<>();
-        for (Path path : getRelativizePathsWith()) {
-            for (Resource resource : path) {
-                paths.add(Paths.get(resource.toString()));
-            }
-        }
-        return paths;
-    }
 }

pmd-ant/src/main/java/net/sourceforge/pmd/ant/ReportException.java

@@ -6,11 +6,12 @@
 
 /**
  * @author Philippe T'Seyen
+ * @apiNote Internal API
  */
-public class ReportException extends RuntimeException {
+class ReportException extends RuntimeException {
     private static final long serialVersionUID = 6043174086675858209L;
 
-    public ReportException(Throwable cause) {
+    ReportException(Throwable cause) {
         super(cause);
     }
 }