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       * This method returns a child node.  The children are numbered
49       * from zero, left to right.
50       *
51       * @param index the child index. Must be nonnegative and less than
52       *          {@link #jjtGetNumChildren}.
53       */
54      Node jjtGetChild(int index);
55  
56      /**
57       * Return the number of children the node has.
58       */
59      int jjtGetNumChildren();
60  
61      int jjtGetId();
62  
63      String getImage();
64  
65      void setImage(String image);
66  
67      boolean hasImageEqualTo(String image);
68  
69      int getBeginLine();
70  
71      int getBeginColumn();
72  
73      int getEndLine();
74  
75      int getEndColumn();
76  
77      DataFlowNode getDataFlowNode();
78  
79      void setDataFlowNode(DataFlowNode dataFlowNode);
80  
81      boolean isFindBoundary();
82  
83      Node getNthParent(int n);
84  
85      <T> T getFirstParentOfType(Class<T> parentType);
86  
87      <T> List<T> getParentsOfType(Class<T> parentType);
88  
89      /**
90       * Traverses the children to find all the instances of type childType.
91       *
92       * @see #findDescendantsOfType(Class) if traversal of the entire tree is needed.
93       *
94       * @param childType class which you want to find.
95       * @return List of all children of type childType. Returns an empty list if none found.
96       */
97      <T> List<T> findChildrenOfType(Class<T> childType);
98  
99      /**
100      * Traverses down the tree to find all the descendant instances of type descendantType.
101      *
102      * @param targetType class which you want to find.
103      * @return List of all children of type targetType. Returns an empty list if none found.
104      */
105     <T> List<T> findDescendantsOfType(Class<T> targetType);
106 
107     /**
108      * Traverses down the tree to find all the descendant instances of type descendantType.
109      *
110      * @param targetType class which you want to find.
111      * @param results list to store the matching descendants
112      * @param crossFindBoundaries if <code>false</code>, recursion stops for nodes for which {@link #isFindBoundary()} is <code>true</code>
113      */
114     <T> void findDescendantsOfType(Class<T> targetType, List<T> results, boolean crossFindBoundaries);
115 
116     /**
117      * Traverses the children to find the first instance of type childType.
118      *
119      * @see #getFirstDescendantOfType(Class) if traversal of the entire tree is needed.
120      *
121      * @param childType class which you want to find.
122      * @return Node of type childType. Returns <code>null</code> if none found.
123      */
124     <T> T getFirstChildOfType(Class<T> childType);
125 
126     /**
127      * Traverses down the tree to find the first descendant instance of type descendantType.
128      *
129      * @param descendantType class which you want to find.
130      * @return Node of type descendantType. Returns <code>null</code> if none found.
131      */
132     <T> T getFirstDescendantOfType(Class<T> descendantType);
133 
134     /**
135      * Finds if this node contains a descendant of the given type.
136      *
137      * @param type the node type to search
138      * @return <code>true</code> if there is at least one descendant of the given type
139      */
140     <T> boolean hasDescendantOfType(Class<T> type);
141 
142     /**
143      * Returns all the nodes matching the xpath expression.
144      *
145      * @param xpathString the expression to check
146      * @return List of all matching nodes. Returns an empty list if none found.
147      * @throws JaxenException
148      */
149     List<? extends Node> findChildNodesWithXPath(String xpathString) throws JaxenException;
150 
151     /**
152      * Checks whether at least one descendant matches the xpath expression.
153      *
154      * @param xpathString the expression to check
155      * @return true if there is a match
156      */
157     boolean hasDescendantMatchingXPath(String xpathString);
158 
159     /**
160      * Get a DOM Document which contains Elements and Attributes representative
161      * of this Node and it's children.  Essentially a DOM tree representation of
162      * the Node AST, thereby allowing tools which can operate upon DOM to
163      * also indirectly operate on the AST.
164      */
165     Document getAsDocument();
166     
167     /**
168      * Get the user data associated with this node.  By default there is no data,
169      * unless it has been set via {@link #setUserData(Object)}.
170      * @return The user data set on this node.
171      */
172     Object getUserData();
173 
174     /**
175      * Set the user data associated with this node.
176      * <p>
177      * PMD itself will never set user data onto a node.  Nor should any Rule
178      * implementation, as the AST nodes are shared between concurrently executing
179      * Rules (i.e. it is <strong>not</strong> thread-safe).
180      * <p> 
181      * This API is most useful for external applications looking to leverage
182      * PMD's robust support for AST structures, in which case application
183      * specific annotations on the AST nodes can be quite useful.
184      * 
185      * @param userData The data to set on this node.
186      */
187     void setUserData(Object userData);
188 }