japicmp

To use japicmp in automated pipelines (like CI/CD), you can force the tool to exit with an error code if specific types of incompatibilities are detected. This allows you to break a build if breaking changes are introduced.

• --error-on-binary-incompatibility: Exit if binary incompatibility is found.
• --error-on-source-incompatibility: Exit if source incompatibility is found.
• --error-on-modifications: Exit if any change (even non-breaking) is detected.
• --error-on-semantic-incompatibility: Exit if changes violate Semantic Versioning rules (requires versions in Major.Minor.Patch format).

Note on Exclusions: If you use --no-error-on-exclusion-incompatibility, the tool will not trigger an error if an incompatibility is caused by a class or member you have explicitly excluded (e.g., an interface was removed from a class, but that interface was excluded from the check).

The Compatibility Report is a tool used to identify breaking changes between two versions of a library (e.g., Guava 18.0 vs 19.0). It categorizes changes based on SemVer (Semantic Versioning) principles, specifically highlighting MAJOR incompatible changes.

When reviewing a report, you can expand the options used to see the specific configuration applied during the check, such as:

• Access modifier filter: Limits the scope of the check (e.g., PROTECTED).
• Report only changes: If enabled, the report focuses on what changed rather than a full summary.
• Evaluate annotations: Determines if annotation changes are considered part of the compatibility check.
• Classpath mode: Defines how the tool handles classpaths (e.g., ONE_COMMON_CLASSPATH).
• Treat changes as errors: Configures whether specific types of changes (binary, source, or semantic incompatibilities) should trigger error states.

japicmp provides several advanced capabilities for Java API comparison:

• Dependency-free comparison: Uses the javassist library to inspect class files, meaning you don't need to add all dependencies of the JARs to the classpath.
• Compatibility detection: Differentiates between source compatible and binary compatible changes.
• Annotation tracking: Compares changes in annotations, making it suitable for annotation-based APIs like JAXB, JPA, and JAX-RS.
• Flexible output: Differences can be printed to the command line or exported as Markdown, XML, or HTML files.
• Granular control:
  • Control access modifier visibility (public, protected, package, private).
  • Include/exclude specific packages, classes, methods, or fields.
  • Include synthetic classes/members using --include-synthetic.
• Semantic Versioning: The --semantic-versioning option suggests the appropriate version increment (Major/Minor/Patch) based on changes.
• Serialization awareness: Evaluates changes regarding the Java Object Serialization Specification if a class is serializable.

The japicmp-maven-plugin allows you to automate API compatibility checks during your Maven build lifecycle (e.g., during the verify phase). You can define the oldVersion as a dependency and the newVersion as a local file.

<plugin>
	<groupId>com.github.siom79.japicmp</groupId>
	<artifactId>japicmp-maven-plugin</artifactId>
	<version>0.26.1</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>

The <postAnalysisScript> parameter allows you to execute a Groovy script after the API analysis is complete but before the output is written. This is useful for:

1. Custom Filtering: Removing specific classes or methods from the report (e.g., filtering out annotations or getter/setter methods).
2. Custom Build Rules: Breaking the build by throwing an exception if certain API change conditions are met (e.g., ensuring specific packages remain UNCHANGED).

Important: The script must return a list of JApiClass objects. If it does not, the Maven plugin will report an error.

// Example: Filtering out classes in a specific package and specific method patterns
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