JarJarDiff Task

JarJarDiff

Description

Computes API differences between two versions of a codebase.

Takes two JAR files and computes the API changes between them. The first JAR file is considered the "old" code and the second JAR file is considered the "new" code. The result is an XML document listing the changes. You can use DiffToHTML and PublishedDiffToHTML to render the report in HTML. The second one is more restrictive as to what gets included in the report, so you can limit the report to "public" changes.

It writes all differences into an XML document that follows the differences DTD.

Parameters

Attribute	Description	Required
destfile	where to write the output. If the file , it is created. If it already exists, its content is overwritten.	Yes
encoding	encoding used for the XML output document.	No
dtdprefix	prefix of the DTD URL for the XML output document.	No
indenttext	used for each indentation level in the XML output.	No
name	project name for the report.	No
oldlabel	version name for the report. If omitted, the tools will use a string representation of the `old` nested element instead.	No
newlabel	version name for the report. If omitted, the tools will use a string representation of the `new` nested element instead.	No
filter	location of the file with the list of programming elements that the tool should limit itself to. If omitted, the tool reports on all programming elements.	No
level	one of: api for declaration-only differences, incompatible for only differences that affect backwards compatibility, or the name of a `DifferenceStrategy` implementation to instantiate. If omitted, defaults to api.	No

Nested elements

old

Use nested old elements to specify file names of JAR files, Zip files, and .class files that make up the old codebase. You can also give directory names, the tool will search it for .class files and read them. It is a path-like structures.

new

Use nested new elements to specify file names of JAR files, Zip files, and .class files that make up the new codebase. You can also give directory names, the tool will search it for .class files and read them. It is a path-like structures.

Examples

To compare versions 20020127 and 20020711 of Dependency Finder and save the resulting report in 20020127-20020711.xml:

  <jarjardiff destfile="20020127-20020711.xml"
              name="Dependency Finder"
              oldlabel="20020127"
              newlabel="20020711">
    <old>
      <pathelement location="20020127\lib\DependencyFinder.jar"/>
    </old>
    <new>
      <pathelement location="20020711\lib\DependencyFinder.jar"/>
    </new>
  </jarjardiff>

To compare version 20030101 of Dependency Finder with the latest compilation and save the resulting report in 20030101-now.xml:

  <jarjardiff destfile="20030101-now.xml"
              name="Dependency Finder"
              oldlabel="20030101"
              newlabel="latest">
    <old>
      <pathelement location="20030101\lib\DependencyFinder.jar"/>
    </old>
    <new>
      <pathelement location="DependencyFinder\classes"/>
    </new>
  </jarjardiff>

To compare versions 2.2.1 and 2.3.0 of Xerces and save the resulting report in xerces.xml:

  <jarjardiff destfile="xerces.xml"
              name="Xerces"
              oldlabel="2.2.1"
              newlabel="2.3.0">
    <old>
      <pathelement location="xerces-2_2_1\xmlParserAPIs.jar"/>
      <pathelement location="xerces-2_2_1\xercesImpl.jar"/>
    </old>
    <new>
      <pathelement location="xerces-2_3_0\xml-apis.jar"/>
      <pathelement location="xerces-2_3_0\xercesImpl.jar"/>
    </new>
  </jarjardiff>

To compare versions 2.2.1 and 2.3.0 of Xerces and save the resulting report in xerces.xml, and then convert the report to HTML:

  <jarjardiff destfile="xerces.xml"
              name="Xerces"
              oldlabel="2.2.1"
              newlabel="2.3.0">
    <old>
      <pathelement location="xerces-2_2_1\xmlParserAPIs.jar"/>
      <pathelement location="xerces-2_2_1\xercesImpl.jar"/>
    </old>
    <new>
      <pathelement location="xerces-2_3_0\xml-apis.jar"/>
      <pathelement location="xerces-2_3_0\xercesImpl.jar"/>
    </new>
  </jarjardiff>
  <xslt style="${dependencyfinder.home}/etc/DiffToHTML.xsl"
        in="xerces.xml"
        out="xerces.html"/>

To compare versions 2.2.1 and 2.3.0 of Xerces and save the resulting report in xerces.xml, keeping only modifications to the public API, and then convert the report to HTML:

  <jarjardiff destfile="xerces.xml"
              name="Xerces"
              oldlabel="2.2.1"
              newlabel="2.3.0"
              level="incompatible">
    <old>
      <pathelement location="xerces-2_2_1\xmlParserAPIs.jar"/>
      <pathelement location="xerces-2_2_1\xercesImpl.jar"/>
    </old>
    <new>
      <pathelement location="xerces-2_3_0\xml-apis.jar"/>
      <pathelement location="xerces-2_3_0\xercesImpl.jar"/>
    </new>
  </jarjardiff>
  <xslt style="${dependencyfinder.home}/etc/DiffToHTML.xsl"
        in="xerces.xml"
        out="xerces.html"/>