japicmp

https://siom79.github.io/japicmp
Admin
japicmp is a tool to compare two versions of a JAR archive and analyze differences between Java...
Tokens:12,262
Snippets:156
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### XML Report Generation Example

Source: https://siom79.github.io/japicmp/Examples.html

This XML output represents a JApiCmp report detailing changes between two JAR files, including class-level and constructor modifications.

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<japicmp xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" accessModifier="PRIVATE" creationTimestamp="2016-02-19T14:36:10.066+0100" ignoreMissingClasses="false" newJar="C:\\MCP-IDE\\repository\\com\\google\\guava\\guava\\19.0\\guava-19.0.jar" oldJar="C:\\MCP-IDE\\repository\\com\\google\\guava\\guava\\18.0\\guava-18.0.jar" onlyBinaryIncompatibleModifications="false" onlyModifications="true" packagesExclude="n.a." packagesInclude="all" semanticVersioning="1.0.0" title="JApiCmp-Report" xsi:noNamespaceSchemaLocation="japicmp.xsd">
    <classes>
        <class binaryCompatible="false" changeStatus="MODIFIED" fullyQualifiedName="com.google.common.base.CharMatcher" javaObjectSerializationCompatible="NOT_SERIALIZABLE" javaObjectSerializationCompatibleAsString="not serializable" sourceCompatible="false">
            <annotations/>
            <attributes>
                <attribute changeStatus="UNCHANGED" newValue="NON_SYNTHETIC" oldValue="NON_SYNTHETIC"/>
            </attributes>
            <classType changeStatus="UNCHANGED" newType="CLASS" oldType="CLASS"/>
            <compatibilityChanges/>
            <constructors>
                <constructor binaryCompatible="false" changeStatus="REMOVED" name="CharMatcher" newLineNumber="n.a." oldLineNumber="600" sourceCompatible="false">
                    <annotations/>
                    <attributes>
                        <attribute changeStatus="REMOVED" newValue="n.a." oldValue="NON_SYNTHETIC"/>
                    </attributes>
                    <compatibilityChanges>
                        <compatibilityChange>CONSTRUCTOR_REMOVED</compatibilityChange>
                    </compatibilityChanges>
                    <modifiers>
                        <modifier changeStatus="REMOVED" newValue="n.a." oldValue="NON_FINAL"/>
                        <modifier changeStatus="REMOVED" newValue="n.a." oldValue="NON_STATIC"/>
                        <modifier changeStatus="REMOVED" newValue="n.a." oldValue="PACKAGE_PROTECTED"/>
                        <modifier changeStatus="REMOVED" newValue="n.a." oldValue="NON_ABSTRACT"/>
                        <modifier changeStatus="REMOVED" newValue="n.a." oldValue="NON_BRIDGE"/>
                        <modifier changeStatus="REMOVED" newValue="n.a." oldValue="NON_SYNTHETIC"/>
                    </modifiers>
                    <parameters>
                        <parameter type="java.lang.String"/>
                    </parameters>
                </constructor>
            </constructors>
			...

```

--------------------------------

### Configure JAPICMP Maven Plugin with Old Version Pattern

Source: https://siom79.github.io/japicmp/MavenPlugin.html

Use this configuration to specify a pattern for matching the old version. This is useful for precisely defining which version to use as the 'old' baseline, for example, only GA releases.

```xml
<plugin>
	<groupId>com.github.siom79.japicmp</groupId>
	<artifactId>japicmp-maven-plugin</artifactId>
	<version>0.25.7</version>
	<configuration>
		<parameter>
        	<oldVersionPattern>\d+\.\d+\.\d+\.GA</oldVersionPattern>
        </parameter>
	</configuration>
	<executions>
		<execution>
			<phase>verify</phase>
			<goals>
				<goal>cmp</goal>
			</goals>
		</execution>
	</executions>
