Revapi Maven Plugin

Maven integration for Revapi.

Note:This goal should be used as a Maven report.

Full name:

org.revapi:revapi-maven-plugin:0.9.2:report

Description:

(no description)

Attributes:

  • Requires a Maven project to be executed.
  • Requires dependency collection of artifacts in scope: compile+runtime.
  • Since version: 0.1.
  • Binds by default to the lifecycle phase: site.

Optional Parameters

Name Type Since Description
alwaysCheckForReleaseVersion boolean 0.1 If true (the default) revapi will always download the information about the latest version from the remote repositories (instead of using locally cached info). This will respect the offline settings.
Default value is: true.
User property is: revapi.alwaysCheckForReleaseVersion.
analysisConfiguration PlexusConfiguration 0.1 The JSON configuration of various analysis options. The available options depend on what analyzers are present on the plugins classpath through the <dependencies>.

These settings take precedence over the configuration loaded from analysisConfigurationFiles.


analysisConfigurationFiles Object[] 0.1 The list of files containing the configuration of various analysis options. The available options depend on what analyzers are present on the plugins classpath through the <dependencies>.

The analysisConfiguration can override the settings present in the files.

The list is either a list of strings or has the following form:


  <analysisConfigurationFiles>
       <configurationFile>
           <path>path/to/the/file/relative/to/project/base/dir</path>
           <resource>path/to/the/file/in/one/of/the/dependencies</resource>
           <roots>
               <root>configuration/root1</root>
               <root>configuration/root2</root>
               ...
           </roots>
       </configurationFile>
       ...
   </analysisConfigurationFiles>

where
  • path is the path on the filesystem,
  • resource is the path to the resource file in one of the artifacts the plugin depends on
  • roots is optional and specifies the subtrees of the JSON/XML config that should be used for configuration. If not specified, the whole file is taken into account.
Either path or resource has to be specified but not both. The configuration/root1 and configuration/root2 are paths to the roots of the configuration inside that JSON/XML config file. This might be used in cases where multiple configurations are stored within a single file and you want to use a particular one.

An example of this might be a config file which contains API changes to be ignored in all past versions of a library. The classes to be ignored are specified in a configuration that is specific for each version:


   {
        "0.1.0" : [
            {
                "extension": "revapi.ignore",
                "configuration": [
                    {
                        "code" : "java.method.addedToInterface",
                        "new" : "method void com.example.MyInterface::newMethod()",
                        "justification" : "This interface is not supposed to be implemented by clients."
                    },
                    ...
                ]
            }
        ],
        "0.2.0" : [
            ...
        ]
    }


User property is: revapi.analysisConfigurationFiles.
checkDependencies boolean 0.1 Whether to include the dependencies in the API checks. This is the default thing to do because your API might be exposing classes from the dependencies and thus classes from your dependencies could become part of your API.

However, setting this to false might be useful in situations where you have checked your dependencies in another module and don't want do that again. In that case, you might want to configure Revapi to ignore missing classes because it might find the classes from your dependencies as used in your API and would complain that it could not find it. See the docs.


Default value is: true.
User property is: revapi.checkDependencies.
disallowedExtensions String 0.1 A comma-separated list of extensions (fully-qualified class names thereof) that are not taken into account during API analysis. By default, all extensions that are found on the classpath are used.

You can modify this set if you use another extensions that change the found differences in a way that the determined new version would not correspond to what it should be.


User property is: revapi.disallowedExtensions.
failOnMissingConfigurationFiles boolean 0.1 Set to false if you want to tolerate files referenced in the analysisConfigurationFiles missing on the filesystem and therefore not contributing to the analysis configuration.

The default is true, which means that a missing analysis configuration file will fail the build.


