View Javadoc

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