</plugin>
```

--------------------------------

### Compare Multiple JARs

Source: https://siom79.github.io/japicmp/CliTool.html

Provide multiple JAR files for both old and new versions to perform a comparative analysis across several libraries simultaneously.

```bash
java -jar japicmp-0.25.7-jar-with-dependencies.jar -o lib1-old.jar;lib2-old.jar -n lib1-new.jar;lib2-new.jar
```

--------------------------------

### Standard Classpath Usage

Source: https://siom79.github.io/japicmp/CliTool.html

If the classpath for both versions has not changed, you can include the JApiCmp JAR and other necessary libraries using the standard -cp argument.

```bash
java -cp japicmp-0.25.7-jar-with-dependencies.jar;otherLibrary.jar japicmp.JApiCmp -n new-version.jar -o old-version.jar
```

--------------------------------

### Command-line API Differences Report

Source: https://siom79.github.io/japicmp/Examples.html

This output shows the differences between two versions of the Guava library, indicating binary and source incompatible changes with specific markers.

```text
**** MODIFIED INTERFACE: PUBLIC ABSTRACT com.google.common.collect.RangeMap  (not serializable)
	+++* NEW METHOD: PUBLIC(+) ABSTRACT(+) java.util.Map asDescendingMapOfRanges()
**** MODIFIED INTERFACE: PUBLIC ABSTRACT com.google.common.collect.RangeSet  (not serializable)
	+++* NEW METHOD: PUBLIC(+) ABSTRACT(+) java.util.Set asDescendingSetOfRanges()
***! MODIFIED CLASS: com.google.common.collect.RegularImmutableBiMap  (type of field has changed)
	***  MODIFIED FIELD: PRIVATE FINAL java.util.Map$Entry[] (<- com.google.common.collect.ImmutableMapEntry[]) entries
	+++  NEW FIELD: STATIC(+) FINAL(+) com.google.common.collect.RegularImmutableBiMap EMPTY
	---! REMOVED CONSTRUCTOR: RegularImmutableBiMap(java.util.Map$Entry[])
	---! REMOVED CONSTRUCTOR: RegularImmutableBiMap(int, com.google.common.collect.ImmutableMapEntry$TerminalEntry[])
	---! REMOVED CONSTRUCTOR: RegularImmutableBiMap(com.google.common.collect.ImmutableMapEntry$TerminalEntry[])
	+++  NEW CONSTRUCTOR: PRIVATE(+) RegularImmutableBiMap(com.google.common.collect.ImmutableMapEntry[], com.google.common.collect.ImmutableMapEntry[], java.util.Map$Entry[], int, int)
	+++  NEW METHOD: PRIVATE(+) STATIC(+) void checkNoConflictInValueBucket(java.lang.Object, java.util.Map$Entry, com.google.common.collect.ImmutableMapEntry)
	---  REMOVED METHOD: PRIVATE(-) STATIC(-) com.google.common.collect.ImmutableMapEntry[] createEntryArray(int)
	+++  NEW METHOD: STATIC(+) com.google.common.collect.RegularImmutableBiMap fromEntries(java.util.Map$Entry[])
	+++  NEW METHOD: STATIC(+) com.google.common.collect.RegularImmutableBiMap fromEntryArray(int, java.util.Map$Entry[])
	+++  NEW METHOD: PUBLIC(+) int hashCode()
	+++  NEW METHOD: boolean isHashCodeFast()
...
```

--------------------------------

### Configure japicmp for Summary Reports

Source: https://siom79.github.io/japicmp/MavenPlugin.html

Define multiple old and new versions using <dependency/> tags within <oldVersions/> and <newVersions/> to generate a comprehensive summary report.

```xml
<configuration>
	<oldVersions>
		<dependency>
			<groupId>com.github.siom79.japicmp</groupId>
			<artifactId>japicmp-test-v1</artifactId>
			<version>${project.version}</version>
		</dependency>
		<dependency>
			<groupId>com.github.siom79.japicmp</groupId>
			<artifactId>japicmp-test2-v1</artifactId>
			<version>${project.version}</version>
		</dependency>
	</oldVersions>
	<newVersions>
		<dependency>
			<groupId>com.github.siom79.japicmp</groupId>
			<artifactId>japicmp-test-v2</artifactId>
			<version>${project.version}</version>
		</dependency>
		<dependency>
			<groupId>com.github.siom79.japicmp</groupId>
			<artifactId>japicmp-test2-v2</artifactId>
			<version>${project.version}</version>
		</dependency>
	</newVersions>
	...
