Edit me

We’re excited to bring you the next major version of PMD! Here are the major features and changes we’re working on. To give us feedback or to suggest a new feature, drop us a line on Gitter!

New Features

TODO

Java grammar changes

New API support guidelines

What’s new

Until now, all released public members and types were implicitly considered part of PMD’s public API, including inheritance-specific members (protected members, abstract methods). We have maintained those APIs with the goal to preserve full binary compatibility between minor releases, only breaking those APIs infrequently, for major releases.

In order to allow PMD to move forward at a faster pace, this implicit contract will be invalidated with PMD 7.0.0. We now introduce more fine-grained distinctions between the type of compatibility support we guarantee for our libraries, and ways to make them explicit to clients of PMD.

.internal packages and @InternalApi annotation

Internal API is meant for use only by the main PMD codebase. Internal types and methods may be modified in any way, or even removed, at any time.

Any API in a package that contains an .internal segment is considered internal. The @InternalApi annotation will be used for APIs that have to live outside of these packages, e.g. methods of a public type that shouldn’t be used outside of PMD (again, these can be removed anytime).

@ReservedSubclassing

Types marked with the @ReservedSubclassing annotation are only meant to be subclassed by classes within PMD. As such, we may add new abstract methods, or remove protected methods, at any time. All published public members remain supported. The annotation is not inherited, which means a reserved interface doesn’t prevent its implementors to be subclassed.

@Experimental

APIs marked with the @Experimental annotation at the class or method level are subject to change. They can be modified in any way, or even removed, at any time. You should not use or rely on them in any production code. They are purely to allow broad testing and feedback.

@Deprecated

APIs marked with the @Deprecated annotation at the class or method level will remain supported until the next major release but it is recommended to stop using them.

The transition

All currently supported APIs will remain so until 7.0.0. All APIs that are to be moved to .internal packages or hidden will be tagged @InternalApi before that major release, and the breaking API changes will be performed in 7.0.0.

Planned API removals

List of currently deprecated APIs

6.17.0

No changes.

6.16.0

Deprecated APIs

Reminder: Please don’t use members marked with the annotation InternalApi, as they will likely be removed, hidden, or otherwise intentionally broken with 7.0.0.

In ASTs

As part of the changes we’d like to do to AST classes for 7.0.0, we would like to hide some methods and constructors that rule writers should not have access to. The following usages are now deprecated in the Java AST (with other languages to come):

  • Manual instantiation of nodes. Constructors of node classes are deprecated and marked InternalApi. Nodes should only be obtained from the parser, which for rules, means that never need to instantiate node themselves. Those constructors will be made package private with 7.0.0.
  • Subclassing of abstract node classes, or usage of their type. Version 7.0.0 will bring a new set of abstractions that will be public API, but the base classes are and will stay internal. You should not couple your code to them.
    • In the meantime you should use interfaces like JavaNode or Node, or the other published interfaces in this package, to refer to nodes generically.
    • Concrete node classes will be made final with 7.0.0.
  • Setters found in any node class or interface. Rules should consider the AST immutable. We will make those setters package private with 7.0.0.

Please look at net.sourceforge.pmd.lang.java.ast to find out the full list of deprecations.

6.15.0

Deprecated APIs
For removal

6.14.0

No changes.

6.13.0

Command Line Interface

The start scripts run.sh, pmd.bat and cpd.bat support the new environment variable PMD_JAVA_OPTS. This can be used to set arbitrary JVM options for running PMD, such as memory settings (e.g. PMD_JAVA_OPTS=-Xmx512m) or enable preview language features (e.g. PMD_JAVA_OPTS=--enable-preview).

The previously available variables such as OPTS or HEAPSIZE are deprecated and will be removed with PMD 7.0.0.

Deprecated API

  • CodeClimateRule is deprecated in 7.0.0 because it was unused for 2 years and created an unwanted dependency. Properties “cc_categories”, “cc_remediation_points_multiplier”, “cc_block_highlighting” will also be removed. See #1702 for more.

  • The Apex ruleset rulesets/apex/ruleset.xml has been deprecated and will be removed in 7.0.0. Please use the new quickstart ruleset rulesets/apex/quickstart.xml instead.

6.12.0

No changes.

6.11.0

6.10.0

Properties framework

The properties framework is about to get a lifting, and for that reason, we need to deprecate a lot of APIs to remove them in 7.0.0. The proposed changes to the API are described on the wiki

Changes to how you define properties

Here’s an example:

// Before 7.0.0, these are equivalent:
IntegerProperty myProperty = new IntegerProperty("score", "Top score value", 1, 100, 40, 3.0f);
IntegerProperty myProperty = IntegerProperty.named("score").desc("Top score value").range(1, 100).defaultValue(40).uiOrder(3.0f);

// They both map to the following in 7.0.0
PropertyDescriptor<Integer> myProperty = PropertyFactory.intProperty("score").desc("Top score value").require(inRange(1, 100)).defaultValue(40);

You’re highly encouraged to migrate to using this new API as soon as possible, to ease your migration to 7.0.0.