Default value is: true.
User property is: revapi.failOnMissingConfigurationFiles.
failOnUnresolvedArtifacts boolean 0.1 If true, the build will fail if one of the old or new artifacts fails to be resolved. Defaults to false.
Default value is: false.
User property is: revapi.failOnUnresolvedArtifacts.
failOnUnresolvedDependencies boolean 0.1 If true, the build will fail if some of the dependencies of the old or new artifacts fail to be resolved. Defaults to false.
Default value is: false.
User property is: revapi.failOnUnresolvedDependencies.
generateSiteReport boolean 0.1 Set this to false if you want to use the goal to generate other kind of output than the default report for the Maven-generated site. You can generate such output by using different reporting extensions (like revapi-reporter-text).
Default value is: true.
User property is: revapi.generateSiteReport.
newArtifacts String[] 0.1 The coordinates of the new artifacts. These are the full GAVs of the artifacts, which means that you can compare different artifacts than the one being built. If you merely want to specify the artifact being built, use newVersion property instead.
User property is: revapi.newArtifacts.
newVersion String 0.1 The new version of the artifact. Defaults to "${project.version}".
Default value is: ${project.version}.
User property is: revapi.newVersion.
oldArtifacts String[] 0.1 The coordinates of the old artifacts. Defaults to single artifact with the latest released version of the current project. If the this property is null, the oldVersion property is checked for a value of the old version of the artifact being built.
User property is: revapi.oldArtifacts.
oldVersion String 0.1 If you don't want to compare a different artifact than the one being built, specifying the just the old version is simpler way of specifying the old artifact. The default value is "RELEASE" meaning that the old version is the last released version of the artifact being built.
Default value is: RELEASE.
User property is: revapi.oldVersion.
reportSeverity FailSeverity 0.1 Problems with this or higher severity will be included in the report. Possible values: equivalent, nonBreaking, potentiallyBreaking, breaking.
Default value is: potentiallyBreaking.
User property is: revapi.reportSeverity.
resolveProvidedDependencies boolean 0.1 When establishing the API classes, Revapi by default also looks through the provided dependencies. The reason for this is that even though such dependencies do not appear in the transitive dependency set established by maven, they need to be present both on the compilation and runtime classpath of the module. Therefore, the classes in the module are free to expose classes from a provided dependency as API elements.

In rare circumstances this is not a desired behavior though. It is undesired if for example the classes from the provided dependency are used only for establishing desired build order or when they are used in some non-standard scenarios during the build and actually not needed at runtime.


Default value is: true.
User property is: revapi.resolveProvidedDependencies.
skip boolean 0.1 Whether to skip the mojo execution.
Default value is: false.
User property is: revapi.skip.
versionFormat String 0.1 If set, this property demands a format of the version string when the oldVersion or newVersion parameters are set to RELEASE or LATEST special version strings.

Because Maven will report the newest non-snapshot version as the latest release, we might end up comparing a .Beta or other pre-release versions with the new version. This might not be what you want and setting the versionFormat will make sure that a newest version conforming to the version format is used instead of the one resolved by Maven by default.

This parameter is a regular expression pattern that the version string needs to match in order to be considered a RELEASE.


User property is: revapi.versionFormat.

Parameter Details

alwaysCheckForReleaseVersion:

If true (the default) revapi will always download the information about the latest version from the remote repositories (instead of using locally cached info). This will respect the offline settings.
  • Type: boolean
  • Since: 0.1
  • Required: No
  • User Property: revapi.alwaysCheckForReleaseVersion
  • Default: true

analysisConfiguration:

The JSON configuration of various analysis options. The available options depend on what analyzers are present on the plugins classpath through the &lt;dependencies&gt;.

These settings take precedence over the configuration loaded from analysisConfigurationFiles.

  • Type: org.codehaus.plexus.configuration.PlexusConfiguration
  • Since: 0.1
  • Required: No

analysisConfigurationFiles:

The list of files containing the configuration of various analysis options. The available options depend on what analyzers are present on the plugins classpath through the &lt;dependencies&gt;.

The analysisConfiguration can override the settings present in the files.

The list is either a list of strings or has the following form:


  <analysisConfigurationFiles>
       <configurationFile>
           <path>path/to/the/file/relative/to/project/base/dir</path>
           <resource>path/to/the/file/in/one/of/the/dependencies</resource>
           <roots>
               <root>configuration/root1</root>
               <root>configuration/root2</root>
               ...
           </roots>
       </configurationFile>
       ...
   </analysisConfigurationFiles>

where
  • path is the path on the filesystem,
  • resource is the path to the resource file in one of the artifacts the plugin depends on
  • roots is optional and specifies the subtrees of the JSON/XML config that should be used for configuration. If not specified, the whole file is taken into account.
Either path or resource has to be specified but not both. The configuration/root1 and configuration/root2 are paths to the roots of the configuration inside that JSON/XML config file. This might be used in cases where multiple configurations are stored within a single file and you want to use a particular one.

An example of this might be a config file which contains API changes to be ignored in all past versions of a library. The classes to be ignored are specified in a configuration that is specific for each version:


   {
        "0.1.0" : [
            {
                "extension": "revapi.ignore",
                "configuration": [
                    {
                        "code" : "java.method.addedToInterface",
                        "new" : "method void com.example.MyInterface::newMethod()",
                        "justification" : "This interface is not supposed to be implemented by clients."
                    },
                    ...
                ]
            }
        ],
        "0.2.0" : [
            ...
        ]
    }

  • Type: java.lang.Object[]
  • Since: 0.1
  • Required: No
  • User Property: revapi.analysisConfigurationFiles

checkDependencies:

Whether to include the dependencies in the API checks. This is the default thing to do because your API might be exposing classes from the dependencies and thus classes from your dependencies could become part of your API.