```

--------------------------------

### Compare JARs using japicmp Command-Line

Source: https://siom79.github.io/japicmp/index.html

Use this command to compare two JAR archives from the command line. Specify the new and old versions of the JARs.

```bash
java -jar japicmp-0.25.7-jar-with-dependencies.jar -n new-version.jar -o old-version.jar
```

--------------------------------

### Compare JARs using japicmp Library

Source: https://siom79.github.io/japicmp/index.html

Integrate japicmp into your Java project as a library to programmatically compare JAR archives. This requires setting up comparator options and providing old and new archives.

```java
JarArchiveComparatorOptions comparatorOptions = new JarArchiveComparatorOptions();
JarArchiveComparator jarArchiveComparator = new JarArchiveComparator(comparatorOptions);
List<JApiClass> jApiClasses = jarArchiveComparator.compare(oldArchives, newArchives);
```

--------------------------------

### Specify Classpath for External Libraries

Source: https://siom79.github.io/japicmp/CliTool.html

When comparing libraries that depend on external interfaces or classes, specify the classpath for both new and old versions using --new-classpath and --old-classpath.

```bash
java -jar japicmp-0.25.7-jar-with-dependencies.jar -n new-version.jar -o old-version.jar --new-classpath other-library-v2.jar
	--old-classpath other-library-v1.jar
```

--------------------------------

### Configure Japicmp Maven Plugin with Advanced Parameters

Source: https://siom79.github.io/japicmp/MavenPlugin.html

Use this configuration to specify old and new versions for comparison and to set various parameters that control the build and reporting behavior of the Japicmp Maven plugin. This includes options for including/excluding specific packages or classes, breaking the build on modifications, and customizing reports.

```xml
<build>
	<plugins>
		<plugin>
			<groupId>com.github.siom79.japicmp</groupId>
			<artifactId>japicmp-maven-plugin</artifactId>
			<version>0.25.7</version>
			<configuration>
				<oldVersion>
					<dependency>
						<groupId>japicmp</groupId>
						<artifactId>japicmp-test-v1</artifactId>
						<version>0.25.7</version>
						<type>jar</type>
					</dependency>
				</oldVersion>
				<newVersion>
					<file>
						<path>${project.build.directory}/${project.artifactId}-${project.version}.${project.packaging}</path>
					</file>
				</newVersion>
				<parameter>
					<onlyModified>true</onlyModified>
					<includes>
						<include>package.to.include</include>
						<include>package.ClassToInclude</include>
						<include>package.Class#methodToInclude(long,int)</include>
						<include>package.Class#fieldToInclude</include>
						<include>@my.AnnotationToInclude</include>
					</includes>
					<excludes>
						<exclude>package.to.exclude</exclude>
						<exclude>package.ClassToExclude</exclude>
						<exclude>package.Class#methodToExclude(long,int)</exclude>
						<exclude>package.Class#fieldToExclude</exclude>
						<exclude>@my.AnnotationToExclude</exclude>
					</excludes>
					<includeExclusively>false</includeExclusively>
					<excludeExclusively>false</excludeExclusively>
					<accessModifier>public</accessModifier>
					<breakBuildOnModifications>false</breakBuildOnModifications>
					<breakBuildOnBinaryIncompatibleModifications>false</breakBuildOnBinaryIncompatibleModifications>
					<breakBuildOnSourceIncompatibleModifications>false</breakBuildOnSourceIncompatibleModifications>
					<breakBuildBasedOnSemanticVersioning>false</breakBuildBasedOnSemanticVersioning>
					<breakBuildBasedOnSemanticVersioningForMajorVersionZero>false</breakBuildBasedOnSemanticVersioningForMajorVersionZero>
					<breakBuildIfCausedByExclusion>true</breakBuildIfCausedByExclusion>
					<overrideCompatibilityChangeParameters>
						<overrideCompatibilityChangeParameter>
							<compatibilityChange>CLASS_REMOVED</compatibilityChange>
							<binaryCompatible>true</binaryCompatible>
							<sourceCompatible>true</sourceCompatible>
							<semanticVersionLevel>PATCH</semanticVersionLevel>
						</overrideCompatibilityChangeParameter>
					</overrideCompatibilityChangeParameters>
					<onlyBinaryIncompatible>false</onlyBinaryIncompatible>
					<includeSynthetic>false</includeSynthetic>
					<ignoreMissingClasses>false</ignoreMissingClasses>
					<ignoreMissingClassesByRegularExpressions>
						<ignoreMissingClassesByRegularExpression>org.apache.commons.math3.*</ignoreMissingClassesByRegularExpression>
					</ignoreMissingClassesByRegularExpressions>
					<skipPomModules>true</skipPomModules>
					<htmlStylesheet>path/to/stylesheet.css</htmlStylesheet>
					<htmlTitle>Title of report</htmlTitle>
					<markdownTitle>Title of report</markdownTitle>
					<noAnnotations>false</noAnnotations>
					<ignoreNonResolvableArtifacts>false</ignoreNonResolvableArtifacts>
					<ignoreMissingOptionalDependency>false</ignoreMissingOptionalDependency>
					<packagingSupporteds>
						<packagingSupported>jar</packagingSupported>
					</packagingSupporteds>
					<postAnalysisScript>${project.basedir}/src/main/groovy/postAnalysisScript.groovy</postAnalysisScript>
					<reportOnlyFilename>false</reportOnlyFilename>
					<skipXmlReport>false</skipXmlReport>
					<skipHtmlReport>false</skipHtmlReport>
					<skipMarkdownReport>false</skipMarkdownReport>
					<skipDiffReport>false</skipDiffReport>
					<includeModules>
						<includeModule>.*incl.*</includeModule>
					</includeModules>
					<excludeModules>
						<excludeModule>.*incl.*</excludeModule>
					</excludeModules>
					<reportLinkName>artifact1_vs_artifact2</reportLinkName>
				</parameter>
				<dependencies>
					<dependency>
						<groupId>org.apache.commons</groupId>
						<artifactId>commons-math3</artifactId>
						<version>3.4</version>
					</dependency>
				</dependencies>
				<skip>false</skip>
			</configuration>
			<executions>
				<execution>
					<phase>verify</phase>
					<goals>
						<goal>cmp</goal>
					</goals>
				</execution>
			</executions>
		</plugin>
	</plugins>
