Merge branch 'pr-2060'

docs/pages/release_notes.md

@@ -78,6 +78,15 @@ This is a {{ site.pmd.release_type }} release.
   * {% jdoc apex::lang.apex.ast.CanSuppressWarnings %} and its implementations
   * {% jdoc apex::lang.apex.rule.ApexRuleViolation#isSupressed(Node,Rule) %}
 
+##### Internal APIs
+
+* pmd-core
+  * All the package {% jdoc_package core::util %} and its subpackages,
+  except {% jdoc_package core::util.datasource %} and {% jdoc_package core::util.database %}.
+  * {% jdoc core::cpd.GridBagHelper %}
+  * {% jdoc core::renderers.ColumnDescriptor %}
+
+
 
 ### External Contributions
 

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

@@ -24,7 +24,6 @@ import net.sourceforge.pmd.lang.rule.stat.StatisticalRule;
 import net.sourceforge.pmd.renderers.AbstractAccumulatingRenderer;
 import net.sourceforge.pmd.stat.Metric;
 import net.sourceforge.pmd.util.DateTimeUtil;
-import net.sourceforge.pmd.util.EmptyIterator;
 import net.sourceforge.pmd.util.NumericConstants;
 
 /**
@@ -162,7 +161,7 @@ public class Report implements Iterable<RuleViolation> {
         public String getMsg() {
             return error.getClass().getSimpleName() + ": " + error.getMessage();
         }
-        
+
         public String getDetail() {
             try (StringWriter stringWriter = new StringWriter();
                     PrintWriter writer = new PrintWriter(stringWriter)) {
@@ -491,7 +490,7 @@ public class Report implements Iterable<RuleViolation> {
      * @return the iterator
      */
     public Iterator<ProcessingError> errors() {
-        return errors == null ? EmptyIterator.<ProcessingError>instance() : errors.iterator();
+        return errors == null ? Collections.<ProcessingError>emptyIterator() : errors.iterator();
     }
 
     /**
@@ -500,7 +499,7 @@ public class Report implements Iterable<RuleViolation> {
      * @return the iterator
      */
     public Iterator<ConfigurationError> configErrors() {
-        return configErrors == null ? EmptyIterator.<ConfigurationError>instance() : configErrors.iterator();
+        return configErrors == null ? Collections.<ConfigurationError>emptyIterator() : configErrors.iterator();
     }
 
     /**

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

@@ -13,6 +13,13 @@ import java.awt.Insets;
 import javax.swing.JLabel;
 import javax.swing.SwingConstants;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
+/**
+ * @deprecated Is internal API
+ */
+@Deprecated
+@InternalApi
 public class GridBagHelper {
 
     GridBagLayout gridbag;

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

@@ -21,7 +21,6 @@ public final class IteratorUtil {
 
     }
 
-
     public static <T> Iterator<T> reverse(Iterator<T> it) {
         List<T> tmp = toList(it);
         Collections.reverse(tmp);

pmd-core/src/main/java/net/sourceforge/pmd/renderers/ColumnDescriptor.java

@@ -4,12 +4,17 @@
 
 package net.sourceforge.pmd.renderers;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
 /**
  *
  * @author Brian Remedios
  *
  * @param <T>
+ * @deprecated Is internal API
  */
+@InternalApi
+@Deprecated
 public class ColumnDescriptor<T extends Object> {
 
     public final String id;

pmd-core/src/main/java/net/sourceforge/pmd/util/ClassUtil.java

@@ -17,7 +17,9 @@ import java.util.Map;
  * UIs without the package prefixes.
  *
  * @author Brian Remedios
+ * @deprecated Is internal API
  */
+@Deprecated
 public final class ClassUtil {
 
     public static final Class<?>[] EMPTY_CLASS_ARRAY = new Class[0];

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

@@ -19,17 +19,22 @@ import java.util.logging.Logger;
 
 import org.apache.commons.lang3.StringUtils;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
 /**
  * Create a ClassLoader which loads classes using a CLASSPATH like String. If
  * the String looks like a URL to a file (e.g. starts with <code>file://</code>)
  * 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 = Logger.getLogger(ClasspathClassLoader.class.getName());
-    
+
     static {
         registerAsParallelCapable();
     }
@@ -102,7 +107,7 @@ public class ClasspathClassLoader extends URLClassLoader {
                 .append(StringUtils.join(getURLs(), ":"))
                 .append("] parent: ").append(getParent()).append(']').toString();
     }
-    
+
     @Override
     protected Class<?> loadClass(final String name, final boolean resolve) throws ClassNotFoundException {
         synchronized (getClassLoadingLock(name)) {
@@ -118,7 +123,7 @@ public class ClasspathClassLoader extends URLClassLoader {
                     c = super.loadClass(name, resolve);
                 }
             }
-    
+
             if (resolve) {
                 resolveClass(c);
             }

pmd-core/src/main/java/net/sourceforge/pmd/util/CollectionUtil.java

@@ -16,13 +16,18 @@ import java.util.Map;
 import java.util.Objects;
 import java.util.Set;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
 /**
  * Generic collection and array-related utility functions for java.util types.
  * See ClassUtil for comparable facilities for short name lookup.
  *
  * @author Brian Remedios
  * @version $Revision$
+ * @deprecated Is internal API
  */
+@Deprecated
+@InternalApi
 public final class CollectionUtil {
 
     @SuppressWarnings("PMD.UnnecessaryFullyQualifiedName")

pmd-core/src/main/java/net/sourceforge/pmd/util/CompoundIterator.java

@@ -7,6 +7,8 @@ package net.sourceforge.pmd.util;
 import java.util.Iterator;
 import java.util.NoSuchElementException;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
 /**
  * Creates a single compound Iterator from an array of Iterators.
  *
@@ -15,6 +17,8 @@ import java.util.NoSuchElementException;
  *
  * @see Iterator
  */
+@InternalApi
+@Deprecated
 public class CompoundIterator<T> implements Iterator<T> {
     private final Iterator<T>[] iterators;
     private int index;

pmd-core/src/main/java/net/sourceforge/pmd/util/DateTimeUtil.java

@@ -4,10 +4,14 @@
 
 package net.sourceforge.pmd.util;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
 /**
  *
  * @author Brian Remedios
  */
+@InternalApi
+@Deprecated
 public final class DateTimeUtil {
 
     private DateTimeUtil() {

pmd-core/src/main/java/net/sourceforge/pmd/util/EmptyIterator.java

@@ -4,15 +4,21 @@
 
 package net.sourceforge.pmd.util;
 
+import java.util.Collections;
 import java.util.Iterator;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
 /**
  * A singleton iterator that never has anything.
  *
  * @author Brian Remedios
  *
  * @param <T>
+ * @deprecated Use {@link Collections#emptyIterator()}
  */
+@InternalApi
+@Deprecated
 public final class EmptyIterator<T extends Object> implements Iterator<T> {
 
     @SuppressWarnings("rawtypes")
@@ -23,7 +29,7 @@ public final class EmptyIterator<T extends Object> implements Iterator<T> {
 
     @SuppressWarnings("unchecked")
     public static <T extends Object> Iterator<T> instance() {
-        return INSTANCE;
+        return Collections.emptyIterator();
     }
 
     @Override

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

@@ -12,9 +12,14 @@ import java.util.List;
 
 import org.apache.commons.io.comparator.PathFileComparator;
 
+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/util/FileIterable.java

@@ -9,6 +9,7 @@ import java.io.IOException;
 import java.io.LineNumberReader;
 import java.nio.charset.Charset;
 import java.nio.file.Files;
+import java.nio.file.Path;
 import java.util.Iterator;
 
 /**
@@ -19,8 +20,9 @@ import java.util.Iterator;
  * </p>
  *
  * @author Romain Pelisse &lt;belaran@gmail.com&gt;
- *
+ * @deprecated Just use {@link Files#readAllLines(Path, Charset)} or {@code lines} on Java 8
  */
+@Deprecated
 public class FileIterable implements Iterable<String> {
 
     private LineNumberReader lineReader = null;

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

@@ -5,8 +5,11 @@
 package net.sourceforge.pmd.util;
 
 import java.io.File;
+import java.io.FileNotFoundException;
 import java.io.FilenameFilter;
 import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.Enumeration;
@@ -20,6 +23,7 @@ import java.util.zip.ZipFile;
 import org.apache.commons.io.FileUtils;
 import org.apache.commons.lang3.StringUtils;
 
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.util.datasource.DataSource;
 import net.sourceforge.pmd.util.datasource.FileDataSource;
 import net.sourceforge.pmd.util.datasource.ZipDataSource;
@@ -30,7 +34,10 @@ import net.sourceforge.pmd.util.filter.OrFilter;
 
 /**
  * This is a utility class for working with Files.
+ * @deprecated Is internal API
  */
+@Deprecated
+@InternalApi
 public final class FileUtil {
 
     private FileUtil() {
@@ -148,13 +155,19 @@ public final class FileUtil {
         Pattern regexp = Pattern.compile(pattern);
         Matcher matcher = regexp.matcher("");
 
-        FileIterable it = new FileIterable(file);
-        for (String line : it) {
-            matcher.reset(line); // reset the input
-            if (matcher.find()) {
-                return true;
+        try {
+            for (String line : Files.readAllLines(file.toPath(), StandardCharsets.UTF_8)) {
+                matcher.reset(line); // reset the input
+                if (matcher.find()) {
+                    return true;
+                }
             }
+        } catch (FileNotFoundException e) {
+            throw new IllegalArgumentException(e);
+        } catch (IOException e) {
+            throw new RuntimeException(e);
         }
+
         return false;
     }
 
@@ -162,7 +175,7 @@ public final class FileUtil {
      * Reads the file, which contains the filelist. This is used for the
      * command line arguments --filelist/-filelist for both PMD and CPD.
      * The separator in the filelist is a command and/or newlines.
-     * 
+     *
      * @param filelist the file which contains the list of path names
      * @return a comma-separated list of file paths
      * @throws IOException if the file couldn't be read

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

@@ -17,10 +17,15 @@ import java.nio.file.Files;
 import org.apache.commons.io.IOUtils;
 import org.apache.commons.lang3.StringUtils;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
 /**
  *
  * @author Brian Remedios
+ * @deprecated Is internal API
  */
+@InternalApi
+@Deprecated
 public final class IOUtil {
 
     private IOUtil() {

pmd-core/src/main/java/net/sourceforge/pmd/util/NumericConstants.java

@@ -4,13 +4,18 @@
 
 package net.sourceforge.pmd.util;
 
+/**
+ * @deprecated These constants were only useful before autoboxing was
+ *     introduced, just use a literal or define your own constants
+ */
+@Deprecated
 public final class NumericConstants {
 
     public static final Integer ZERO = 0;
 
     public static final Integer ONE = 1;
 
-    public static final Float FLOAT_ZERO = new Float(0.0f);
+    public static final Float FLOAT_ZERO = 0.0f;
 
     private NumericConstants() { }
 }

pmd-core/src/main/java/net/sourceforge/pmd/util/ResourceLoader.java

@@ -14,7 +14,13 @@ import java.nio.file.Files;
 import java.util.Objects;
 
 import net.sourceforge.pmd.RuleSetNotFoundException;
+import net.sourceforge.pmd.annotation.InternalApi;
 
+/**
+ * @deprecated Is internal API
+ */
+@Deprecated
+@InternalApi
 public class ResourceLoader {
 
     public static final int TIMEOUT;
@@ -79,7 +85,7 @@ public class ResourceLoader {
                 // We will throw our own exception, with a different message
             }
         }
-        
+
         throw new RuleSetNotFoundException("Can't find resource " + name
                 + ". Make sure the resource is a valid file or URL or is on the CLASSPATH");
     }
@@ -102,7 +108,7 @@ public class ResourceLoader {
             return connection.getInputStream();
         }
     }
-    
+
     public InputStream loadClassPathResourceAsStreamOrThrow(final String name) throws RuleSetNotFoundException {
         InputStream is = null;
         try {
@@ -110,12 +116,12 @@ public class ResourceLoader {
         } catch (final IOException ignored) {
             // ignored
         }
-        
+
         if (is == null) {
             throw new RuleSetNotFoundException("Can't find resource " + name
                     + ". Make sure the resource is on the CLASSPATH");
         }
-        
+
         return is;
     }
 }

pmd-core/src/main/java/net/sourceforge/pmd/util/SearchFunction.java

@@ -4,6 +4,10 @@
 
 package net.sourceforge.pmd.util;
 
+/**
+ * @deprecated Will be replaced with standard java.util.function.Predicate with 7.0.0
+ */
+@Deprecated
 public interface SearchFunction<E> {
     /**
      * Applies the search function over a single element.

pmd-core/src/main/java/net/sourceforge/pmd/util/StringUtil.java

@@ -12,12 +12,17 @@ import java.util.Locale;
 
 import org.apache.commons.lang3.StringUtils;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
 /**
  * A number of String-specific utility methods for use by PMD or its IDE
  * plugins.
  *
  * @author BrianRemedios
+ * @deprecated Is internal API
  */
+@Deprecated
+@InternalApi
 public final class StringUtil {
 
     private static final String[] EMPTY_STRINGS = new String[0];

pmd-core/src/main/java/net/sourceforge/pmd/util/TypeMap.java

@@ -8,6 +8,8 @@ import java.util.HashMap;
 import java.util.Iterator;
 import java.util.Map;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
 /**
  * A specialized map that stores types by both their full and short (without
  * package prefixes) names. If an incoming type shares the same name (but
@@ -16,7 +18,10 @@ import java.util.Map;
  * said short name could be in error.
  *
  * @author Brian Remedios
+ * @deprecated Is internal API
  */
+@Deprecated
+@InternalApi
 public class TypeMap {
 
     private Map<String, Class<?>> typesByName;

pmd-core/src/main/java/net/sourceforge/pmd/util/filter/AbstractCompoundFilter.java

@@ -14,7 +14,9 @@ import java.util.List;
  *
  * @param <T>
  *            The underlying type on which the filter applies.
+ * @deprecated See {@link Filter}
  */
+@Deprecated
 public abstract class AbstractCompoundFilter<T> implements Filter<T> {
 
     protected List<Filter<T>> filters;

pmd-core/src/main/java/net/sourceforge/pmd/util/filter/AbstractDelegateFilter.java

@@ -10,7 +10,9 @@ package net.sourceforge.pmd.util.filter;
  *
  * @param <T>
  *            The underlying type on which the filter applies.
+ * @deprecated See {@link Filter}
  */
+@Deprecated
 public abstract class AbstractDelegateFilter<T> implements Filter<T> {
     protected Filter<T> filter;
 

pmd-core/src/main/java/net/sourceforge/pmd/util/filter/AndFilter.java

@@ -9,7 +9,9 @@ package net.sourceforge.pmd.util.filter;
  *
  * @param <T>
  *            The underlying type on which the filter applies.
+ * @deprecated See {@link Filter}
  */
+@Deprecated
 public class AndFilter<T> extends AbstractCompoundFilter<T> {
 
     public AndFilter() {

pmd-core/src/main/java/net/sourceforge/pmd/util/filter/DirectoryFilter.java

@@ -8,7 +8,9 @@ import java.io.File;
 
 /**
  * Directory filter.
+ * @deprecated See {@link Filter}
  */
+@Deprecated
 public final class DirectoryFilter implements Filter<File> {
     public static final DirectoryFilter INSTANCE = new DirectoryFilter();
 

pmd-core/src/main/java/net/sourceforge/pmd/util/filter/FileExtensionFilter.java

@@ -7,6 +7,10 @@ package net.sourceforge.pmd.util.filter;
 import java.io.File;
 import java.util.Locale;
 
+/**
+ * @deprecated See {@link Filter}
+ */
+@Deprecated
 public class FileExtensionFilter implements Filter<File> {
     protected final String[] extensions;
     protected final boolean ignoreCase;

pmd-core/src/main/java/net/sourceforge/pmd/util/filter/Filter.java

@@ -9,7 +9,10 @@ package net.sourceforge.pmd.util.filter;
  *
  * @param <T>
  *            The underlying type on which the filter applies.
+ *
+ * @deprecated Will be replaced with standard java.util.function.Predicate with 7.0.0
  */
+@Deprecated
 public interface Filter<T> {
     boolean filter(T obj);
 }

pmd-core/src/main/java/net/sourceforge/pmd/util/filter/Filters.java

@@ -10,10 +10,16 @@ import java.util.ArrayList;
 import java.util.Collection;
 import java.util.List;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
 /**
  * Utility class for working with Filters. Contains builder style methods, apply
  * methods, as well as mechanisms for adapting Filters and FilenameFilters.
+ *
+ * @deprecated Internal API, see {@link Filter}
  */
+@Deprecated
+@InternalApi
 public final class Filters {
 
     private Filters() { }

pmd-core/src/main/java/net/sourceforge/pmd/util/filter/NotFilter.java

@@ -9,7 +9,9 @@ package net.sourceforge.pmd.util.filter;
  *
  * @param <T>
  *            The underlying type on which the filter applies.
+ * @deprecated See {@link Filter}
  */
+@Deprecated
 public class NotFilter<T> extends AbstractDelegateFilter<T> {
     public NotFilter() {
         super();

pmd-core/src/main/java/net/sourceforge/pmd/util/filter/OrFilter.java

@@ -9,7 +9,9 @@ package net.sourceforge.pmd.util.filter;
  *
  * @param <T>
  *            The underlying type on which the filter applies.
+ * @deprecated See {@link Filter}
  */
+@Deprecated
 public class OrFilter<T> extends AbstractCompoundFilter<T> {
 
     public OrFilter() {

pmd-core/src/main/java/net/sourceforge/pmd/util/filter/RegexStringFilter.java

@@ -16,7 +16,9 @@ import java.util.regex.PatternSyntaxException;
  * some sort of relative file path, the regular expression is checked to see if
  * it can be evaluated using much faster calls to
  * {@link String#endsWith(String)}.
+ * @deprecated See {@link Filter}
  */
+@Deprecated
 public class RegexStringFilter implements Filter<String> {
     /**
      * Matches regular expressions begin with an optional {@code ^}, then