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 }