</build>
```

--------------------------------

### Load Groovy Script from Classpath Dependency

Source: https://siom79.github.io/japicmp/MavenPlugin.html

Configure the japicmp-maven-plugin to load a post-analysis Groovy script from an external artifact by specifying the script name and adding the artifact as a dependency.

```xml
<plugin>
	<groupId>com.github.siom79.japicmp</groupId>
	<artifactId>japicmp-maven-plugin</artifactId>
	<version>${project.version}</version>
	<configuration>
		[...]
		<parameter>
			<postAnalysisScript>post-analysis-script.groovy</postAnalysisScript>
		</parameter>
	</configuration>
	<dependencies>
		<dependency>
			<groupId>com.github.siom79.japicmp</groupId>
			<artifactId>post-analysis-script-artifact</artifactId>
			<version>${project.version}</version>
		</dependency>
	</dependencies>
</plugin>
```

--------------------------------

### Basic Ant Task Usage

Source: https://siom79.github.io/japicmp/AntTask.html

Defines the japicmp Ant task and invokes it to compare two JAR versions. Configure `oldjar`, `newjar`, and classpath references. Set `onlybinaryincompatible` to true to filter for binary incompatible changes only.

```xml
<path id="task.classpath">
	<fileset file="${project.build.directory}/japicmp-jar-with-dependencies.jar"/>
	<fileset file="${project.build.directory}/japicmp-ant-task.jar"/>
</path>
<path id="old.classpath">
	<fileset file="${project.build.directory}/guava-18.0.jar"/>
</path>
<path id="new.classpath">
	<fileset file="${project.build.directory}/guava-19.0.jar"/>
</path>
<taskdef resource="japicmp/ant/antlib.xml" classpathref="task.classpath"/>
<japicmp oldjar="${project.build.directory}/guava-18.0.jar"
	 newjar="${project.build.directory}/guava-19.0.jar"
	 oldclasspathref="old.classpath"
	 newclasspathref="new.classpath"
	 onlybinaryincompatible="false"
	 onlymodifications="true"
	 />
