Interface Node
-
- All Known Subinterfaces:
DFAGraphMethod
,QualifiableNode
,RootNode
,ScopedNode
,SignedNode<N>
- All Known Implementing Classes:
AbstractJjtreeNode
,AbstractNode
public interface Node
Root interface for all AST nodes. This interface provides only the API shared by all AST implementations in PMD language modules. This includes for now:- Tree traversal methods, like
getParent()
andgetFirstChildOfType(Class)
- The API used to describe nodes in a form understandable by XPath expressions:
getXPathNodeName()
,getXPathAttributesIterator()
- Location metadata: eg
getBeginLine()
,getBeginColumn()
Every language implementation must publish a sub-interface of Node which serves as a supertype for all nodes of that language (e.g. pmd-java provides JavaNode, pmd-apex provides ApexNode, etc.). It is assumed in many places that the
getChild(int)
andgetParent()
method return an instance of this sub-interface. For example, no JSP node should have a Java node as its child. Embedding nodes from different languages will not be done via these methods, and conforming implementations should ensure that every node returned by these methods are indeed of the same type. Possibly, a type parameter will be added to the Node interface in 7.0.0 to enforce it at compile-time.A number of methods are deprecated and will be removed in 7.0.0. Most of them are implementation details that clutter this API and make implementation more difficult. Some methods prefixed with
jjt
have a more conventional counterpart (e.g.jjtGetParent()
andgetParent()
) that should be preferred.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description Iterable<? extends Node>
children()
Returns an iterable enumerating the children of this node.List<? extends Node>
findChildNodesWithXPath(String xpathString)
Deprecated.This is very inefficient and should not be used in new code.<T> List<T>
findChildrenOfType(Class<T> childType)
Traverses the children to find all the instances of type childType or one of its subclasses.<T> List<T>
findDescendantsOfType(Class<? extends T> targetType)
Traverses down the tree to find all the descendant instances of type descendantType without crossing find boundaries.<T> List<T>
findDescendantsOfType(Class<T> targetType, boolean crossFindBoundaries)
Traverses down the tree to find all the descendant instances of type descendantType.<T> void
findDescendantsOfType(Class<T> targetType, List<T> results, boolean crossFindBoundaries)
Deprecated.UsefindDescendantsOfType(Class, boolean)
instead, which returns a result list.Document
getAsDocument()
Deprecated.Converting a tree to a DOM is not a standard use case.int
getBeginColumn()
int
getBeginLine()
Node
getChild(int index)
Returns the child of this node at the given index.DataFlowNode
getDataFlowNode()
Deprecated.This is Java-specific and will be removed from this interfaceint
getEndColumn()
int
getEndLine()
<T> T
getFirstChildOfType(Class<T> childType)
Traverses the children to find the first instance of type childType.<T> T
getFirstDescendantOfType(Class<T> descendantType)
Traverses down the tree to find the first descendant instance of type descendantType without crossing find boundaries.<T> T
getFirstParentOfAnyType(Class<? extends T>... parentTypes)
Deprecated.This method causes an unchecked warning at call sites.<T> T
getFirstParentOfType(Class<T> parentType)
Traverses up the tree to find the first parent instance of type parentType or one of its subclasses.String
getImage()
Returns a string token, usually filled-in by the parser, which describes some textual characteristic of this node.int
getIndexInParent()
Returns the index of this node in its parent's children.Node
getNthParent(int n)
Returns the n-th parent or null if there are less thann
ancestors.int
getNumChildren()
Returns the number of children of this node.Node
getParent()
Returns the parent of this node, or null if this is the root of the tree.<T> List<T>
getParentsOfType(Class<T> parentType)
Traverses up the tree to find all of the parent instances of type parentType or one of its subclasses.Object
getUserData()
Deprecated.UsegetUserMap()
DataMap<DataMap.DataKey<?,?>>
getUserMap()
Returns a data map used to store additional information on this node.Iterator<Attribute>
getXPathAttributesIterator()
Returns an iterator enumerating all the attributes that are available from XPath for this node.String
getXPathNodeName()
Gets the name of the node that is used to match it with XPath queries.boolean
hasDescendantMatchingXPath(String xpathString)
Deprecated.This is very inefficient and should not be used in new code.<T> boolean
hasDescendantOfType(Class<T> type)
Finds if this node contains a descendant of the given type without crossing find boundaries.boolean
hasImageEqualTo(String image)
Returns true if this node's image is equal to the given string.boolean
isFindBoundary()
Returns true if this node is considered a boundary by traversal methods.void
jjtAddChild(Node child, int index)
Deprecated.This is JJTree-specific and will be removed from this interfacevoid
jjtClose()
Deprecated.This is JJTree-specific and will be removed from this interfaceNode
jjtGetChild(int index)
Deprecated.UsegetChild(int)
int
jjtGetChildIndex()
Deprecated.int
jjtGetId()
Deprecated.This is JJTree-specific and will be removed from this interface.int
jjtGetNumChildren()
Deprecated.UsegetNumChildren()
Node
jjtGetParent()
Deprecated.UsegetParent()
void
jjtOpen()
Deprecated.This is JJTree-specific and will be removed from this interfacevoid
jjtSetChildIndex(int index)
Deprecated.This is JJTree-specific and will be removed from this interfacevoid
jjtSetParent(Node parent)
Deprecated.This is JJTree-specific and will be removed from this interfacevoid
remove()
Deprecated.This is internal API and will be removed from this interface with 7.0.0void
removeChildAtIndex(int childIndex)
Deprecated.This is internal API and will be removed from this interface with 7.0.0void
setDataFlowNode(DataFlowNode dataFlowNode)
Deprecated.This is Java-specific and will be removed from this interfacevoid
setImage(String image)
Deprecated.This is internal API, the image should never be set by developers.void
setUserData(Object userData)
Deprecated.UsegetUserMap()
-
-
-
Method Detail
-
jjtOpen
@Deprecated void jjtOpen()
Deprecated.This is JJTree-specific and will be removed from this interfaceThis method is called after the node has been made the current node. It indicates that child nodes can now be added to it.
-
jjtClose
@Deprecated void jjtClose()
Deprecated.This is JJTree-specific and will be removed from this interfaceThis method is called after all the child nodes have been added.
-
jjtSetParent
@Deprecated void jjtSetParent(Node parent)
Deprecated.This is JJTree-specific and will be removed from this interfaceSets the parent of this node.- Parameters:
parent
- The parent
-
jjtGetParent
@Deprecated Node jjtGetParent()
Deprecated.UsegetParent()
Returns the parent of this node.- Returns:
- The parent of the node
-
jjtAddChild
@Deprecated void jjtAddChild(Node child, int index)
Deprecated.This is JJTree-specific and will be removed from this interfaceThis method tells the node to add its argument to the node's list of children.- Parameters:
child
- The child to addindex
- The index to which the child will be added
-
jjtSetChildIndex
@Deprecated void jjtSetChildIndex(int index)
Deprecated.This is JJTree-specific and will be removed from this interfaceSets the index of this node from the perspective of its parent. This means: this.getParent().getChild(index) == this.- Parameters:
index
- the child index
-
jjtGetChildIndex
@Deprecated int jjtGetChildIndex()
Deprecated.Gets the index of this node in the children of its parent.- Returns:
- The index of the node
-
jjtGetChild
@Deprecated Node jjtGetChild(int index)
Deprecated.UsegetChild(int)
This method returns a child node. The children are numbered from zero, left to right.- Parameters:
index
- the child index. Must be nonnegative and less thanjjtGetNumChildren()
.
-
jjtGetNumChildren
@Deprecated int jjtGetNumChildren()
Deprecated.UsegetNumChildren()
Returns the number of children the node has.
-
jjtGetId
@Deprecated int jjtGetId()
Deprecated.This is JJTree-specific and will be removed from this interface.
-
getImage
String getImage()
Returns a string token, usually filled-in by the parser, which describes some textual characteristic of this node. This is usually an identifier, but you should check that using the Designer. On most nodes though, this method returnsnull
.
-
setImage
@InternalApi @Deprecated void setImage(String image)
Deprecated.This is internal API, the image should never be set by developers.
-
hasImageEqualTo
boolean hasImageEqualTo(String image)
Returns true if this node's image is equal to the given string.- Parameters:
image
- The image to check
-
getBeginLine
int getBeginLine()
-
getBeginColumn
int getBeginColumn()
-
getEndLine
int getEndLine()
-
getEndColumn
int getEndColumn()
-
getDataFlowNode
@Deprecated DataFlowNode getDataFlowNode()
Deprecated.This is Java-specific and will be removed from this interface
-
setDataFlowNode
@Deprecated void setDataFlowNode(DataFlowNode dataFlowNode)
Deprecated.This is Java-specific and will be removed from this interface
-
isFindBoundary
@DeprecatedAttribute boolean isFindBoundary()
Returns true if this node is considered a boundary by traversal methods. Traversal methods such asgetFirstDescendantOfType(Class)
don't look past such boundaries by default, which is usually the expected thing to do. For example, in Java, lambdas and nested classes are considered find boundaries.Note: This attribute is deprecated for XPath queries. It is not useful for XPath queries and will be removed with PMD 7.0.0.
-
getNthParent
Node getNthParent(int n)
Returns the n-th parent or null if there are less thann
ancestors.- Parameters:
n
- how many ancestors to iterate over.- Returns:
- the n-th parent or null.
- Throws:
IllegalArgumentException
- ifn
is negative or zero.
-
getFirstParentOfType
<T> T getFirstParentOfType(Class<T> parentType)
Traverses up the tree to find the first parent instance of type parentType or one of its subclasses.- Type Parameters:
T
- The type you want to find- Parameters:
parentType
- Class literal of the type you want to find- Returns:
- Node of type parentType. Returns null if none found.
-
getParentsOfType
<T> List<T> getParentsOfType(Class<T> parentType)
Traverses up the tree to find all of the parent instances of type parentType or one of its subclasses. The nodes are ordered deepest-first.- Type Parameters:
T
- The type you want to find- Parameters:
parentType
- Class literal of the type you want to find- Returns:
- List of parentType instances found.
-
getFirstParentOfAnyType
@Deprecated <T> T getFirstParentOfAnyType(Class<? extends T>... parentTypes)
Deprecated.This method causes an unchecked warning at call sites. PMD 7 will provide a way to do the same thing without the warning.Gets the first parent that's an instance of any of the given types.- Type Parameters:
T
- Most specific common type of the parameters- Parameters:
parentTypes
- Types to look for- Returns:
- The first parent with a matching type. Returns null if there is no such parent
-
findChildrenOfType
<T> List<T> findChildrenOfType(Class<T> childType)
Traverses the children to find all the instances of type childType or one of its subclasses.- Parameters:
childType
- class which you want to find.- Returns:
- List of all children of type childType. Returns an empty list if none found.
- See Also:
if traversal of the entire tree is needed.
-
findDescendantsOfType
<T> List<T> findDescendantsOfType(Class<? extends T> targetType)
Traverses down the tree to find all the descendant instances of type descendantType without crossing find boundaries.- Parameters:
targetType
- class which you want to find.- Returns:
- List of all children of type targetType. Returns an empty list if none found.
-
findDescendantsOfType
@Deprecated <T> void findDescendantsOfType(Class<T> targetType, List<T> results, boolean crossFindBoundaries)
Deprecated.UsefindDescendantsOfType(Class, boolean)
instead, which returns a result list.Traverses down the tree to find all the descendant instances of type descendantType.- Parameters:
targetType
- class which you want to find.results
- list to store the matching descendantscrossFindBoundaries
- iffalse
, recursion stops for nodes for whichisFindBoundary()
istrue
-
findDescendantsOfType
<T> List<T> findDescendantsOfType(Class<T> targetType, boolean crossFindBoundaries)
Traverses down the tree to find all the descendant instances of type descendantType.- Parameters:
targetType
- class which you want to find.crossFindBoundaries
- iffalse
, recursion stops for nodes for whichisFindBoundary()
istrue
- Returns:
- List of all matching descendants
-
getFirstChildOfType
<T> T getFirstChildOfType(Class<T> childType)
Traverses the children to find the first instance of type childType.- Parameters:
childType
- class which you want to find.- Returns:
- Node of type childType. Returns
null
if none found. - See Also:
if traversal of the entire tree is needed.
-
getFirstDescendantOfType
<T> T getFirstDescendantOfType(Class<T> descendantType)
Traverses down the tree to find the first descendant instance of type descendantType without crossing find boundaries.- Parameters:
descendantType
- class which you want to find.- Returns:
- Node of type descendantType. Returns
null
if none found.
-
hasDescendantOfType
<T> boolean hasDescendantOfType(Class<T> type)
Finds if this node contains a descendant of the given type without crossing find boundaries.- Parameters:
type
- the node type to search- Returns:
true
if there is at least one descendant of the given type
-
findChildNodesWithXPath
@Deprecated List<? extends Node> findChildNodesWithXPath(String xpathString) throws org.jaxen.JaxenException
Deprecated.This is very inefficient and should not be used in new code. PMD 7.0.0 will remove support for this method.Returns all the nodes matching the xpath expression.- Parameters:
xpathString
- the expression to check- Returns:
- List of all matching nodes. Returns an empty list if none found.
- Throws:
org.jaxen.JaxenException
- if the xpath is incorrect or fails altogether
-
hasDescendantMatchingXPath
@Deprecated boolean hasDescendantMatchingXPath(String xpathString)
Deprecated.This is very inefficient and should not be used in new code. PMD 7.0.0 will remove support for this method.Checks whether at least one descendant matches the xpath expression.- Parameters:
xpathString
- the expression to check- Returns:
- true if there is a match
-
getAsDocument
@Deprecated Document getAsDocument()
Deprecated.Converting a tree to a DOM is not a standard use case. The implementation rethrows aParserConfigurationException
as aRuntimeException
, but a caller should handle it if he really wants to do this. Another problem is that this is available on any node, yet only the root node of a tree corresponds really to a document. The conversion is easy to implement anyway, and does not have to be part of this API.Get a DOM Document which contains Elements and Attributes representative of this Node and it's children. Essentially a DOM tree representation of the Node AST, thereby allowing tools which can operate upon DOM to also indirectly operate on the AST.
-
getUserData
@Deprecated Object getUserData()
Deprecated.UsegetUserMap()
Get the user data associated with this node. By default there is no data, unless it has been set viasetUserData(Object)
.- Returns:
- The user data set on this node.
-
setUserData
@Deprecated void setUserData(Object userData)
Deprecated.UsegetUserMap()
Set the user data associated with this node.PMD itself will never set user data onto a node. Nor should any Rule implementation, as the AST nodes are shared between concurrently executing Rules (i.e. it is not thread-safe).
This API is most useful for external applications looking to leverage PMD's robust support for AST structures, in which case application specific annotations on the AST nodes can be quite useful.
- Parameters:
userData
- The data to set on this node.
-
remove
@Deprecated @InternalApi void remove()
Deprecated.This is internal API and will be removed from this interface with 7.0.0Remove the current node from its parent.
-
removeChildAtIndex
@Deprecated @InternalApi void removeChildAtIndex(int childIndex)
Deprecated.This is internal API and will be removed from this interface with 7.0.0This method tells the node to remove the child node at the given index from the node's list of children, if any; if not, no changes are done.- Parameters:
childIndex
- The index of the child to be removed
-
getUserMap
DataMap<DataMap.DataKey<?,?>> getUserMap()
Returns a data map used to store additional information on this node. This replaces the legacygetUserData()
/setUserData(Object)
.- Returns:
- The user data map of this node
-
getParent
Node getParent()
Returns the parent of this node, or null if this is the root of the tree.This method should be preferred to
jjtGetParent()
.- Returns:
- The parent of this node
-
getChild
Node getChild(int index)
Returns the child of this node at the given index.- Throws:
IndexOutOfBoundsException
- if the index is negative or greater thangetNumChildren()
.
-
getNumChildren
int getNumChildren()
Returns the number of children of this node.
-
getIndexInParent
int getIndexInParent()
Returns the index of this node in its parent's children. If this node is a root node, returns -1.This method replaces
jjtGetChildIndex()
, whose name was JJTree-specific.- Returns:
- The index of this node in its parent's children
-
getXPathNodeName
String getXPathNodeName()
Gets the name of the node that is used to match it with XPath queries.- Returns:
- The XPath node name
-
getXPathAttributesIterator
Iterator<Attribute> getXPathAttributesIterator()
Returns an iterator enumerating all the attributes that are available from XPath for this node.- Returns:
- An attribute iterator for this node
-
children
Iterable<? extends Node> children()
Returns an iterable enumerating the children of this node. Use it with a foreach loop:for (Node child : node.children()) { // process child }
This method's return type will be changed to NodeStream in PMD 7, which is a more powerful kind of iterable. The change will be source compatible.
- Returns:
- A new iterable for the children of this node
-
-