Getting Started

Revapi can be used in 4 ways. Either as a standalone java program, using its maven plugin or ant task during build or as an embedded library.

Maven

You can read more about the maven plugin in its dedicated section.

You can find the latest versions of the various Revapi components in the downloads section.

Revapi’s main purpose is to track API changes between releases. This is ideally done during build and so the maven integration is essential.

The basic usage of the Revapi’s maven plugin is quite simple. In your pom.xml, do:

<build>
    ...
    <plugins>
        ...
        <plugin>
            <groupId>org.revapi</groupId>
            <artifactId>revapi-maven-plugin</artifactId>
            <version>0.12.0</version>
            <dependencies>
                <dependency>
                    <groupId>org.revapi</groupId>
                    <artifactId>revapi-java</artifactId>
                    <version>0.22.0</version>
                </dependency>
                ...
            </dependencies>
            <executions>
                <execution>
                    <id>check</id>
                    <goals><goal>check</goal></goals>
                </execution>
            </executions>
        </plugin>
        ...
    </plugins>
    ...
</build>

By default, Revapi only bundles the basic features so in order to check your java code, you need to add the Revapi’s java extension as a dependency to the maven plugin.

For more detailed info, check the maven plugin’s site.

Gradle

There is an externally developed Gradle plugin contributed by Palantir, the gradle-revapi plugin. Please consult the home page of the project for usage guidelines and documentation.

Standalone Usage

More information about the Revapi’s CLI tool, can be obtained from its dedicated section.

First you need to download the standalone distribution of Revapi, say revapi-standalone-0.9.6.zip. Now you have to:

$ unzip revapi-standalone-0.9.6.zip
$ cd revapi-standalone-0.9.6

Your installation is now ready. To start using it, you can simply invoke

$ ./revapi.sh

(or if you’re unfortunate enough to be on windows)

> revapi.bat

and you will be presented with the usual usage information.

An invocation of Revapi could look like this:

./revapi.sh \
  --extensions=org.revapi:revapi-java:0.22.0,org.revapi:revapi-reporter-text:0.12.1 \
  --old=my-lib-0.1.0.jar --new=my-lib-0.2.0.jar -D revapi.reporter.text.minSeverity=BREAKING

Different extensions might define different configuration options that you might supply to them using either the -D command line parameter or they can be read from configuration file(s) specified by the -c option.

Ant

You can read more about the Revapi’s Ant task in its dedicated section.

There is also an Ant task to invoke Revapi analysis on arbitrary archives. The task implicitly supports the basic features but other extensions need to be added.

The following attributes are supported:

oldArchives

The FileSet of archives of the old version of the API

oldSupplementaryArchives

The FileSet of archives that support the old API (i.e. dependencies)

newArchives

The FileSet of archives of the new version of the API

newSupplementaryArchives

The FileSet of archives that support the new API (i.e. dependencies)

revapiClassPath

A Path to additional extensions to use with Revapi

configuration

A JSON string with the Revapi configuration

breakingSeverity

The minimal severity of differences that will be reported

An example for checking Java code:

<target name="api-check">
  <taskdef name="revapi" classname="org.revapi.ant.RevapiTask" classpath="lib/revapi-ant-task-0.10.0.jar"/>
  <revapi>
    <oldArchives file="mylib-1.0.jar"/>
    <newArchives file="mylib-1.1.jar"/>
    <revapiClassPath>
      <pathelement location="lib/revapi-java-0.22.0-uber.jar"/>
    </revapiClassPath>
  </revapi>
</target>

Notice the use of the "uber" jar for the java extension. The uber jar of the java extension contains its dependencies (excluding the revapi API itself which is considered provided).

Embedding

Revapi revapi = Revapi.builder().withAllExtensionsFromThreadContextClassLoader().build();

AnalysisContext analysisContext = AnalysisContext.builder()
    .withOldAPI(API.of(...))
    .withNewAPI(API.of(...))
    .withConfigurationFromJSON("json").build();

revapi.analyze(analysisContext);

For more details, see dedicated section.