```

--------------------------------

### Configure JAPICMP Maven Plugin with Old and New Versions

Source: https://siom79.github.io/japicmp/MavenPlugin.html

Include this configuration in your pom.xml to specify both the old and new versions for API comparison. The plugin will then compare the specified old version dependency against the new version artifact.

```xml
<plugin>
	<groupId>com.github.siom79.japicmp</groupId>
	<artifactId>japicmp-maven-plugin</artifactId>
	<version>0.25.7</version>
	<configuration>
		<oldVersion>
			<dependency>
				<groupId>${project.groupId}</groupId>
				<artifactId>${project.artifactId}</artifactId>
				<version>${oldversion}</version>
				<type>jar</type>
			</dependency>
		</oldVersion>
		<newVersion>
			<file>
				<path>${project.build.directory}/${project.artifactId}-${project.version}.${project.packaging}</path>
			</file>
		</newVersion>
		<parameter>
			<!-- see documentation -->
		</parameter>
	</configuration>
	<executions>
		<execution>
			<phase>verify</phase>
			<goals>
				<goal>cmp</goal>
			</goals>
		</execution>
	</executions>
</plugin>
```

--------------------------------

### Configure External Dependencies for Japicmp

Source: https://siom79.github.io/japicmp/MavenPlugin.html

Add external libraries as dependencies for the Japicmp plugin. These are appended to the classpath before those from the enclosing pom.xml, allowing for overrides.

```xml
<dependencies>
	<dependency>
		<groupId>org.apache.commons</groupId>
		<artifactId>commons-math3</artifactId>
		<version>3.4</version>
	</dependency>
</dependencies>
```

--------------------------------

### Integrate japicmp into Maven Site Report

Source: https://siom79.github.io/japicmp/MavenPlugin.html

Configure the japicmp-maven-plugin within the <reporting/> tag to include its output in the Maven site report.

```xml
<reporting>
	<plugins>
		<plugin>
			<groupId>com.github.siom79.japicmp</groupId>
			<artifactId>japicmp-maven-plugin</artifactId>
			<version>0.25.7</version>
			<reportSets>
				<reportSet>
					<reports>
						<report>cmp-report</report>
					</reports>
				</reportSet>
			</reportSets>
			<configuration>
				<!-- see above -->
			</configuration>
		</plugin>
	</plugins>
</reporting>
```

--------------------------------

### Filter Classes and Methods with Groovy Script

Source: https://siom79.github.io/japicmp/MavenPlugin.html

Use a Groovy script with the <postAnalysisScript/> parameter to filter out specific classes and methods after analysis but before output generation. The script must return a list of JApiClass objects.

```groovy
def it = jApiClasses.iterator()
while (it.hasNext()) {
	def jApiClass = it.next()
	def fqn = jApiClass.getFullyQualifiedName()
	if (fqn.startsWith("japicmp.test.annotation")) {
		it.remove()
	}
	def methodIt = jApiClass.getMethods().iterator()
	while (methodIt.hasNext()) {
		def method = methodIt.next()
		if (method.getName().startsWith("get") || method.getName().startsWith("set")) {
			methodIt.remove()
		}
	}
}
return jApiClasses
```

--------------------------------

### Specify Custom Classpath Dependencies for Japicmp Maven Plugin

Source: https://siom79.github.io/japicmp/MavenPlugin.html

Use these elements to define separate dependencies for the old and new versions of your project when their classpaths differ. This ensures accurate comparison by the Japicmp plugin.

```xml
<oldClassPathDependencies>
	<dependency>
		<groupId>org.apache.commons</groupId>
		<artifactId>commons-math3</artifactId>
		<version>3.4</version>
	</dependency>
</oldClassPathDependencies>
<newClassPathDependencies>
	<dependency>
		<groupId>org.apache.commons</groupId>
		<artifactId>commons-math3</artifactId>
		<version>3.5</version>
	</dependency>
</newClassPathDependencies>
```

--------------------------------

### Integrate japicmp with Ant Task

Source: https://siom79.github.io/japicmp/index.html

Use the japicmp Ant task to incorporate API comparison into your Ant build scripts. This requires defining the task and specifying old and new JAR paths, along with classpath references.

```xml
<taskdef resource="japicmp/ant/antlib.xml" classpathref="task.classpath"/>
<japicmp oldjar="${project.build.directory}/guava-18.0.jar"
	 newjar="${project.build.directory}/guava-19.0.jar"
	 oldclasspathref="old.classpath"
	 newclasspathref="new.classpath"
	 onlybinaryincompatiblemodifications="false"
	 onlyModifications="true"
	 />
