Pull new methods up into Node

hirsute-chauve · Dec 17, 2019 · cf843a8 · cf843a8
1 parent a64ea6b
commit cf843a8
Show file tree

Hide file tree

Showing 2 changed files with 71 additions and 30 deletions.
diff --git a/pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/AbstractNode.java b/pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/AbstractNode.java
@@ -29,13 +29,20 @@
 
 /**
  * Base class for all implementations of the Node interface.
+ *
+ * <p>Please use the {@link Node} interface wherever possible and
+ * not this class, unless you're compelled to do so.
+ *
+ * <p>Note that nearly all methods of the {@link Node} interface
+ * will have default implementations with PMD 7.0.0, so that it
+ * will not be necessary to extend this class directly.
  */
 public abstract class AbstractNode implements Node {
 
     private static final Logger LOG = Logger.getLogger(AbstractNode.class.getName());
 
     /**
-     * @deprecated Use {@link #jjtGetParent()}
+     * @deprecated Use {@link #getParent()}
      */
     @Deprecated
     protected Node parent;
@@ -126,10 +133,7 @@ public Node jjtGetParent() {
         return parent;
     }
 
-    /**
-     * Returns the parent of this node, or null if this is the {@linkplain RootNode root}
-     * of the tree.
-     */
+    @Override
     public Node getParent() {
         return jjtGetParent();
     }
@@ -168,11 +172,7 @@ public int jjtGetChildIndex() {
     }
 
 
-    /**
-     * Returns the index of this node in the parent's children. If this
-     * node is a {@linkplain RootNode root node}, returns -1.
-     */
-    // TODO move up to Node
+    @Override
     public int getIndexInParent() {
         return jjtGetChildIndex();
     }
@@ -182,29 +182,20 @@ public Node jjtGetChild(final int index) {
         return children[index];
     }
 
-    /**
-     * Returns the child of this node at the given index.
-     *
-     * @throws IndexOutOfBoundsException if the index is negative or greater than {@link #getNumChildren()}.
-     */
-    // TODO move up to Node
+    @Override
     public Node getChild(final int index) {
-        if (index < 0 || children.length <= index) {
-            // we could return null though.
+        if (children == null) {
             throw new IndexOutOfBoundsException();
         }
-        return jjtGetChild(index);
+        return children[index];
     }
 
     @Override
     public int jjtGetNumChildren() {
         return children == null ? 0 : children.length;
     }
 
-    /**
-     * Returns the number of children of this node.
-     */
-    // TODO move up to Node
+    @Override
     public int getNumChildren() {
         return jjtGetNumChildren();
     }

diff --git a/pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/Node.java b/pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/Node.java
@@ -1,7 +1,6 @@
-/**
+/*
  * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
  */
-/* Generated By:JJTree: Do not edit this line. Node.java */
 
 package net.sourceforge.pmd.lang.ast;
 
@@ -16,9 +15,21 @@
 import net.sourceforge.pmd.lang.dfa.DataFlowNode;
 
 /**
- * All AST nodes must implement this interface. It provides basic
- * machinery for constructing the parent and child relationships
- * between nodes.
+ * Root interface for all AST nodes. This interface provides only the API
+ * shared by all AST implementations in PMD language modules. This includes for now:
+ * <ul>
+ * <li>Tree traversal methods, like {@link #getParent()} and {@link #getFirstChildOfType(Class)}
+ * <li>The API used to describe nodes in a form understandable by XPath expressions:
+ * {@link #getXPathNodeName()},  {@link #getXPathAttributesIterator()}
+ * <li>Location metadata: eg {@link #getBeginLine()}, {@link #getBeginColumn()}
+ * </ul>
+ *
+ * <p>A number of methods are deprecated and will be removed in 7.0.0.
+ * Most of them are implementation details that clutter this API and
+ * make implementation more difficult. Some methods prefixed with {@code jjt}
+ * have a more conventional counterpart (e.g. {@link #jjtGetParent()} and
+ * {@link #getParent()}) that should be preferred. We may deprecate those
+ * old forms in the future.
  */
 public interface Node {
 
@@ -60,6 +71,17 @@ public interface Node {
     Node jjtGetParent();
 
 
+    /**
+     * Returns the parent of this node, or null if this is the {@linkplain RootNode root}
+     * of the tree.
+     *
+     * <p>This method should be preferred to {@link #jjtGetParent()}.
+     *
+     * @return The parent of this node
+     */
+    Node getParent();
+
+
     /**
      * This method tells the node to add its argument to the node's list of
      * children.
@@ -92,6 +114,19 @@ public interface Node {
      */
     int jjtGetChildIndex();
 
+
+    /**
+     * Returns the index of this node in its parent's children. If this
+     * node is a {@linkplain RootNode root node}, returns -1.
+     *
+     * <p>This method replaces {@link #jjtGetChildIndex()}, whose name was
+     * JJTree-specific.
+     *
+     * @return The index of this node in its parent's children
+     */
+    int getIndexInParent();
+
+
     /**
      * This method returns a child node. The children are numbered from zero,
      * left to right.
@@ -102,14 +137,29 @@ public interface Node {
      */
     Node jjtGetChild(int index);
 
+
+    /**
+     * Returns the child of this node at the given index.
+     *
+     * @throws IndexOutOfBoundsException if the index is negative or greater than {@link #getNumChildren()}.
+     */
+    Node getChild(int index);
+
+
     /**
      * Returns the number of children the node has.
      */
     int jjtGetNumChildren();
 
 
     /**
-     * @deprecated This is JJTree-specific and will be removed from this interface
+     * Returns the number of children of this node.
+     */
+    int getNumChildren();
+
+
+    /**
+     * @deprecated This is JJTree-specific and will be removed from this interface.
      */
     @Deprecated
     int jjtGetId();
@@ -124,7 +174,7 @@ public interface Node {
 
 
     /**
-     * @deprecated This is internal API.
+     * @deprecated This is internal API, the image should never be set by developers.
      */
     @InternalApi
     @Deprecated