View Javadoc
1   /**
2    * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
3    */
4   /* Generated By:JJTree: Do not edit this line. Node.java */
5   
6   package net.sourceforge.pmd.lang.ast;
7   
8   import java.util.List;
9   
10  import net.sourceforge.pmd.lang.dfa.DataFlowNode;
11  
12  import org.jaxen.JaxenException;
13  import org.w3c.dom.Document;
14  
15  /* All AST nodes must implement this interface.  It provides basic
16     machinery for constructing the parent and child relationships
17     between nodes. */
18  
19  public interface Node {
20  
21      /**
22       * This method is called after the node has been made the current
23       * node.  It indicates that child nodes can now be added to it.
24       */
25      void jjtOpen();
26  
27      /**
28       * This method is called after all the child nodes have been
29       * added.
30       */
31      void jjtClose();
32  
33      /**
34       * This pair of methods are used to inform the node of its
35       * parent.
36       */
37      void jjtSetParent(Node parent);
38  
39      Node jjtGetParent();
40  
41      /**
42       * This method tells the node to add its argument to the node's
43       * list of children.
44       */
45      void jjtAddChild(Node child, int index);
46  
47      /**
48       * Sets the index of this node from the perspective of its parent.
49       * This means: this.jjtGetParent().jjtGetChild(index) == this.
50       * 
51       * @param index the child index
52       */
53      void jjtSetChildIndex(int index);
54  
55      int jjtGetChildIndex();
56  
57      /**
58       * This method returns a child node.  The children are numbered
59       * from zero, left to right.
60       *
61       * @param index the child index. Must be nonnegative and less than
62       *          {@link #jjtGetNumChildren}.
63       */
64      Node jjtGetChild(int index);
65  
66      /**
67       * Return the number of children the node has.
68       */
69      int jjtGetNumChildren();
70  
71      int jjtGetId();
72  
73      String getImage();
74  
75      void setImage(String image);
76  
77      boolean hasImageEqualTo(String image);
78  
79      int getBeginLine();
80  
81      int getBeginColumn();
82  
83      int getEndLine();
84  
85      int getEndColumn();
86  
87      DataFlowNode getDataFlowNode();
88  
89      void setDataFlowNode(DataFlowNode dataFlowNode);
90  
91      boolean isFindBoundary();
92  
93      Node getNthParent(int n);
94  
95      <T> T getFirstParentOfType(Class<T> parentType);
96  
97      <T> List<T> getParentsOfType(Class<T> parentType);
98  
99      /**
100      * Traverses the children to find all the instances of type childType.
101      *
102      * @see #findDescendantsOfType(Class) if traversal of the entire tree is needed.
103      *
104      * @param childType class which you want to find.
105      * @return List of all children of type childType. Returns an empty list if none found.
106      */
107     <T> List<T> findChildrenOfType(Class<T> childType);
108 
109     /**
110      * Traverses down the tree to find all the descendant instances of type descendantType.
111      *
112      * @param targetType class which you want to find.
113      * @return List of all children of type targetType. Returns an empty list if none found.
114      */
115     <T> List<T> findDescendantsOfType(Class<T> targetType);
116 
117     /**
118      * Traverses down the tree to find all the descendant instances of type descendantType.
119      *
120      * @param targetType class which you want to find.
121      * @param results list to store the matching descendants
122      * @param crossFindBoundaries if <code>false</code>, recursion stops for nodes for which {@link #isFindBoundary()} is <code>true</code>
123      */
124     <T> void findDescendantsOfType(Class<T> targetType, List<T> results, boolean crossFindBoundaries);
125 
126     /**
127      * Traverses the children to find the first instance of type childType.
128      *
129      * @see #getFirstDescendantOfType(Class) if traversal of the entire tree is needed.
130      *
131      * @param childType class which you want to find.
132      * @return Node of type childType. Returns <code>null</code> if none found.
133      */
134     <T> T getFirstChildOfType(Class<T> childType);
135 
136     /**
137      * Traverses down the tree to find the first descendant instance of type descendantType.
138      *
139      * @param descendantType class which you want to find.
140      * @return Node of type descendantType. Returns <code>null</code> if none found.
141      */
142     <T> T getFirstDescendantOfType(Class<T> descendantType);
143 
144     /**
145      * Finds if this node contains a descendant of the given type.
146      *
147      * @param type the node type to search
148      * @return <code>true</code> if there is at least one descendant of the given type
149      */
150     <T> boolean hasDescendantOfType(Class<T> type);
151 
152     /**
153      * Returns all the nodes matching the xpath expression.
154      *
155      * @param xpathString the expression to check
156      * @return List of all matching nodes. Returns an empty list if none found.
157      * @throws JaxenException
158      */
159     List<? extends Node> findChildNodesWithXPath(String xpathString) throws JaxenException;
160 
161     /**
162      * Checks whether at least one descendant matches the xpath expression.
163      *
164      * @param xpathString the expression to check
165      * @return true if there is a match
166      */
167     boolean hasDescendantMatchingXPath(String xpathString);
168 
169     /**
170      * Get a DOM Document which contains Elements and Attributes representative
171      * of this Node and it's children.  Essentially a DOM tree representation of
172      * the Node AST, thereby allowing tools which can operate upon DOM to
173      * also indirectly operate on the AST.
174      */
175     Document getAsDocument();
176     
177     /**
178      * Get the user data associated with this node.  By default there is no data,
179      * unless it has been set via {@link #setUserData(Object)}.
180      * @return The user data set on this node.
181      */
182     Object getUserData();
183 
184     /**
185      * Set the user data associated with this node.
186      * <p>
187      * PMD itself will never set user data onto a node.  Nor should any Rule
188      * implementation, as the AST nodes are shared between concurrently executing
189      * Rules (i.e. it is <strong>not</strong> thread-safe).
190      * <p> 
191      * This API is most useful for external applications looking to leverage
192      * PMD's robust support for AST structures, in which case application
193      * specific annotations on the AST nodes can be quite useful.
194      * 
195      * @param userData The data to set on this node.
196      */
197     void setUserData(Object userData);
198 }