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 }