Merge pull request #4354 from oowekyala:pmd7-utility-classes

[core] Move utility classes around #4354

docs/pages/7_0_0_release_notes.md

@@ -247,6 +247,7 @@ The following previously deprecated rules have been finally removed:
     * [#4080](https://github.com/pmd/pmd/issues/4080): \[ant] Split off Ant integration into a new submodule 
 * core
     * [#2234](https://github.com/pmd/pmd/issues/2234): \[core] Consolidate PMD CLI into a single command
+    * [#2873](https://github.com/pmd/pmd/issues/2873): \[core] Utility classes in pmd 7
     * [#3203](https://github.com/pmd/pmd/issues/3203): \[core] Replace RuleViolationFactory implementations with ViolationDecorator
     * [#3902](https://github.com/pmd/pmd/issues/3902): \[core] Violation decorators
     * [#4035](https://github.com/pmd/pmd/issues/4035): \[core] ConcurrentModificationException in DefaultRuleViolationFactory
@@ -354,6 +355,19 @@ The following previously deprecated rules have been finally removed:
   has been moved into the same package {% jdoc_package ant::ant %}. You'll need to update your taskdef entries in your
   build.xml files with the FQCN {% jdoc !!ant::ant.CPDTask %} if you use it anywhere.
 
+* Utility classes in {% jdoc_package core::util %}, that have previously marked as `@InternalApi` have been finally
+  moved to {% jdoc_package core::internal.util %}. This includes ClasspathClassLoader, FileFinder, FileUtil, and
+  IOUtil.
+
+* The following utility classes in {% jdoc_package core::util %} are now considered public API:
+  * {% jdoc core::util.AssertionUtil %}
+  * {% jdoc core::util.CollectionUtil %}
+  * {% jdoc core::util.ContextedAssertionError %}
+  * {% jdoc core::util.ContextedStackOverflowError %}
+  * {% jdoc core::util.GraphUtil %}
+  * {% jdoc core::util.IteratorUtil %}
+  * {% jdoc core::util.StringUtil %}
+
 #### Metrics framework
 
 The metrics framework has been made simpler and more general.

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

@@ -27,12 +27,12 @@ import org.apache.tools.ant.types.Parameter;
 
 import net.sourceforge.pmd.Report;
 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;
 import net.sourceforge.pmd.renderers.RendererFactory;
 import net.sourceforge.pmd.reporting.FileAnalysisListener;
 import net.sourceforge.pmd.reporting.GlobalAnalysisListener;
-import net.sourceforge.pmd.util.IOUtil;
 
 @InternalApi
 public class Formatter {

pmd-ant/src/main/java/net/sourceforge/pmd/ant/internal/PMDTaskImpl.java

@@ -28,6 +28,8 @@ import net.sourceforge.pmd.ant.Formatter;
 import net.sourceforge.pmd.ant.PMDTask;
 import net.sourceforge.pmd.ant.SourceLanguage;
 import net.sourceforge.pmd.internal.Slf4jSimpleConfiguration;
+import net.sourceforge.pmd.internal.util.ClasspathClassLoader;
+import net.sourceforge.pmd.internal.util.IOUtil;
 import net.sourceforge.pmd.lang.Language;
 import net.sourceforge.pmd.lang.LanguageRegistry;
 import net.sourceforge.pmd.lang.LanguageVersion;
@@ -36,8 +38,6 @@ import net.sourceforge.pmd.reporting.FileAnalysisListener;
 import net.sourceforge.pmd.reporting.GlobalAnalysisListener;
 import net.sourceforge.pmd.reporting.ReportStats;
 import net.sourceforge.pmd.reporting.ReportStatsListener;
-import net.sourceforge.pmd.util.ClasspathClassLoader;
-import net.sourceforge.pmd.util.IOUtil;
 
 public class PMDTaskImpl {
 

pmd-ant/src/test/java/net/sourceforge/pmd/ant/AbstractAntTest.java

@@ -19,7 +19,7 @@ import org.apache.tools.ant.ProjectHelper;
 import org.junit.jupiter.api.AfterAll;
 
 import net.sourceforge.pmd.internal.Slf4jSimpleConfiguration;
-import net.sourceforge.pmd.util.IOUtil;
+import net.sourceforge.pmd.internal.util.IOUtil;
 
 class AbstractAntTest {
     protected Project project;

pmd-ant/src/test/java/net/sourceforge/pmd/ant/PMDTaskTest.java

@@ -20,7 +20,7 @@ import org.apache.tools.ant.BuildException;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
-import net.sourceforge.pmd.util.IOUtil;
+import net.sourceforge.pmd.internal.util.IOUtil;
 
 class PMDTaskTest extends AbstractAntTest {
 

pmd-apex/src/test/java/net/sourceforge/pmd/cpd/ApexCpdTest.java

@@ -14,8 +14,8 @@ import java.util.Iterator;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
+import net.sourceforge.pmd.internal.util.IOUtil;
 import net.sourceforge.pmd.lang.apex.ApexLanguageModule;
-import net.sourceforge.pmd.util.IOUtil;
 
 class ApexCpdTest {
     private File testdir;

pmd-apex/src/test/java/net/sourceforge/pmd/lang/apex/ast/ApexParserTest.java

@@ -20,9 +20,9 @@ import java.util.List;
 
 import org.junit.jupiter.api.Test;
 
+import net.sourceforge.pmd.internal.util.IOUtil;
 import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.document.FileLocation;
-import net.sourceforge.pmd.util.IOUtil;
 
 class ApexParserTest extends ApexParserTestBase {
 
@@ -182,7 +182,7 @@ class ApexParserTest extends ApexParserTestBase {
     @Test
     void stackOverflowDuringClassParsing() throws Exception {
         String source = IOUtil.readToString(ApexParserTest.class.getResourceAsStream("StackOverflowClass.cls"),
-                StandardCharsets.UTF_8);
+                                            StandardCharsets.UTF_8);
         ASTUserClassOrInterface<?> rootNode = parse(source);
         assertNotNull(rootNode);
 

pmd-apex/src/test/java/net/sourceforge/pmd/lang/apex/multifile/ApexMultifileAnalysisTest.java

@@ -19,7 +19,7 @@ import org.checkerframework.checker.nullness.qual.NonNull;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
 
-import net.sourceforge.pmd.util.IOUtil;
+import net.sourceforge.pmd.internal.util.IOUtil;
 
 import com.github.stefanbirkner.systemlambda.SystemLambda;
 

pmd-cli/src/main/java/net/sourceforge/pmd/cli/commands/internal/CpdCommand.java

@@ -24,7 +24,7 @@ import net.sourceforge.pmd.cpd.CPDReport;
 import net.sourceforge.pmd.cpd.Language;
 import net.sourceforge.pmd.cpd.Tokenizer;
 import net.sourceforge.pmd.internal.LogMessages;
-import net.sourceforge.pmd.util.IOUtil;
+import net.sourceforge.pmd.internal.util.IOUtil;
 
 import picocli.CommandLine.Command;
 import picocli.CommandLine.Option;

pmd-cli/src/test/java/net/sourceforge/pmd/cli/PmdCliTest.java

@@ -42,9 +42,9 @@ import org.junit.jupiter.api.io.TempDir;
 import net.sourceforge.pmd.RuleContext;
 import net.sourceforge.pmd.cli.internal.CliExitCode;
 import net.sourceforge.pmd.internal.Slf4jSimpleConfiguration;
+import net.sourceforge.pmd.internal.util.IOUtil;
 import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.rule.MockRule;
-import net.sourceforge.pmd.util.IOUtil;
 
 import com.github.stefanbirkner.systemlambda.SystemLambda;
 

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

@@ -26,13 +26,13 @@ import net.sourceforge.pmd.cache.AnalysisCache;
 import net.sourceforge.pmd.cache.FileAnalysisCache;
 import net.sourceforge.pmd.cache.NoopAnalysisCache;
 import net.sourceforge.pmd.cli.PmdParametersParseResult;
-import net.sourceforge.pmd.internal.util.AssertionUtil;
+import net.sourceforge.pmd.internal.util.ClasspathClassLoader;
 import net.sourceforge.pmd.lang.LanguageRegistry;
 import net.sourceforge.pmd.lang.LanguageVersion;
 import net.sourceforge.pmd.lang.LanguageVersionDiscoverer;
 import net.sourceforge.pmd.renderers.Renderer;
 import net.sourceforge.pmd.renderers.RendererFactory;
-import net.sourceforge.pmd.util.ClasspathClassLoader;
+import net.sourceforge.pmd.util.AssertionUtil;
 import net.sourceforge.pmd.util.log.MessageReporter;
 import net.sourceforge.pmd.util.log.internal.SimpleMessageReporter;
 

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

@@ -26,8 +26,9 @@ import net.sourceforge.pmd.benchmark.TimedOperationCategory;
 import net.sourceforge.pmd.cache.AnalysisCacheListener;
 import net.sourceforge.pmd.cache.NoopAnalysisCache;
 import net.sourceforge.pmd.internal.LogMessages;
-import net.sourceforge.pmd.internal.util.AssertionUtil;
+import net.sourceforge.pmd.internal.util.ClasspathClassLoader;
 import net.sourceforge.pmd.internal.util.FileCollectionUtil;
+import net.sourceforge.pmd.internal.util.IOUtil;
 import net.sourceforge.pmd.lang.Language;
 import net.sourceforge.pmd.lang.LanguageVersion;
 import net.sourceforge.pmd.lang.LanguageVersionDiscoverer;
@@ -39,8 +40,7 @@ import net.sourceforge.pmd.reporting.GlobalAnalysisListener;
 import net.sourceforge.pmd.reporting.ListenerInitializer;
 import net.sourceforge.pmd.reporting.ReportStats;
 import net.sourceforge.pmd.reporting.ReportStatsListener;
-import net.sourceforge.pmd.util.ClasspathClassLoader;
-import net.sourceforge.pmd.util.IOUtil;
+import net.sourceforge.pmd.util.AssertionUtil;
 import net.sourceforge.pmd.util.StringUtil;
 import net.sourceforge.pmd.util.log.MessageReporter;
 

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

@@ -29,6 +29,7 @@ import org.w3c.dom.Document;
 import org.w3c.dom.Element;
 import org.w3c.dom.Text;
 
+import net.sourceforge.pmd.internal.util.IOUtil;
 import net.sourceforge.pmd.lang.Language;
 import net.sourceforge.pmd.lang.LanguageVersion;
 import net.sourceforge.pmd.lang.rule.RuleReference;
@@ -36,7 +37,6 @@ import net.sourceforge.pmd.lang.rule.XPathRule;
 import net.sourceforge.pmd.properties.PropertyDescriptor;
 import net.sourceforge.pmd.properties.PropertyDescriptorField;
 import net.sourceforge.pmd.properties.PropertyTypeId;
-import net.sourceforge.pmd.util.IOUtil;
 
 /**
  * This class represents a way to serialize a RuleSet to an XML configuration

pmd-core/src/main/java/net/sourceforge/pmd/cache/AbstractAnalysisCache.java

@@ -33,9 +33,9 @@ import net.sourceforge.pmd.benchmark.TimeTracker;
 import net.sourceforge.pmd.benchmark.TimedOperation;
 import net.sourceforge.pmd.benchmark.TimedOperationCategory;
 import net.sourceforge.pmd.cache.internal.ClasspathFingerprinter;
+import net.sourceforge.pmd.internal.util.IOUtil;
 import net.sourceforge.pmd.lang.document.TextDocument;
 import net.sourceforge.pmd.reporting.FileAnalysisListener;
-import net.sourceforge.pmd.util.IOUtil;
 
 /**
  * Abstract implementation of the analysis cache. Handles all operations, except for persistence.

pmd-core/src/main/java/net/sourceforge/pmd/cache/internal/RawFileFingerprinter.java

@@ -16,7 +16,7 @@ import java.util.zip.Checksum;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import net.sourceforge.pmd.util.IOUtil;
+import net.sourceforge.pmd.internal.util.IOUtil;
 
 /**
  * Base fingerprinter for raw files.

pmd-core/src/main/java/net/sourceforge/pmd/cpd/CPD.java

@@ -23,10 +23,10 @@ import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 import net.sourceforge.pmd.annotation.Experimental;
+import net.sourceforge.pmd.internal.util.FileFinder;
+import net.sourceforge.pmd.internal.util.FileUtil;
+import net.sourceforge.pmd.internal.util.IOUtil;
 import net.sourceforge.pmd.lang.ast.TokenMgrError;
-import net.sourceforge.pmd.util.FileFinder;
-import net.sourceforge.pmd.util.FileUtil;
-import net.sourceforge.pmd.util.IOUtil;
 import net.sourceforge.pmd.util.database.DBMSMetadata;
 import net.sourceforge.pmd.util.database.DBURI;
 import net.sourceforge.pmd.util.database.SourceObject;

pmd-core/src/main/java/net/sourceforge/pmd/cpd/CPDConfiguration.java

@@ -22,8 +22,8 @@ import java.util.Set;
 
 import net.sourceforge.pmd.AbstractConfiguration;
 import net.sourceforge.pmd.cpd.renderer.CPDReportRenderer;
-import net.sourceforge.pmd.util.FileFinder;
-import net.sourceforge.pmd.util.FileUtil;
+import net.sourceforge.pmd.internal.util.FileFinder;
+import net.sourceforge.pmd.internal.util.FileUtil;
 
 /**
  *

pmd-core/src/main/java/net/sourceforge/pmd/cpd/SourceCode.java

@@ -14,7 +14,7 @@ import java.nio.file.Files;
 import java.util.ArrayList;
 import java.util.List;
 
-import net.sourceforge.pmd.util.IOUtil;
+import net.sourceforge.pmd.internal.util.IOUtil;
 
 public class SourceCode {
 

pmd-core/src/main/java/net/sourceforge/pmd/cpd/token/internal/BaseTokenFilter.java

@@ -4,7 +4,7 @@
 
 package net.sourceforge.pmd.cpd.token.internal;
 
-import static net.sourceforge.pmd.internal.util.IteratorUtil.AbstractIterator;
+import static net.sourceforge.pmd.util.IteratorUtil.AbstractIterator;
 
 import java.util.ConcurrentModificationException;
 import java.util.Iterator;

pmd-core/src/main/java/net/sourceforge/pmd/internal/util/ClasspathClassLoader.java

@@ -1,8 +1,8 @@
-/**
+/*
  * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
  */
 
-package net.sourceforge.pmd.util;
+package net.sourceforge.pmd.internal.util;
 
 import java.io.BufferedReader;
 import java.io.File;
@@ -19,8 +19,7 @@ import org.apache.commons.lang3.StringUtils;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import net.sourceforge.pmd.annotation.InternalApi;
-import net.sourceforge.pmd.internal.util.AssertionUtil;
+import net.sourceforge.pmd.util.AssertionUtil;
 
 /**
  * Create a ClassLoader which loads classes using a CLASSPATH like String. If
@@ -28,10 +27,7 @@ import net.sourceforge.pmd.internal.util.AssertionUtil;
  * the file will be read with each line representing an path on the classpath.
  *
  * @author Edwin Chan
- * @deprecated Is internal API
  */
-@InternalApi
-@Deprecated
 public class ClasspathClassLoader extends URLClassLoader {
 
     private static final Logger LOG = LoggerFactory.getLogger(ClasspathClassLoader.class);
@@ -105,10 +101,10 @@ public class ClasspathClassLoader extends URLClassLoader {
 
     @Override
     public String toString() {
-        return new StringBuilder(getClass().getSimpleName())
-                .append("[[")
-                .append(StringUtils.join(getURLs(), ":"))
-                .append("] parent: ").append(getParent()).append(']').toString();
+        return getClass().getSimpleName()
+            + "[["
+            + StringUtils.join(getURLs(), ":")
+            + "] parent: " + getParent() + ']';
     }
 
     @Override

pmd-core/src/main/java/net/sourceforge/pmd/internal/util/FileCollectionUtil.java

@@ -17,8 +17,6 @@ import org.slf4j.LoggerFactory;
 
 import net.sourceforge.pmd.PMDConfiguration;
 import net.sourceforge.pmd.lang.document.FileCollector;
-import net.sourceforge.pmd.util.FileUtil;
-import net.sourceforge.pmd.util.IOUtil;
 import net.sourceforge.pmd.util.database.DBMSMetadata;
 import net.sourceforge.pmd.util.database.DBURI;
 import net.sourceforge.pmd.util.database.SourceObject;

pmd-core/src/main/java/net/sourceforge/pmd/internal/util/FileFinder.java

@@ -1,8 +1,8 @@
-/**
+/*
  * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
  */
 
-package net.sourceforge.pmd.util;
+package net.sourceforge.pmd.internal.util;
 
 import java.io.File;
 import java.io.FilenameFilter;
@@ -11,14 +11,9 @@ import java.util.Arrays;
 import java.util.Comparator;
 import java.util.List;
 
-import net.sourceforge.pmd.annotation.InternalApi;
-
 /**
  * A utility class for finding files within a directory.
- * @deprecated Is internal API
  */
-@Deprecated
-@InternalApi
 public class FileFinder {
 
     private FilenameFilter filter;

pmd-core/src/main/java/net/sourceforge/pmd/internal/util/FileUtil.java

@@ -1,8 +1,8 @@
-/**
+/*
  * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
  */
 
-package net.sourceforge.pmd.util;
+package net.sourceforge.pmd.internal.util;
 
 import java.io.File;
 import java.io.FileNotFoundException;
@@ -21,15 +21,9 @@ import java.util.stream.Collectors;
 import org.apache.commons.lang3.StringUtils;
 import org.checkerframework.checker.nullness.qual.NonNull;
 
-import net.sourceforge.pmd.annotation.InternalApi;
-
 /**
  * This is a utility class for working with Files.
- *
- * @deprecated Is internal API
  */
-@Deprecated
-@InternalApi
 public final class FileUtil {
 
     private FileUtil() {

pmd-core/src/main/java/net/sourceforge/pmd/internal/util/IOUtil.java

@@ -1,8 +1,8 @@
-/**
+/*
  * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
  */
 
-package net.sourceforge.pmd.util;
+package net.sourceforge.pmd.internal.util;
 
 import java.io.Closeable;
 import java.io.File;
@@ -34,15 +34,10 @@ import java.util.Objects;
 import org.apache.commons.lang3.StringUtils;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
-import net.sourceforge.pmd.annotation.InternalApi;
-
 /**
  *
  * @author Brian Remedios
- * @deprecated Is internal API
  */
-@InternalApi
-@Deprecated
 public final class IOUtil {
     /**
      * Unicode BOM character. Replaces commons io ByteOrderMark.

pmd-core/src/main/java/net/sourceforge/pmd/internal/util/PredicateUtil.java

@@ -5,8 +5,8 @@
 package net.sourceforge.pmd.internal.util;
 
 
-import static net.sourceforge.pmd.internal.util.AssertionUtil.requireOver1;
-import static net.sourceforge.pmd.internal.util.AssertionUtil.requireParamNotNull;
+import static net.sourceforge.pmd.util.AssertionUtil.requireOver1;
+import static net.sourceforge.pmd.util.AssertionUtil.requireParamNotNull;
 
 import java.util.Collection;
 import java.util.function.Predicate;
@@ -14,6 +14,8 @@ import java.util.regex.Pattern;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
 
+import net.sourceforge.pmd.util.AssertionUtil;
+
 /**
  * Utility class for working with {@link Predicate}.
  */

pmd-core/src/main/java/net/sourceforge/pmd/lang/LanguageVersionDiscoverer.java

@@ -15,7 +15,7 @@ import org.apache.commons.lang3.StringUtils;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
 import net.sourceforge.pmd.annotation.DeprecatedUntil700;
-import net.sourceforge.pmd.internal.util.AssertionUtil;
+import net.sourceforge.pmd.util.AssertionUtil;
 
 /**
  * This class can discover the LanguageVersion of a source file. Further, every

pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/AstInfo.java

@@ -10,9 +10,9 @@ import java.util.Map;
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 import net.sourceforge.pmd.annotation.Experimental;
-import net.sourceforge.pmd.internal.util.AssertionUtil;
 import net.sourceforge.pmd.lang.ast.Parser.ParserTask;
 import net.sourceforge.pmd.lang.document.TextDocument;
+import net.sourceforge.pmd.util.AssertionUtil;
 
 /**
  * The output of {@link Parser#parse(ParserTask)}.

pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/GenericToken.java

@@ -9,10 +9,10 @@ import java.util.stream.Stream;
 import org.apache.commons.lang3.StringUtils;
 
 import net.sourceforge.pmd.annotation.Experimental;
-import net.sourceforge.pmd.internal.util.IteratorUtil;
 import net.sourceforge.pmd.lang.document.Chars;
 import net.sourceforge.pmd.lang.document.TextRegion;
 import net.sourceforge.pmd.reporting.Reportable;
+import net.sourceforge.pmd.util.IteratorUtil;
 
 /**
  * Represents a token, part of a token chain in a source file. Tokens

pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/impl/javacc/EscapeTranslator.java

@@ -6,11 +6,11 @@ package net.sourceforge.pmd.lang.ast.impl.javacc;
 
 import static java.lang.Integer.min;
 
-import net.sourceforge.pmd.internal.util.AssertionUtil;
 import net.sourceforge.pmd.lang.document.Chars;
 import net.sourceforge.pmd.lang.document.FileLocation;
 import net.sourceforge.pmd.lang.document.FragmentedDocBuilder;
 import net.sourceforge.pmd.lang.document.TextDocument;
+import net.sourceforge.pmd.util.AssertionUtil;
 
 /**
  * An object that can translate an input document into an output document,

pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/internal/AxisStream.java

@@ -18,10 +18,10 @@ import java.util.function.Predicate;
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
-import net.sourceforge.pmd.internal.util.AssertionUtil;
-import net.sourceforge.pmd.internal.util.IteratorUtil;
 import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.ast.NodeStream;
+import net.sourceforge.pmd.util.AssertionUtil;
+import net.sourceforge.pmd.util.IteratorUtil;
 
 /**
  * Stream that iterates over one axis of the tree.