Merge branch 'pr-2434'

[core] Deprecate a few more methods in Node, AbstractNode #2434

docs/pages/release_notes.md

@@ -180,6 +180,9 @@ In the **Java AST** the following attributes are deprecated and will issue a war
 *   {% jdoc !!core::cpd.token.AntlrToken#getType() %} - use `getKind()` instead.
 *   {% jdoc core::lang.rule.ImmutableLanguage %}
 *   {% jdoc core::lang.rule.MockRule %}
+*   {% jdoc !!core::lang.ast.Node#getFirstParentOfAnyType(java.lang.Class[]) %}
+*   {% jdoc !!core::lang.ast.Node#getAsDocument() %}
+*   {% jdoc !!core::lang.ast.AbstractNode#hasDescendantOfAnyType(java.lang.Class[]) %}
 *   {% jdoc !!java::lang.java.ast.ASTRecordDeclaration#getComponentList() %}
 *   Multiple fields, constructors and methods in {% jdoc core::lang.rule.XPathRule %}. See javadoc for details.
 

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

@@ -345,6 +345,7 @@ public <T> List<T> getParentsOfType(final Class<T> parentType) {
 
     @SafeVarargs
     @Override
+    @Deprecated
     public final <T> T getFirstParentOfAnyType(final Class<? extends T>... parentTypes) {
         Node parentNode = getParent();
         while (parentNode != null) {
@@ -414,6 +415,7 @@ public boolean isFindBoundary() {
     }
 
     @Override
+    @Deprecated
     public Document getAsDocument() {
         try {
             final DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
@@ -486,7 +488,8 @@ public final <T> boolean hasDescendantOfType(final Class<T> type) {
      * Returns true if this node has a descendant of any type among the provided types.
      *
      * @param types Types to test
-     * @deprecated Use {@link #hasDescendantOfAnyType(Class[])}
+     *
+     * @deprecated See {@link #hasDescendantOfAnyType(Class[])} for reasons
      */
     @Deprecated
     public final boolean hasDecendantOfAnyType(final Class<?>... types) {
@@ -497,7 +500,13 @@ public final boolean hasDecendantOfAnyType(final Class<?>... types) {
      * Returns true if this node has a descendant of any type among the provided types.
      *
      * @param types Types to test
+     *
+     * @deprecated This is implemented inefficiently, with PMD 7 Node streams
+     *     will provide a better alternative. We cannot ensure binary compatibility
+     *     because the methods on 7.0 expect at least one class type, by requiring
+     *     one Class parameter before the varargs (Effective Java 2nd ed., Item 42).
      */
+    @Deprecated
     public final boolean hasDescendantOfAnyType(final Class<?>... types) {
         // TODO consider implementing that with a single traversal!
         // hasDescendantOfType could then be a special case of this one

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

@@ -6,6 +6,7 @@
 
 import java.util.Iterator;
 import java.util.List;
+import javax.xml.parsers.ParserConfigurationException;
 
 import org.jaxen.JaxenException;
 import org.w3c.dom.Document;
@@ -26,6 +27,8 @@
  * {@link #getXPathNodeName()},  {@link #getXPathAttributesIterator()}
  * <li>Location metadata: eg {@link #getBeginLine()}, {@link #getBeginColumn()}
  * </ul>
+ * Additionally, the {@linkplain #getUserMap() user data map} is an extensibility
+ * mechanism with which any client can independently associate values to AST nodes.
  *
  * <p>Every language implementation must publish a sub-interface of Node
  * which serves as a supertype for all nodes of that language (e.g.
@@ -258,7 +261,11 @@ public interface Node {
      *
      * @return The first parent with a matching type. Returns null if there
      * is no such parent
+     *
+     * @deprecated This method causes an unchecked warning at call sites.
+     *     PMD 7 will provide a way to do the same thing without the warning.
      */
+    @Deprecated
     <T> T getFirstParentOfAnyType(Class<? extends T>... parentTypes);
 
     /**
@@ -381,7 +388,17 @@ public interface Node {
      * of this Node and it's children. Essentially a DOM tree representation of
      * the Node AST, thereby allowing tools which can operate upon DOM to also
      * indirectly operate on the AST.
+     *
+     * @deprecated Converting a tree to a DOM is not a standard use case.
+     *            The implementation rethrows a {@link ParserConfigurationException}
+     *            as a {@link RuntimeException}, but a caller should handle
+     *            it if he really wants to do this. Another problem is that
+     *            this is available on any node, yet only the root node of
+     *            a tree corresponds really to a document. The conversion
+     *            is easy to implement anyway, and does not have to be part
+     *            of this API.
      */
+    @Deprecated
     Document getAsDocument();
 
     /**