```

--------------------------------

### Integrate japicmp with Maven Plugin

Source: https://siom79.github.io/japicmp/index.html

Configure the japicmp Maven plugin to automatically compare JAR versions during your build process. This allows for automated API change detection.

```xml
<plugin>
	<groupId>com.github.siom79.japicmp</groupId>
	<artifactId>japicmp-maven-plugin</artifactId>
	<version>0.25.7</version>
	<configuration>
		<oldVersion>
			<dependency>
				<groupId>japicmp</groupId>
				<artifactId>japicmp-test-v1</artifactId>
				<version>${oldversion}</version>
				<type>jar</type>
			</dependency>
		</oldVersion>
		<newVersion>
			<file>
				<path>${project.build.directory}/${project.artifactId}-${project.version}.${project.packaging}</path>
			</file>
		</newVersion>
		<parameter>
			<!-- see documentation -->
		</parameter>
	</configuration>
	<executions>
		<execution>
			<phase>verify</phase>
			<goals>
				<goal>cmp</goal>
			</goals>
		</execution>
	</executions>
</plugin>
```

--------------------------------

### Add japicmp as a Maven Dependency

Source: https://siom79.github.io/japicmp/index.html

Include japicmp as a dependency in your Maven project to use its features. This is the standard way to add libraries in Maven projects.

```xml
<dependency>
	<groupId>com.github.siom79.japicmp</groupId>
	<artifactId>japicmp</artifactId>
	<version>0.25.7</version>
</dependency>
```

--------------------------------

### Configure JAPICMP Maven Plugin without Explicit Versions

Source: https://siom79.github.io/japicmp/MavenPlugin.html

This configuration omits explicit old and new version definitions. The plugin attempts to automatically detect the latest released version and the project's output artifact for comparison.

```xml
<plugin>
	<groupId>com.github.siom79.japicmp</groupId>
	<artifactId>japicmp-maven-plugin</artifactId>
	<version>0.25.7</version>
	<configuration>
		<parameter>
			<!-- see documentation -->
		</parameter>
	</configuration>
	<executions>
		<execution>
			<phase>verify</phase>
			<goals>
				<goal>cmp</goal>
			</goals>
		</execution>
	</executions>
</plugin>
```

--------------------------------

### JAXB XML Document Change Tracking Output

Source: https://siom79.github.io/japicmp/Examples.html

This output highlights modifications in a Java class annotated with JAXB, showing changes in method annotations and XML element names. It is useful for understanding how JAXB bindings evolve.

```text
***  MODIFIED CLASS: PUBLIC japicmp.test.jaxb.SimpleDocument
	***  MODIFIED METHOD: PUBLIC java.lang.String getTitle()
		---  REMOVED ANNOTATION: javax.xml.bind.annotation.XmlAttribute
		+++  NEW ANNOTATION: javax.xml.bind.annotation.XmlElement
	***  MODIFIED METHOD: PUBLIC java.lang.String getAuthor()
		---  REMOVED ANNOTATION: javax.xml.bind.annotation.XmlAttribute
		+++  NEW ANNOTATION: javax.xml.bind.annotation.XmlElement
	***  MODIFIED ANNOTATION: javax.xml.bind.annotation.XmlRootElement
		***  MODIFIED ELEMENT: name=document (<- simpleDocument)
```

--------------------------------

### Break Build on Class Modification with Groovy

Source: https://siom79.github.io/japicmp/MavenPlugin.html

Implement a Groovy script to check the change status of classes within a specific package and throw an exception if any class is not UNCHANGED, effectively breaking the build. Ensure the script returns the list of JApiClass objects.

```groovy
import static japicmp.model.JApiChangeStatus.*

def it = jApiClasses.iterator()
while (it.hasNext()) {
	def jApiClass = it.next()
	def fqn = jApiClass.getFullyQualifiedName()
	if (fqn.startsWith("japicmp.test.annotation")) {
		if (jApiClass.getChangeStatus() != UNCHANGED) {
			throw new Exception("Class in package japicmp.test.annotation has been modified.")
		}
	}
}
return jApiClasses
```
Tokens:
Raw