Architectural simplifications
Changes to the PropertyDescriptor interface
  • preferredRowCount is deprecated with no intended replacement. It was never implemented, and does not belong in this interface. The methods uiOrder and compareTo(PropertyDescriptor) are deprecated for the same reason. These methods mix presentation logic with business logic and are not necessary for PropertyDescriptors to work. PropertyDescriptor will not extend Comparable<PropertyDescriptor> anymore come 7.0.0.
  • The method propertyErrorFor is deprecated and will be removed with no intended replacement. It’s really just a shortcut for prop.errorFor(rule.getProperty(prop)).
  • T valueFrom(String) and String asDelimitedString(T) are deprecated and will be removed. These were used to serialize and deserialize properties to/from a string, but 7.0.0 will introduce a more flexible XML syntax which will make them obsolete.
  • isMultiValue and type are deprecated and won’t be replaced. The new XML syntax will remove the need for a divide between multi- and single-value properties, and will allow arbitrary types to be represented. Since arbitrary types may be represented, type will become obsolete as it can’t represent generic types, which will nevertheless be representable with the XML syntax. It was only used for documentation, but a new way to document these properties exhaustively will be added with 7.0.0.
  • errorFor is deprecated as its return type will be changed to Optional<String> with the shift to Java 8.
Deprecated APIs
For internalization
For removal

6.9.0

No changes.

6.8.0

  • A couple of methods and fields in net.sourceforge.pmd.properties.AbstractPropertySource have been deprecated, as they are replaced by already existing functionality or expose internal implementation details: propertyDescriptors, propertyValuesByDescriptor, copyPropertyDescriptors(), copyPropertyValues(), ignoredProperties(), usesDefaultValues(), useDefaultValueFor().

  • Some methods in net.sourceforge.pmd.properties.PropertySource have been deprecated as well: usesDefaultValues(), useDefaultValueFor(), ignoredProperties().

  • The class net.sourceforge.pmd.lang.rule.AbstractDelegateRule has been deprecated and will be removed with PMD 7.0.0. It is internally only in use by RuleReference.

  • The default constructor of net.sourceforge.pmd.lang.rule.RuleReference has been deprecated and will be removed with PMD 7.0.0. RuleReferences should only be created by providing a Rule and a RuleSetReference. Furthermore the following methods are deprecated: setRuleReference(), hasOverriddenProperty(), usesDefaultValues(), useDefaultValueFor().

6.7.0

  • All classes in the package net.sourceforge.pmd.lang.dfa.report have been deprecated and will be removed with PMD 7.0.0. This includes the class net.sourceforge.pmd.lang.dfa.report.ReportTree. The reason is, that this class is very specific to Java and not suitable for other languages. It has only been used for YAHTMLRenderer, which has been rewritten to work without these classes.

  • The nodes RUNSIGNEDSHIFT and RSIGNEDSHIFT are deprecated and will be removed from the AST with PMD 7.0.0. These represented the operator of ShiftExpression in two cases out of three, but they’re not needed and make ShiftExpression inconsistent. The operator of a ShiftExpression is now accessible through ShiftExpression#getOperator.

6.5.0

  • The utility class net.sourceforge.pmd.lang.java.ast.CommentUtil has been deprecated and will be removed with PMD 7.0.0. Its methods have been intended to parse javadoc tags. A more useful solution will be added around the AST node FormalComment, which contains as children JavadocElement nodes, which in turn provide access to the JavadocTag.

    All comment AST nodes (FormalComment, MultiLineComment, SingleLineComment) have a new method getFilteredComment() which provide access to the comment text without the leading /* markers.

  • The method AbstractCommentRule.tagsIndicesIn() has been deprecated and will be removed with PMD 7.0.0. It is not very useful, since it doesn’t extract the information in a useful way. You would still need check, which tags have been found, and with which data they might be accompanied.

6.4.0

  • The following classes in package net.sourceforge.pmd.benchmark have been deprecated: Benchmark, Benchmarker, BenchmarkReport, BenchmarkResult, RuleDuration, StringBuilderCR and TextReport. Their API is not supported anymore and is disconnected from the internals of PMD. Use the newer API based around TimeTracker instead, which can be found in the same package.
  • The class net.sourceforge.pmd.lang.java.xpath.TypeOfFunction has been deprecated. Use the newer TypeIsFunction in the same package.
  • The typeof methods in net.sourceforge.pmd.lang.java.xpath.JavaFunctions have been deprecated. Use the newer typeIs method in the same class instead..
  • The methods isA, isEither and isNeither of net.sourceforge.pmd.lang.java.typeresolution.TypeHelper. Use the new isExactlyAny and isExactlyNone methods in the same class instead.

6.2.0

  • The static method PMDParameters.transformParametersIntoConfiguration(PMDParameters) is now deprecated, for removal in 7.0.0. The new instance method PMDParameters.toConfiguration() replaces it.

  • The method ASTConstructorDeclaration.getParameters() has been deprecated in favor of the new method getFormalParameters(). This method is available for both ASTConstructorDeclaration and ASTMethodDeclaration.

6.1.0

  • The method getXPathNodeName is added to the Node interface, which removes the use of the toString of a node to get its XPath element name (see #569).
    • The default implementation provided in AbstractNode, will be removed with 7.0.0
    • With 7.0.0, the Node.toString method will not necessarily provide its XPath node name anymore.

  • The interface net.sourceforge.pmd.cpd.Renderer has been deprecated. A new interface net.sourceforge.pmd.cpd.renderer.CPDRenderer has been introduced to replace it. The main difference is that the new interface is meant to render directly to a java.io.Writer rather than to a String. This allows to greatly reduce the memory footprint of CPD, as on large projects, with many duplications, it was causing OutOfMemoryErrors (see #795).

    net.sourceforge.pmd.cpd.FileReporter has also been deprecated as part of this change, as it’s no longer needed.

6.0.1

  • The constant net.sourceforge.pmd.PMD.VERSION has been deprecated and will be removed with PMD 7.0.0. Please use net.sourceforge.pmd.PMDVersion.VERSION instead.

List of currently deprecated rules