However, setting this to false might be useful in situations where you have checked your dependencies in another module and don't want do that again. In that case, you might want to configure Revapi to ignore missing classes because it might find the classes from your dependencies as used in your API and would complain that it could not find it. See the docs.

  • Type: boolean
  • Since: 0.1
  • Required: No
  • User Property: revapi.checkDependencies
  • Default: true

disallowedExtensions:

A comma-separated list of extensions (fully-qualified class names thereof) that are not taken into account during API analysis. By default, all extensions that are found on the classpath are used.

You can modify this set if you use another extensions that change the found differences in a way that the determined new version would not correspond to what it should be.

  • Type: java.lang.String
  • Since: 0.1
  • Required: No
  • User Property: revapi.disallowedExtensions

failOnMissingConfigurationFiles:

Set to false if you want to tolerate files referenced in the analysisConfigurationFiles missing on the filesystem and therefore not contributing to the analysis configuration.

The default is true, which means that a missing analysis configuration file will fail the build.

  • Type: boolean
  • Since: 0.1
  • Required: No
  • User Property: revapi.failOnMissingConfigurationFiles
  • Default: true

failOnUnresolvedArtifacts:

If true, the build will fail if one of the old or new artifacts fails to be resolved. Defaults to false.
  • Type: boolean
  • Since: 0.1
  • Required: No
  • User Property: revapi.failOnUnresolvedArtifacts
  • Default: false

failOnUnresolvedDependencies:

If true, the build will fail if some of the dependencies of the old or new artifacts fail to be resolved. Defaults to false.
  • Type: boolean
  • Since: 0.1
  • Required: No
  • User Property: revapi.failOnUnresolvedDependencies
  • Default: false

generateSiteReport:

Set this to false if you want to use the goal to generate other kind of output than the default report for the Maven-generated site. You can generate such output by using different reporting extensions (like revapi-reporter-text).
  • Type: boolean
  • Since: 0.1
  • Required: No
  • User Property: revapi.generateSiteReport
  • Default: true

newArtifacts:

The coordinates of the new artifacts. These are the full GAVs of the artifacts, which means that you can compare different artifacts than the one being built. If you merely want to specify the artifact being built, use newVersion property instead.
  • Type: java.lang.String[]
  • Since: 0.1
  • Required: No
  • User Property: revapi.newArtifacts

newVersion:

The new version of the artifact. Defaults to "${project.version}".
  • Type: java.lang.String
  • Since: 0.1
  • Required: No
  • User Property: revapi.newVersion
  • Default: ${project.version}

oldArtifacts:

The coordinates of the old artifacts. Defaults to single artifact with the latest released version of the current project. If the this property is null, the oldVersion property is checked for a value of the old version of the artifact being built.
  • Type: java.lang.String[]
  • Since: 0.1
  • Required: No
  • User Property: revapi.oldArtifacts

oldVersion:

If you don't want to compare a different artifact than the one being built, specifying the just the old version is simpler way of specifying the old artifact. The default value is "RELEASE" meaning that the old version is the last released version of the artifact being built.
  • Type: java.lang.String
  • Since: 0.1
  • Required: No
  • User Property: revapi.oldVersion
  • Default: RELEASE

reportSeverity:

Problems with this or higher severity will be included in the report. Possible values: equivalent, nonBreaking, potentiallyBreaking, breaking.
  • Type: org.revapi.maven.FailSeverity
  • Since: 0.1
  • Required: No
  • User Property: revapi.reportSeverity
  • Default: potentiallyBreaking

resolveProvidedDependencies:

When establishing the API classes, Revapi by default also looks through the provided dependencies. The reason for this is that even though such dependencies do not appear in the transitive dependency set established by maven, they need to be present both on the compilation and runtime classpath of the module. Therefore, the classes in the module are free to expose classes from a provided dependency as API elements.

In rare circumstances this is not a desired behavior though. It is undesired if for example the classes from the provided dependency are used only for establishing desired build order or when they are used in some non-standard scenarios during the build and actually not needed at runtime.

  • Type: boolean
  • Since: 0.1
  • Required: No
  • User Property: revapi.resolveProvidedDependencies
  • Default: true

skip:

Whether to skip the mojo execution.
  • Type: boolean
  • Since: 0.1
  • Required: No
  • User Property: revapi.skip
  • Default: false

versionFormat:

If set, this property demands a format of the version string when the oldVersion or newVersion parameters are set to RELEASE or LATEST special version strings.

Because Maven will report the newest non-snapshot version as the latest release, we might end up comparing a .Beta or other pre-release versions with the new version. This might not be what you want and setting the versionFormat will make sure that a newest version conforming to the version format is used instead of the one resolved by Maven by default.

This parameter is a regular expression pattern that the version string needs to match in order to be considered a RELEASE.

  • Type: java.lang.String
  • Since: 0.1
  • Required: No
  • User Property: revapi.versionFormat

Back to top

Msb3 Maven skin by Marek Romanowski.