Class DomXPathRule
- java.lang.Object
-
- net.sourceforge.pmd.properties.AbstractPropertySource
-
- net.sourceforge.pmd.lang.rule.AbstractRule
-
- net.sourceforge.pmd.lang.xml.rule.DomXPathRule
-
- All Implemented Interfaces:
PropertySource
,Rule
public class DomXPathRule extends AbstractRule
XPath rule that executes an expression on the DOM directly, and not on the PMD AST wrapper. The XPath expressions adheres to the XPath (2.0) spec, so they can be tested in any existing XPath testing tools instead of just the PMD designer (google "xpath test"). Usage of this class is strongly recommended over the standardXPathRule
, which is mostly useful in other PMD languages.Differences with
This rule andXPathRule
XPathRule
do not accept exactly the same queries, becauseXPathRule
implements the XPath spec in an ad-hoc way. The main differences are:XPathRule
uses elements to represent text nodes. This is contrary to the XPath spec, in which element and text nodes are different kinds of nodes. To replace the query//elt/text[@Image="abc"]
, use the XPath functiontext()
, eg//elt[text()="abc"]
.XPathRule
adds additional attributes to each element (eg@BeginLine
and@Image
). These attributes are not XML attributes, so they are not accessible using DomXPathRule rule. Instead, use the XPath functionspmd:startLine(node)
,pmd:endLine(node)
and related. For instance, replace//elt[@EndLine - @BeginLine > 10]
withelt[pmd:endLine(.) - pmd:startLine(.) > 10]
.XPathRule
uses an element called"document"
as the root node of every XML AST. This node does not have the correct node kind, as it's an element, not a document. To replace/document/RootNode
, use just/RootNode
.XPathRule
ignores comments and processing instructions (eg FXML's<?import javafx.Node ?>
). This rule makes them accessible with the regular XPath syntax. The following finds all comments in the file:
The following finds only top-level comments starting with "prefix"://comment()
Note the use of/comment()[fn:starts-with(fn:string(.), "prefix")]
fn:string
. As an example of matching processing instructions, the following fetches all<?import ... ?>
processing instructions.
The string value of the instruction can be found with/processing-instruction('import')
fn:string
.
Additionally, this rule only supports XPath 2.0, with no option for configuration. This will be bumped to XPath 3.1 in PMD 7.
Namespace-sensitivity
Another important difference is that this rule is namespace-sensitive. If the tested XML documents use a schema (
xmlns
attribute on the root), you should set the propertydefaultNsUri
on the rule with the value of thexmlns
attribute. Otherwise node tests won't match unless you use a wildcard URI prefix (*:nodeName
).For instance for the document
the XPath query<foo xmlns="http://company.com/aschema"> </foo>
//foo
will not match anything, while//*:foo
will. If you set the propertydefaultNsUri
to"http://company.com/aschema"
, then//foo
will be expanded to//Q{http://company.com/aschema}foo
, and match thefoo
node. The behaviour is equivalent in the following document:<my:foo xmlns:my='http://company.com/aschema'> </my:foo>
However, for the document
the XPath queries<foo> </foo>
//foo
and//*:foo
both match, because//foo
is expanded to//Q{}foo
(local name foo, empty URI), and the document has no default namespace (= the empty default namespace).Note that explicitly specifying URIs with
Q{...}localName
as in this documentation is XPath 3.1 syntax and will only be available in PMD 7.- Since:
- PMD 6.44.0
- Author:
- Clément Fournier
-
-
Field Summary
-
Fields inherited from class net.sourceforge.pmd.properties.AbstractPropertySource
propertyDescriptors, propertyValuesByDescriptor
-
Fields inherited from interface net.sourceforge.pmd.Rule
VIOLATION_SUPPRESS_REGEX_DESCRIPTOR, VIOLATION_SUPPRESS_XPATH_DESCRIPTOR
-
-
Constructor Summary
Constructors Constructor Description DomXPathRule()
DomXPathRule(String xpath)
DomXPathRule(String xpath, String defaultNsUri)
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
apply(List<? extends Node> nodes, RuleContext ctx)
-
Methods inherited from class net.sourceforge.pmd.lang.rule.AbstractRule
addExample, addRuleChainVisit, addRuleChainVisit, addViolation, addViolation, addViolation, addViolationWithMessage, addViolationWithMessage, addViolationWithMessage, asCtx, deepCopy, deepCopyValuesTo, end, equals, getDescription, getExamples, getExternalInfoUrl, getLanguage, getMaximumLanguageVersion, getMessage, getMinimumLanguageVersion, getName, getParserOptions, getPriority, getPropertySourceType, getRuleChainVisits, getRuleClass, getRuleSetName, getSince, hashCode, isDeprecated, isDfa, isMultifile, isRuleChain, isTypeResolution, setDeprecated, setDescription, setDfa, setExternalInfoUrl, setLanguage, setMaximumLanguageVersion, setMessage, setMinimumLanguageVersion, setMultifile, setName, setPriority, setRuleClass, setRuleSetName, setSince, setTypeResolution, setUsesDFA, setUsesMultifile, setUsesTypeResolution, start, usesDFA, usesMultifile, usesRuleChain, usesTypeResolution
-
Methods inherited from class net.sourceforge.pmd.properties.AbstractPropertySource
copyPropertyDescriptors, copyPropertyValues, definePropertyDescriptor, dysfunctionReason, getOverriddenPropertiesByPropertyDescriptor, getOverriddenPropertyDescriptors, getPropertiesByPropertyDescriptor, getProperty, getPropertyDescriptor, getPropertyDescriptors, hasDescriptor, ignoredProperties, isPropertyOverridden, setProperty, setProperty, useDefaultValueFor, usesDefaultValues
-
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
-
Methods inherited from interface net.sourceforge.pmd.properties.PropertySource
definePropertyDescriptor, dysfunctionReason, getOverriddenPropertiesByPropertyDescriptor, getOverriddenPropertyDescriptors, getPropertiesByPropertyDescriptor, getProperty, getPropertyDescriptor, getPropertyDescriptors, hasDescriptor, ignoredProperties, isPropertyOverridden, setProperty, setProperty, useDefaultValueFor, usesDefaultValues
-
-