Description

An abstract syntax tree should be abstract, but in the same time, should not be too abstract. One of the base interfaces for PMD's AST for all languages is net.sourceforge.pmd.lang.ast.Node, which provides the methods Node#getImage() and Node#hasImageEqualTo(java.lang.String).

However, these methods don't necessarily make sense for all nodes in all contexts. That's why getImage() often returns just null. Also, the name is not very describing. AST nodes should try to use more specific names, such as getValue() or getName().

For PMD 7, most languages have been adapted (#4782). And when writing XPath rules, you need to replace @Image with whatever is appropriate now (e.g. @Name).

There are 4 languages, which still need to be refactored:

• Apex
• Java
• PLSQL
• Visualforce

The getImage() method should be annotated with @deprecated and @DeprecatedAttribute and a replacement method with a better name should be provided.

There are also other base class implementations, that need to be deprecated:

• net.sourceforge.pmd.lang.ast.impl.javacc.AbstractJjtreeNode#getImage

Special considerations:

• XPathRule requires something to get the message for reporting violations. Currently it is getImage(). Maybe we need to extend Reportable, to provide something like a main attribute for nodes. Usually, this feature is only used for variable/field names to be present in the rule violation message.

  • Maybe add an annotation "@MainXPathAttribute" to mark one getter as the main one
  • Then we could figure this out at runtime (refs Node#getXPathAttributesIterator())

• Maybe add a custom PMD rule to dogfooding ruleset - but probably not needed as we are going to remove getImage anyway.

Current status (2024-01-06)

• in PMD 6.55.0, the methods Node#getImage() and Node#hasImageEqualTo() are not deprecated
• in PMD 7.0.0-rc4, these methods are deprecated, but no alternative (where needed) has been provided. Refactoring for Java has been started in [java] Remove usages of getImage in java module #4352.
• The methods can't be deleted without more work. Leaving these methods deprecated creates many deprecation warnings without the possibility to resolve them.
• in [core] Avoid using getImage/@Image #4782 most languages have been refactored

Plan

• [core] Undeprecate Node::getImage() in PMD 7 #4792
  • undeprecate getImage() for PMD 7, but keep a future note in the javadoc, that this will be deprecated and shouldn't be used anymore.
  • to be done in 7.0.0
• Deprecate getImage/@Image #4787
  • to be done in 7.x
  • step by step deprecate first in the individual languages the usage of getImage by providing at the same time the alternative.
  • once all the remaining languages have been refactored, we can deprecate getImage in Node.
• [core] Remove Node::getImage #4318
  • in PMD 8, we can remove these methods.

Related issues, PRs

• [core] Remove Node::getImage #4318
• [core] Avoid using getImage/@Image #4782
• [java] Remove usages of getImage in java module #4352
• [core] Undeprecate Node::getImage() in PMD 7 #4792