Reclassify Transformation

Extension: revapi.reclassify

This extension is deprecated in favor of revapi.differences.

Using this extension one can reclassify certain API problems found during the analysis to become something else or for example reduce their severity.

Sample Configuration

[
  {
    "extension": "revapi.reclassify",
    "configuration": [
      {
        "regex" : false,
        "code" : "PROBLEM_CODE",
        "old" : "FULL_REPRESENTATION_OF_THE_OLD_ELEMENT",
        "new" : "FULL_REPRESENTATION_OF_THE_NEW_ELEMENT",
        "classify" : {
          "NEW_COMPATIBILITY_TYPE": "NEW_SEVERITY",
          "NEW_COMPATIBILITY_TYPE_2": "NEW_SEVERITY_2",
        },
        ... any other properties that correspond to the match parameters of the differences ...
      },
      ...
    ]
  }
]

<analysisConfiguration>
  <revapi.reclassify>
    <item>
      <regex>false</regex>
      <code>PROBLEM_CODE</code>
      <old>FULL_REPRESENTATION_OF_THE_OLD_ELEMENT</old>
      <new>FULL_REPRESENTATION_OF_THE_NEW_ELEMENT</new>
      <classify>
        <NEW_COMPATIBILITY_TYPE>NEW_SEVERITY</NEW_COMPATIBILITY_TYPE>
        <NEW_COMPATIBILITY_TYPE_2>NEW_SEVERITY_2</NEW_COMPATIBILITY_TYPE_2>
      </classify>
      ... any other properties that correspond to the match parameters of the differences ...
    </item>
  </revapi.reclassify>
</analysisConfiguration>

Properties

regex: If true (the default is false), the code, old and new values are understood to be java regular expressions.
code: Specifies the API problem code to reclassify. This is property mandatory.
old: Specifies the old element of the problem. Only if the problem’s old element matches this, the reclassification takes place. This property is optional.
new: Specifies the new element of the problem. Only if the problem’s new element matches this, the reclassification takes place. This property is optional.
classify: Specifies the new classification matrix of the problem. The keys are compatibility types, i.e. one of SOURCE, BINARY, SEMANTIC or OTHER and severities are one of NON_BREAKING, POTENTIALLY_BREAKING or BREAKING.
additional properties: The analyzers can define additional "match parameters" on the differences that can be used to further focus the reclassification rule. For java, see the list of the detected differences. Such additional properties always have a string value.

Example

By specifying the following configuration:

[
  {
    "extension": "revapi.reclassify",
    "configuration": [
      {
        "code" : "java.class.added",
        "new" : "class my.great.app.ForbiddenClass",
        "classify" : {
            "BINARY" : "BREAKING"
        }
      },
      {
        "code": "java.field.noLongerFinal",
        "classify": {
          "SEMANTIC": "BREAKING"
        }
      }
    ]
  }
]

or equivalently in XML

<analysisConfiguration>
  <revapi.reclassify>
    <item>
      <code>java.class.added</code>
      <new>class my.great.app.ForbiddenClass</new>
      <classify>
        <BINARY>BREAKING</BINARY>
      </classify>
    </item>
    <item>
      <code>java.field.noLongerFinal</code>
      <classify>
        <SEMANTIC>BREAKING</SEMANTIC>
      </classify>
    </item>
  </revapi.reclassify>
</analysisConfiguration>

it will be an API error if the class my.great.app.ForbiddenClass appears in the new version of a java library (granted this rule is somewhat weird and maybe not entirely useful, but it illustrates the purpose - you can come up with different policies that your code should follow and enforce them through such rules).

The other rule in the example is arguably more useful. It will declare it a breaking change if any (accessible) final field becomes mutable. This can be useful to make sure your immutable data structures remain immutable.