Merge branch 'pr-1419'

docs/pages/release_notes.md

@@ -31,6 +31,9 @@ This is a {{ site.pmd.release_type }} release.
 
 ### API Changes
 
+* The implementation of the adapters for the XPath engines Saxon and Jaxen (package `net.sourceforge.pmd.lang.ast.xpath`)
+  are now deprecated. They'll be moved to an internal package come 7.0.0. Only `Attribute` remains public API.
+
 ### External Contributions
 
 *   [#1384](https://github.com/pmd/pmd/pull/1384): \[java] New Rule - UseUnderscoresInNumericLiterals - [RajeshR](https://github.com/rajeshggwp)

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

@@ -6,6 +6,7 @@ package net.sourceforge.pmd.lang;
 
 import org.jaxen.Navigator;
 
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.xpath.Initializer;
 
 import net.sf.saxon.sxpath.IndependentContext;
@@ -14,6 +15,8 @@ import net.sf.saxon.sxpath.IndependentContext;
  * Interface for performing Language specific XPath handling, such as
  * initialization and navigation.
  */
+@InternalApi
+@Deprecated
 public interface XPathHandler {
 
     XPathHandler DUMMY = new XPathHandler() {
@@ -48,6 +51,9 @@ public interface XPathHandler {
     /**
      * Get a Jaxen Navigator for this Language. May return <code>null</code> if
      * there is no Jaxen Navigation for this language.
+     *
+     * @deprecated Support for Jaxen will be removed come 7.0.0
      */
+    @Deprecated
     Navigator getNavigator();
 }

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

@@ -6,11 +6,15 @@ package net.sourceforge.pmd.lang.ast.xpath;
 
 import org.jaxen.Navigator;
 
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.Language;
 import net.sourceforge.pmd.lang.XPathHandler;
 
 import net.sf.saxon.sxpath.IndependentContext;
 
+
+@Deprecated
+@InternalApi
 public abstract class AbstractASTXPathHandler implements XPathHandler {
 
     @Override

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

@@ -14,6 +14,7 @@ import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ConcurrentMap;
 
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.Node;
 
 
@@ -22,7 +23,11 @@ import net.sourceforge.pmd.lang.ast.Node;
  * attributes. This is the default way the attributes of a node
  * are made accessible to XPath rules, and defines an important
  * piece of PMD's XPath support.
+ *
+ * @deprecated Use {@link Node#getXPathAttributesIterator()}
  */
+@Deprecated
+@InternalApi
 public class AttributeAxisIterator implements Iterator<Attribute> {
 
     /** Caches the precomputed attribute accessors of a given class. */

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

@@ -4,8 +4,13 @@
 
 package net.sourceforge.pmd.lang.ast.xpath;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
 import net.sf.saxon.sxpath.IndependentContext;
 
+
+@Deprecated
+@InternalApi
 public class DefaultASTXPathHandler extends AbstractASTXPathHandler {
     @Override
     public void initialize() {

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

@@ -11,12 +11,15 @@ import org.jaxen.DefaultNavigator;
 import org.jaxen.XPath;
 import org.jaxen.util.SingleObjectIterator;
 
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.ast.RootNode;
 
 /**
  * @author daniels
  */
+@Deprecated
+@InternalApi
 public class DocumentNavigator extends DefaultNavigator {
 
     private static final Iterator<Node> EMPTY_ITERATOR = new ArrayList<Node>().iterator();

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

@@ -7,6 +7,7 @@ package net.sourceforge.pmd.lang.ast.xpath;
 import java.util.Iterator;
 import java.util.NoSuchElementException;
 
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.Node;
 
 /**
@@ -15,6 +16,8 @@ import net.sourceforge.pmd.lang.ast.Node;
  *
  * @author daniels
  */
+@Deprecated
+@InternalApi
 public abstract class NodeIterator implements Iterator<Node> {
 
     private Node node;

pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/xpath/saxon/AbstractNodeInfo.java

@@ -4,6 +4,8 @@
 
 package net.sourceforge.pmd.lang.ast.xpath.saxon;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
 import net.sf.saxon.Configuration;
 import net.sf.saxon.event.Receiver;
 import net.sf.saxon.om.Axis;
@@ -27,6 +29,8 @@ import net.sf.saxon.value.Value;
  * useful implementations, such as {@link #iterateAxis(byte, NodeTest)} and
  * {@link #isSameNodeInfo(NodeInfo)}.
  */
+@Deprecated
+@InternalApi
 public class AbstractNodeInfo implements VirtualNode, SiblingCountingNode {
     @Override
     public String getSystemId() {

pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/xpath/saxon/AttributeAxisIterator.java

@@ -6,6 +6,7 @@ package net.sourceforge.pmd.lang.ast.xpath.saxon;
 
 import java.util.Iterator;
 
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.xpath.Attribute;
 
 import net.sf.saxon.om.Navigator;
@@ -15,6 +16,8 @@ import net.sf.saxon.om.SequenceIterator;
  * An adapter over our {@link net.sourceforge.pmd.lang.ast.xpath.AttributeAxisIterator}
  * for the Saxon model.
  */
+@Deprecated
+@InternalApi
 public class AttributeAxisIterator extends Navigator.BaseEnumeration {
 
     protected final ElementNode startNodeInfo;

pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/xpath/saxon/AttributeNode.java

@@ -4,6 +4,7 @@
 
 package net.sourceforge.pmd.lang.ast.xpath.saxon;
 
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.xpath.Attribute;
 import net.sourceforge.pmd.lang.rule.xpath.SaxonXPathRuleQuery;
 
@@ -18,6 +19,8 @@ import net.sf.saxon.value.Value;
  * Belongs to an {@link ElementNode}, and wraps an
  * {@link Attribute}.
  */
+@Deprecated
+@InternalApi
 public class AttributeNode extends AbstractNodeInfo {
     protected final Attribute attribute;
     protected final int id;

pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/xpath/saxon/DocumentNode.java

@@ -8,6 +8,7 @@ import java.util.HashMap;
 import java.util.Iterator;
 import java.util.Map;
 
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.Node;
 
 import net.sf.saxon.om.Axis;
@@ -21,6 +22,8 @@ import net.sf.saxon.type.Type;
 /**
  * A Saxon OM Document node for an AST Node.
  */
+@Deprecated
+@InternalApi
 public class DocumentNode extends AbstractNodeInfo implements DocumentInfo {
 
     /**

pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/xpath/saxon/ElementNode.java

@@ -4,6 +4,7 @@
 
 package net.sourceforge.pmd.lang.ast.xpath.saxon;
 
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.Node;
 
 import net.sf.saxon.om.Axis;
@@ -19,6 +20,8 @@ import net.sf.saxon.type.Type;
 /**
  * A Saxon OM Element type node for an AST Node.
  */
+@Deprecated
+@InternalApi
 public class ElementNode extends AbstractNodeInfo {
 
     protected final DocumentNode document;

pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/xpath/saxon/IdGenerator.java

@@ -4,9 +4,14 @@
 
 package net.sourceforge.pmd.lang.ast.xpath.saxon;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
+
 /**
  * This class is used to generate unique IDs for nodes.
  */
+@Deprecated
+@InternalApi
 public class IdGenerator {
     private int id;
 

pmd-core/src/main/java/net/sourceforge/pmd/lang/xpath/Initializer.java

@@ -4,6 +4,7 @@
 
 package net.sourceforge.pmd.lang.xpath;
 
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.Language;
 import net.sourceforge.pmd.lang.LanguageRegistry;
 import net.sourceforge.pmd.lang.LanguageVersion;
@@ -16,7 +17,11 @@ import net.sf.saxon.sxpath.IndependentContext;
  * initialization. For example, initializing custom Jaxen Functions.
  * Initialization should be performed before any XPath related operations are
  * performed.
+ *
+ * @deprecated Is internal API
  */
+@InternalApi
+@Deprecated
 public final class Initializer {
 
     private Initializer() { }

pmd-core/src/main/java/net/sourceforge/pmd/lang/xpath/MatchesFunction.java

@@ -14,9 +14,12 @@ import org.jaxen.FunctionCallException;
 import org.jaxen.SimpleFunctionContext;
 import org.jaxen.XPathFunctionContext;
 
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.xpath.Attribute;
 
 // FIXME Can this function be extended to work on non-AST attributes?
+@InternalApi
+@Deprecated
 public class MatchesFunction implements Function {
 
     public static void registerSelfInSimpleContext() {

pmd-core/src/main/java/net/sourceforge/pmd/lang/xpath/PMDFunctions.java

@@ -4,6 +4,11 @@
 
 package net.sourceforge.pmd.lang.xpath;
 
+import net.sourceforge.pmd.annotation.InternalApi;
+
+
+@InternalApi
+@Deprecated
 public final class PMDFunctions {
     private PMDFunctions() { }
 

pmd-java/src/main/java/net/sourceforge/pmd/lang/java/xpath/GetCommentOnFunction.java

@@ -12,6 +12,7 @@ import org.jaxen.FunctionCallException;
 import org.jaxen.SimpleFunctionContext;
 import org.jaxen.XPathFunctionContext;
 
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.AbstractNode;
 import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.java.ast.ASTCompilationUnit;
@@ -24,6 +25,8 @@ import net.sourceforge.pmd.lang.java.ast.Comment;
  *
  * @author Andy Throgmorton
  */
+@InternalApi
+@Deprecated
 public class GetCommentOnFunction implements Function {
 
     public static void registerSelfInSimpleContext() {

pmd-java/src/main/java/net/sourceforge/pmd/lang/java/xpath/JavaFunctions.java

@@ -4,6 +4,7 @@
 
 package net.sourceforge.pmd.lang.java.xpath;
 
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.ast.xpath.saxon.ElementNode;
 
@@ -12,6 +13,8 @@ import net.sf.saxon.expr.XPathContext;
 /**
  * Exposes all Java Language specific functions for Saxon use.
  */
+@InternalApi
+@Deprecated
 public final class JavaFunctions {
 
     private JavaFunctions() {

pmd-java/src/main/java/net/sourceforge/pmd/lang/java/xpath/MetricFunction.java

@@ -15,6 +15,7 @@ import org.jaxen.FunctionCallException;
 import org.jaxen.SimpleFunctionContext;
 import org.jaxen.XPathFunctionContext;
 
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.java.ast.ASTAnyTypeDeclaration;
 import net.sourceforge.pmd.lang.java.ast.MethodLikeNode;
@@ -32,6 +33,8 @@ import net.sourceforge.pmd.lang.java.metrics.api.JavaOperationMetricKey;
  * @author Clément Fournier
  * @since 6.0.0
  */
+@InternalApi
+@Deprecated
 public class MetricFunction implements Function {
 
 

pmd-java/src/main/java/net/sourceforge/pmd/lang/java/xpath/TypeIsExactlyFunction.java

@@ -12,10 +12,14 @@ import org.jaxen.FunctionCallException;
 import org.jaxen.SimpleFunctionContext;
 import org.jaxen.XPathFunctionContext;
 
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.java.ast.TypeNode;
 import net.sourceforge.pmd.lang.java.typeresolution.TypeHelper;
 
+
+@InternalApi
+@Deprecated
 public class TypeIsExactlyFunction implements Function {
 
     public static void registerSelfInSimpleContext() {

pmd-java/src/main/java/net/sourceforge/pmd/lang/java/xpath/TypeIsFunction.java

@@ -12,10 +12,14 @@ import org.jaxen.FunctionCallException;
 import org.jaxen.SimpleFunctionContext;
 import org.jaxen.XPathFunctionContext;
 
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.java.ast.TypeNode;
 import net.sourceforge.pmd.lang.java.typeresolution.TypeHelper;
 
+
+@InternalApi
+@Deprecated
 public class TypeIsFunction implements Function {
 
     public static void registerSelfInSimpleContext() {