-
Notifications
You must be signed in to change notification settings - Fork 107
/
Copy pathindex.html
198 lines (190 loc) · 13.1 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 1.11.1 from src/site/markdown/index.md at 2025-01-09
| Rendered using Apache Maven Fluido Skin 1.7
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="Date-Revision-yyyymmdd" content="20250109" />
<meta http-equiv="Content-Language" content="en" />
<title>japicmp-base – japicmp</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.7.min.css" />
<link rel="stylesheet" href="./css/site.css" />
<link rel="stylesheet" href="./css/print.css" media="print" />
<script type="text/javascript" src="./js/apache-maven-fluido-1.7.min.js"></script>
</head>
<body class="topBarDisabled">
<a href="https://github.com/siom79/japicmp">
<img style="position: absolute; top: 0; right: 0; border: 0; z-index: 10000;"
src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png"
alt="Fork me on GitHub">
</a>
<div class="container-fluid">
<div id="banner">
<div class="pull-left"><div id="bannerLeft"><h2>japicmp-base</h2>
</div>
</div>
<div class="pull-right"></div>
<div class="clear"><hr/></div>
</div>
<div id="breadcrumbs">
<ul class="breadcrumb">
<li class=""><a href="https://siom79.github.io/japicmp" class="externalLink" title="japicmp">japicmp</a><span class="divider">/</span></li>
<li class="active ">japicmp</li>
<li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2025-01-09</li>
<li id="projectVersion" class="pull-right">Version: 0.23.1</li>
</ul>
</div>
<div class="row-fluid">
<div id="leftColumn" class="span2">
<div class="well sidebar-nav">
<ul class="nav nav-list">
<li class="nav-header">Overview</li>
<li class="active"><a href="#"><span class="none"></span>Introduction</a></li>
<li><a href="CliTool.html" title="Cli-Tool"><span class="none"></span>Cli-Tool</a></li>
<li><a href="MavenPlugin.html" title="Maven Plugin"><span class="none"></span>Maven Plugin</a></li>
<li><a href="AntTask.html" title="Ant Task"><span class="none"></span>Ant Task</a></li>
<li><a href="Examples.html" title="Examples"><span class="none"></span>Examples</a></li>
<li><a href="ReleaseNotes.html" title="Release Notes"><span class="none"></span>Release Notes</a></li>
</ul>
<hr />
<div id="poweredBy">
<div class="clear"></div>
<div class="clear"></div>
<div class="clear"></div>
<div class="clear"></div>
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /></a>
</div>
</div>
</div>
<div id="bodyColumn" class="span10" >
<h1>japicmp</h1>
<p>japicmp is a tool to compare two versions of a jar archive:</p>
<div class="source"><pre class="prettyprint"><code>java -jar japicmp-0.23.1-jar-with-dependencies.jar -n new-version.jar -o old-version.jar
</code></pre></div>
<p>It can also be used as a library:</p>
<div class="source"><pre class="prettyprint"><code>JarArchiveComparatorOptions comparatorOptions = new JarArchiveComparatorOptions();
JarArchiveComparator jarArchiveComparator = new JarArchiveComparator(comparatorOptions);
List<JApiClass> jApiClasses = jarArchiveComparator.compare(oldArchives, newArchives);
</code></pre></div>
<p>japicmp is available in the Maven Central Repository:</p>
<div class="source"><pre class="prettyprint"><code><dependency>
<groupId>com.github.siom79.japicmp</groupId>
<artifactId>japicmp</artifactId>
<version>0.23.1</version>
</dependency>
</code></pre></div>
<p>A maven plugin allows you to integrate the checks into your build:</p>
<div class="source"><pre class="prettyprint"><code><plugin>
<groupId>com.github.siom79.japicmp</groupId>
<artifactId>japicmp-maven-plugin</artifactId>
<version>0.23.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>
</code></pre></div>
<p>A Sonar Qube plugin integrates the results from the japicmp analysis into your code quality report: <a class="externalLink" href="https://github.com/siom79/sonar-japicmp-plugin">sonar-japicmp-plugin</a>.</p>
<p>By using the available Ant task, you can also integrate japicmp into your Ant build files:</p>
<div class="source"><pre class="prettyprint"><code><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"
/>
</code></pre></div>
<p><a class="externalLink" href="https://github.com/melix">melix</a> has developed a <a class="externalLink" href="https://github.com/melix/japicmp-gradle-plugin">gradle plugin</a> for japicmp.</p><section>
<h2><a name="Online-Version"></a>Online-Version</h2>
<p>There is an online version of japicmp that lets you compare two artifacts from the maven central repository
without installing the tool first. Just click <a class="externalLink" href="https://www.japicmp.de">this</a> link and give it a try.</p></section><section>
<h2><a name="Motivation"></a>Motivation</h2>
<p>Every time you release a new version of a library or a product, you have to tell your clients or customers what
has changed in comparison to the last release. Without the appropriate tooling, this task is tedious and error-prone.
This tool/library helps you to determine the differences between the java class files that are contained in two given
jar archives.</p>
<p>This library does not use the Java Reflection API to compute the differences, as the usage of the Reflection API makes
it necessary to include all classes the jar archive under investigation depends on are available on the classpath.
To prevent the inclusion of all dependencies, which can be a lot of work for bigger applications, this library makes
use of the <a class="externalLink" href="https://www.javassist.org/">javassist</a> library to inspect the class files.
This way you only have to provide the two jar archives on the command line (and eventually libraries that contain
classes/interfaces you have extended/implemented).</p>
<p>This approach also detects changes in instrumented and generated classes. You can even evaluate changes in class file attributes (like synthetic) or annotations.
The comparison of annotations makes this approach suitable for annotation-based APIs like JAXB, JPA, JAX-RS, etc.</p>
<p>The goal of this project is to provide a fast and easy to use API comparison for Java. Therefore it does not aim
to integrate change tracking of other types of artifacts (configuration files, etc.) as a generic implementation means
to make compromises in terms of performance and ease of usage. japicmp for example compares two archives with about 1700 classes each
in less than one second and therewith can be easily integrated in each build.</p></section><section>
<h2><a name="Features"></a>Features</h2>
<ul>
<li>Comparison of two jar archives without the need to add all of their dependencies to the classpath.</li>
<li>Differences are printed on the command line in a simple diff format.</li>
<li>Differences can optionally be printed as <a class="externalLink" href="https://www.markdownguide.org/">Markdown</a>, XML or HTML file.</li>
<li>Per default private and package protected classes and class members are not compared. If necessary, the access modifier of the classes and class members to be
compared can be set to public, protected, package or private.</li>
<li>Per default all classes are tracked. If necessary, certain packages, classes, methods or fields can be excluded or explicitly included. Inclusion and exclusion is also possible based on annotations.</li>
<li>All changes between all classes/methods/fields are compared. japicmp differentiates between source and binary compatible changes (as described in the <a class="externalLink" href="http://docs.oracle.com/javase/specs/jls/se7/html/jls-13.html">Java Language Specification</a> and this <a class="externalLink" href="https://blogs.oracle.com/darcy/entry/kinds_of_compatibility">Oracle blog</a>).</li>
<li>All changes between annotations are compared, hence japicmp can be used to track annotation-based APIs like JAXB, JPA, JAX-RS, etc.</li>
<li>A maven plugin is available that allows you to compare the current artifact version with some older version from the repository.</li>
<li>The option <code>--semantic-versioning</code> tells you which part of the version you have to increment in order to follow <a class="externalLink" href="http://semver.org/">semantic versioning</a>.</li>
<li>The option <code>--markdown</code> generates output in <a class="externalLink" href="https://www.markdownguide.org/">Markdown</a> format.</li>
<li>If a class is serializable, changes are evaluated regarding the <a class="externalLink" href="http://docs.oracle.com/javase/7/docs/platform/serialization/spec/serialTOC.html">Java Object Serialization Specification</a>.</li>
<li>Per default synthetic classes and class members (e.g. <a class="externalLink" href="https://docs.oracle.com/javase/tutorial/java/generics/bridgeMethods.html">bridge methods</a>) are hidden. They can be listed by using the option <code>--include-synthetic</code>.</li>
<li>The maven plugin allows project-specific filtering and reports using a custom <a href="groovy-lang.org">Groovy</a> script.</li>
</ul></section><section>
<h2><a name="Downloads"></a>Downloads</h2>
<p>You can download the latest version from the <a class="externalLink" href="https://github.com/siom79/japicmp/releases">release page</a> or directly from the <a class="externalLink" href="http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22japicmp%22">maven central repository</a>.</p></section><section>
<h2><a name="Contact"></a>Contact</h2>
<p>The issue tracker at <a class="externalLink" href="https://github.com/siom79/japicmp/issues">github</a> can be used to submit feature requests or bugs. Beyond that contributions in form of pull requests are highly appreciated.</p></section><section>
<h2><a name="Buy_me_a_coffee"></a>Buy me a coffee</h2>
<p>If you like japicmp and would like to do me a favor for all the work I've done over
the years, please consider buying me a coffee <a class="externalLink" href="https://www.buymeacoffee.com/mmois">here</a>.</p>
<p><a class="externalLink" href="https://www.buymeacoffee.com/mmois" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174" /></a></p></section><section>
<h2><a name="Related_work"></a>Related work</h2>
<p>The following projects have related goals:</p>
<ul>
<li><a class="externalLink" href="http://ispras.linuxbase.org/index.php/Java_API_Compliance_Checker">Java API Compliance Checker</a>: A Perl script that uses javap to compare two jar archives. This approach cannot compare annotations and you need to have Perl installed.</li>
<li><a class="externalLink" href="http://clirr.sourceforge.net/">Clirr</a>: A tool written in Java that compares two libraries for binary compatibility. Tracking of API changes is implemented only partially, tracking of annotations is not supported. Development has stopped around 2005.</li>
<li><a class="externalLink" href="http://javadiff.sourceforge.net/">JDiff</a>: A Javadoc doclet that generates an HTML report of all API changes. The source code for both versions has to be available, the differences are not distinguished between binary incompatible or not. Comparison of annotations is not supported.</li>
<li><a class="externalLink" href="http://revapi.org/">revapi</a>: An API analysis and change tracking tool that was started about the same time as japicmp. It ships with a maven plugin and an Ant task, but the maven plugin currently (version 0.4.1) only reports changes on the command line.</li>
</ul></section>
</div>
</div>
</div>
<hr/>
<footer>
<div class="container-fluid">
<div class="row-fluid">
<p>Copyright ©2025.
All rights reserved.</p>
</div>
</div>
</footer>
</body>
</html>