JDiff User Documentation

JDiff is a Javadoc doclet which generates an HTML report of all the packages, classes, constructors, methods, and fields which have been removed, added or changed in any way, including their documentation, when two APIs are compared. This is very useful for describing exactly what has changed between two releases of a product. Only the API (Application Programming Interface) of each version is compared. It does not compare what the source code does when executed.

Overview
Installation
Synopsis
Output
Adding Comments to a Report
Troubleshooting
Errors and Warning Messages
Difference Statistics
Limitations
Further Reading

OVERVIEW

The basic sequence of operations is to run JDiff on one set of source files to create an XML file which represents the API for that version of a product. Then JDiff is run again on another set of source files to create an XML file which represents the API for the next version of a product. Finally, JDiff compares the two APIs as represented in the XML files and generates an HTML report which describes the differences between the two APIs, together with comments describing the reasons for the differences. This whole process can be executed as separate Javadoc steps (either from Ant or the command line) or by simply using the Ant JDiff task provided.

The results are written into a file called changes.html, with more files in a subdirectory called changes. These files can contain links to existing Javadoc documentation. A CSS stylesheet is also generated in the file stylesheet-jdiff.css, and this uses a background image in background.gif. These are the only files which usually need to be shipped with a product to include a report of what has changed since the previous release. If the -stats option was used, then the file black.gif should also be shipped.

There is a working example of how to use JDiff in the examples directory of the source distribution.

INSTALLATION

Unpack the jdiff-1.1.1.zip file. This will produce a directory named "jdiff-1.1.1" containing all that is necessary to use JDiff to produce your own reports. See the file "example.xml" in that directory for an example of how to use the Ant JDiff task. The file "jdiff.html" contains more information about using JDiff.

If you are using the complete source distribution, then you should be able to simply type "ant" at the top-level to produce a working example report.

The Ant JDiff task needs Ant 1.6.1 to work correctly. Using Ant 1.5 will produce the error:
Error: two projects are needed, one <old> and one <new>

No Windows registry entries are changed by JDiff. To remove JDiff, simply delete the directory where it is was unpacked.

SYNOPSIS

The Ant JDiff task has the following parameters:

Attribute Description Required

destdir The location where the JDiff report will be generated. Defaults to a directory "jdiff_report" in the directory from where Ant was executed. No

stats Generate an HTML page of statistical information about the differences between the two APIs. Defaults to "off". No

docchanges Enables comparison of Javadoc documentation. Defaults to "off". No

verbose Increase the logging vebosity of the task. Defaults to "off". No

Parameters specified as nested elements

The old and new elements are used to describe the projects to be compared.

Attribute Description Required

name The name of the project, e.g. "My Project Version 1". The name, with spaces replaced by underscores, is used as the name of the XML file in destdir, which is generated by JDiff to represent the structure of the source files of this project. Yes

javadoc The location of a Javadoc report for this project. If this attribute is not used, then a Javadoc report for the project will be generated in a subdirectory named name in destdir. No

Note: the old and new elements only have DirSet nested elements, not FileSet ones.

The complete list parameters that can be passed to the JDiff doclet, either through the Ant Javadoc task or directly at the command line, is as follows:

javadoc -doclet jdiff.JDiff -docletpath jdiff.jar
 [-apiname <API name>]
 [-apidir <optional directory where the API XML file is to be placed>]
 [-oldapi <name of old API>]
 [-oldapidir <optional directory where the old API XML file is located>]
 [-newapi <name of new API>]
 [-newapidir <optional directory where the new API XML file is located>]
 [-sourcepath <source path>]
 [-javadocnew <javadoc files location for the new API>]
 [-javadocold <javadoc files location for the old API>]
 [-baseURI <base>]
 [-excludeclass <exclusion level>]
 [-excludemember <exclusion level>]
 [-nosuggest <suggestion level>]
 [-firstsentence]
 [-docchanges]
 [-checkcomments]
 [-packagesonly]
 [-showallchanges]
 [-retainnonprinting]
 [-excludetag <exclude tag>]
 [-stats]
 [-windowtitle <text>]
 [-doctitle <HTML text>]
 [-version]
 [-help]

NOTE: Either -apiname, or both -oldapi and -newapi must be used. All other arguments are optional.

The -d directory argument works just as with Javadoc, redirecting the HTML output to the given directory.

The arguments for the JDiff doclet are:

-apiname <API name>: Define the name which will be associated with the specified API. If the name which is given here has space characters, they will be replaced by underscore characters. This name with no spaces is used as the name of the XML file. It is also written into the XML file as an attribute of the top element. E.g. "SuperProduct 1.0" generates an XML file named "SuperProduct_1.0.xml". The XML file is always generated in the current directory, unless overridden by the -apidir argument.
-oldapi <name of old API>: The name of the old or previous version of an API or product, e.g. "SuperProduct 1.0", which is to be one of the APIs compared. This name is the name which was given to -apiname when the XML file was generated.
-newapi <name of old API>: The name of the new or later version of an API or product, e.g. "SuperProduct 2.0", which is to be one of the APIs compared. This name is the name which was given to -apiname when the XML file was generated.
-apidir <API directory>: Defines the directory where the API XML file is to be placed. Used in conjunction with the -apiname argument.
-oldapidir <old API directory>: Defines the directory where the XML file for the old API is located. Used in conjunction with the -oldapi argument. Default is the current directory.
-newapidir <new API directory>: Defines the directory where the XML file for the new API is located. Used in conjunction with the -newapi argument. Default is the current directory.
-sourcepath <source path>: Define the path to the set of Java source files (the API) to be scanned, e.g. examples/SuperProduct1.0. The slashes in this argument should match the local architecture.
-javadocnew <javadoc files location for the new API>: The location of existing Javadoc files for the new API, e.g. "http://java.sun.com/j2se/1.5.0/docs/api/" for the public documentation for J2SE1.5.0. The default value is "../", which implies that the documentation directory generated by Javadoc is at the same level as the "changes.html" file generated by JDiff. Slashes are always forward in the argument, since this is an HTML link. The argument should also always end in a forward slash. If a relative value is given, it should be relative to files in the "changes" directory generated by JDiff.
-javadocold <javadoc files location for the old API>: The location of existing Javadoc files for the old API, e.g. "http://java.sun.com/j2se/1.5.0/docs/API/" for the public documentation for J2SE1.5.0. The default value is null, which results in no links to Javadoc-generated documentation for the previous release. Slashes are always forward in the argument, since this is an HTML link. The argument should also always end in a forward slash. If a relative value is given, it should be relative to files in the "changes" directory generated by JDiff.
-baseURI <base>: Use \"base\" as the base location of the various DTDs used by JDiff. For example, -baseURI "file:///C:/jdiff/lib" would cause the XML parser to use the copies which are shipped in the lib directory, if JDiff is installed in C:\jdiff. Note that there are three forward slashes after "file:".
-excludeclass <exclusion level>: This can be set to "public", "protected", "package", or "private". If it is set to "protected", only classes which are public or protected will be shown. If it is set to "public", then only public classes are shown. The default is "protected". If this is changed, the Javadoc -private argument must also be passed to Javadoc.
-excludemember <exclusion level>: This can be set to "public", "protected", "package", or "private". If it is set to "protected", only members (constructors, methods and fields) which are public or protected will be shown. If it is set to "public", then only public members are shown. The default is "protected". If this is changed, the Javadoc -private argument must also be passed to Javadoc.
-firstsentence: This argument causes JDiff to save only the first sentence of each Javadoc comment as part of the API. This is only necessary when the XML file representing the API is being generated. See -docchanges for how to note documentation changes as differences.
-docchanges: This argument enables comparison of Javadoc documentation. By default, changes in the saved Javadoc documentation are not noted as changes (or as removals and related additions). See -firstsentence option for how to compare just the first sentence in Javadoc documentation.
-nosuggest <suggestion level>: This can be set to "all", "remove", "add", or "change". The effect of setting this to "all" is to stop comments for any changes at all being suggested. Any comments which are to appear in the report must then be written by the user (see below). If it is set to "change", then comments will not be suggested for changes, but will be suggested for removals and additions. The default is that comments are suggested for all possible places.
-checkcomments: If this argument is used, JDiff will warn the user when the report is generated if there are comments which do not end in a period, question mark or exclamation mark.
-packagesonly: If this argument is used, JDiff will not scan classes specified on the command line. This should only need to be used with the "jdiffjar" script, when comparing Jar files. If this options is not used when comparing Jar files, duplicate classes with no packages ("anonymous" classes) may be wrongly reported by JDiff.
-showallchanges: If this argument is used, JDiff will show changes in native and synchronized modifiers. See here for why these are not shown by default.
-retainnonprinting: Retain non-printable characters in comments. By default, JDiff removes non-printable characters from comments which it uses. This should only really be necessary if the first line of a comment has used explicit Unicode character escape sequences which cannot be printed, or more importantly for JDiff, read in from XML. If this option is used, JDiff may fail to read in an XML file, and exit with an error message about "an invalid XML character (Unicode: 0x....)" on a certain line in the file. Turning off this option does make creating large XML files a little faster.
-excludetag <exclude tag>: The argument passed in with this causes JDiff to ignore program elements (packages, classes, constructors, methods, fields) which contain the given exclude tag in their comment blocks, e.g. " @exclude", " @docset Internal". The extra space in front of "@" is to stop Javadoc from expanding the name into a file containing commands on the compile line. White space is trimmed off before the string is used. Another solution to passing "@" as part of an argument is to pass @foo, and then create a file named foo, containing -excludetag @exclude.
-stats: Generate an HTML page of statistical information about the differences between the two APIs.
-windowtitle <text>: Specify the title used in the browser window for the report. By default, this is "API Differences Between <name of old API> and <name of new API>".
-doctitle <HTML text>: Specify the title used on the first page of the report. By default, this is "API Differences Between <name of old API> and <name of new API>".
-version: Display the version of JDiff.
-help: Display the usage summary for JDiff.

OUTPUT

Interfaces appear in italics, just as in Javadoc documentation.

When a package or class appears in bold, it has been added in the new version or API.

When a package or class appears ~~struck through~~, it has been removed in the new version or API.

When a constructor is added, two entries are added to the "All Differences" index: one for the addition of a new constructor, and one for the change of the class. The constructor entry has "constructor" after it.

There are some complex changes which can occur between versions, for example, when two or more methods with the same name change simultaneously, or when a method or field is moved into or from a superclass. In these cases, the change will be seen as a removal and an addition, rather than as a change. Unexpected removals or additions are often part of one of these type of changes.

With large packages, it is often necessary to change the memory parameters for Javadoc, e.g. pass in -J-Xmx128m to Javadoc.

The api.xsd template describes the format of the XML for the APIs, and the comments.xsd template describes the format of the XML for the comments. The API template is independent of any related work at Sun, but the intention is to adopt whatever becomes the de facto standard in the future, whilst retaining backward compatibility. To enable validation, set the boolean validateXML in the file XMLToAPI.java and recompile.

Comments in the comments XML file do get reordered during regeneration. This is harmless.

ADDING COMMENTS TO A REPORT

Comments can be added to a report by using a text editor to add text to the "user_comments_X_to_Y.xml" file, where "X" and "Y" are the names of the two APIs being compared. This file is automatically regenerated each time the report is generated. If the -d directory argument is used, the user comments XML file also appears, and is expected, in the named directory.
Comments which become unused are moved to the end of the file and placed inside XML comments.

The text which is added can be HTML text if necessary, but if the HTML is incorrect, JDiff may fail to read the comments file and exit. Note that the required HTML is in fact XHTML. Since this HTML is stored in an XML document, single tags without their closing ("slash") element are not permitted. For example, most browsers permit HTML which looks like "<p>Here is some text.", with no closing tag. XML requires that either a closing tag exists ("</p>"), or that the single tag is closed, e.g. "<p/>Here is some text.". HTML p, br and hr tags can be single, due to common usage.

To write comments for a particular removal, addition or change in the JDiff-generated report, edit the comments XML file. Your changes will be automatically incorporated into a new version of this file when the report is next generated. Search the file for the identifier for the particular removal, addition or change, using the package name, class name and member name to find the identifier. Alternatively, look at the HTML source of a report and note the identifier (an HTML named anchor) near the intended place for the comment.

Adding links to comments can be accomplished in two ways: with the {@link} Javadoc tag, or by using HTML links directly.

To link to a class, use the package and class name, e.g. {@link packagename.classname}.

To link to a specific method in a class' HTML page, use the package, class name, a pound sign, and then the method and parameters, or () e.g. {@link packagename.classname#methodname(params)}.

To link to a specific constructor in a class' HTML page, use the package, class name, a pound sign, and then the classname and parameters, or () e.g. {@link packagename.classname#classname(params)}.

To link to a specific field in a class' HTML page, use the package, class name, a pound sign, and then the name of the field e.g. {@link packagename.classname#fieldname}.

Alternatively, you can use an explicit HTML <a> element. e.g. <a href="packagename.classname.html#methodname">link text<a>. The specific HTML named anchor can be found by looking at the HTML source of a report.

Sometimes you may want to have the same comment text appear in multiple places in the report. You can do this by having multiple <identifier> elements in a single <comment> element. This grouping does not persist after the comments file is regenerated.

The first sentence from a comment in the source code for an element is available in the comments XML file by using the @first tag. This tag will be replaced (once) in the comments in the report by the first sentence from the appropriate Javadoc comment.

TROUBLESHOOTING

PROBLEM POSSIBLE SOLUTION
Error: two projects are needed, one
<old> and one <new>
The Ant JDiff task needs Ant 1.6.1 to work correctly
You are not connected to the Internet, or are behind a firewall See the documentation for how to use the -baseURI optionThis only applies to generating JDiff output, not to viewing it.

No changes are seen in the report. By default, Javadoc and JDiff only show public and protected classes and members.

No changes seen for package and private classes. Enable both the correct Javadoc visibility level (-public, -protected, -package, -private) and the correct JDiff visibility level (-excludeclass, -excludemember).

No comments were inserted for packages. You need to use the -sourcepath argument to locate the source code files, so that JDiff can deduce where the package.html file with comments about the package may be. If no package.html file exists or can be found, then no comments can be suggested for packages. Of course, comments can still be added by hand.

JDiff takes a long time to load XML, or throws java.net.NoRouteToHostException: Operation timed out. The validation portion of loading the XML file currently requires the ability to make an HTTP connection. Check your network and try again, or see the -baseURI option and the next suggestion.

From behind a firewall, JDiff fails to load one of the required XML DTD files. Use the following settings to tell the Java2 VM that you are behind a firewall:
java -DproxySet=true -DproxyHost=PROXYSERVER -DproxyPort=PORT
where PROXYSERVER is the hostname or IP address of your proxy server, and PORT is the port number of the proxy server.

The other alternative is to use the local copies of the required files by using the option -baseURI when generating the API XML files. For example, -baseURI "file:///C:/jdiff/lib" would cause the XML parser to use the copies which are shipped in the lib directory, if JDiff is installed in C:\jdiff. Note that there are three forward slashes after "file:". The -baseURI approach has the advantage that it requires no connectivity to the Internet to be able to run JDiff.

JDiff fails to handle assert in J2SE1.4 Be sure to use the -source 1.4 argument to Javadoc to handle assertions present in J2SE1.4 source code.

Using an XML parser other than Xerces Set the org.xml.sax.driver system property to the name of the XML parser class which you wish to use. Setting a system property is usually done by passing -Dname=value to the JVM. To cause Javadoc to pass an argument to the underlying JVM, use -J-Dname=value. To pass an argument to Javadoc from within an ANT Javadoc task, use the additionalparam attribute, e.g. additionalparam="-J-Dorg.xml.sax.driver=com.example.my.driver"

Comparing Jar files results in duplicate class changes being reported. Be sure to use the -packagesonly option when using Jar files as the input to JDiff. You should not need to use -packagesonly otherwise.

Documentation difference page becomes all changes part way through. This problem can occur if incorrect HTML is written in the new documentation. JDiff shows this HTML on the documentation difference page, and can cause entries later on in the page to be displayed incorrectly.
One solution is to edit the documentation difference page by hand, but the better solution is to fix the offending HTML in the new source code.

The background color of my HTML report is not correct. Check that the file background.gif from the lib is in the same directory as the changes.html file.

The names of exceptions are too long in the HTML report. To use short names for exceptions, set the showExceptionTypes boolean to false in XMLToAPI.java file and recompile.

ERRORS AND WARNING MESSAGES

The warnings and error messages which can be generated by JDiff are as follows:

ERROR MESSAGE POSSIBLE CAUSE

Error: unknown element type. The XML file contains an element tag which the current version of JDiff cannot recognize. This may occur if an older version of JDiff is used with XML files generated by a newer version.

Error: IO Error while attempting to create X. Java was unable to open a file for writing. May occur if the user does not have write permission for the current directory.

Error: no identifier found in the comments XML file. The XML file for the comments for the report must contain an identifier to indicate which report of differing APIs these comments are written for.

Error: unknown program element type. Internal JDiff error.

Error: could not create the subdirectory X. Java was unable to create a directory. May occur if the user does not have write or execute permission for the current directory.

Error: file X does not exist for the [old|new] API. The XML files corresponding to the names given to -oldapi and -newapi are not in the current directory. This may be because the XML files have not yet been generated, or were generated elsewhere.
It can also occur if the XML file was generated with one API identifier, and is now being read in with another identifier. Either use the same identifier, or change the <api> name element value in the XML file to the new API identifier.

Error: no API identifier found in the XML file X. The given XML file does not have an identifier in it, probably due to manual modification.

Error: no packages found in the APIs. JDiff was unable to find any packages in the arguments given to Javadoc.

WARNING MESSAGE POSSIBLE CAUSE

Warning: illegal string found in text. Ignoring the comment. The suggested comments from Javadoc are stored in XML files in a CDATA element, which permits every string except .

Warning: no difference between the APIs. There was no difference between the APIs. You are probably comparing two identical XML files.

Warning: no classes found in the package X. A package without classes was encountered.

Warning: change from deprecated to undeprecated for class X. A class changed from being deprecated to being undeprecated in the next release. This is usually either poor software design or a misplaced @deprecated Javadoc tag.

Warning: change from deprecated to undeprecated for a constructor in class X. A constructor changed from being deprecated to being undeprecated in the next release. This is usually either poor software design or a misplaced @deprecated Javadoc tag.

Warning: change from deprecated to undeprecated for method X. A method changed from being deprecated to being undeprecated in the next release. This is usually either poor software design or a misplaced @deprecated Javadoc tag.

Warning: text of comment does not end in a period. Generated when the -checkcomments is used. The suggested comment does not end in a period, question mark or exclamation mark.

Warning: N identical ids in the existing comments file. Using the first instance. The comments file contains comment for multiple places in the report, but N of the identifiers for the comment are non-unique.

Warning: incorrectly formatted @link in text. JDiff was unable to parse the @link in the suggested comment.

Warning: comment com.acme.sp is no longer used. The comment in the comments file intended for the given element is no longer needed, since the element is no longer part of the changes between the APIs. The comment will be moved to the end of the comments file and preserved, but not used.

Warning: API identifier in the comments XML file differs from the name of the file. The comments file keeps track of which APIs it is to be used for, and has detected a mismatch with the names of the current APIs.

Warning: multiple @deprecated tags found in comments for X. Using the first one only. A comment with more than one @deprecated tag was encountered in the source code. This is considered poor Javadoc style.

Warning: @ tag seen in comment. An @ tag other than @link has somehow made its way into a suggested comment. This should not occur, but can be remedied by editing the comments file to use a different comment.

Warning: duplicate class : X found. Using the first instance only. Multiple instances of the same fully qualified class name were found in the API XML file. Most likely caused by manual modification of the file after it was generated.

Warning: missing @since tag A class, constructor, method or field was added in the later API but no @since tag was found in the Javadoc comment. This information is logged into a file missingSinces.txt in the same directory as changes.html. This file is informational only. The boolean to control this behaviour is in the source file HTMLIndexes.java.

Warning: API identifier in the XML file X differs from the name of the file Y. The name given to -apiname when the XML file is generated is embedded in the XML file as a top-level attribute. This warning suggests that the XML file has been modified by hand, but that report generation should proceed using the new API identifier.

DIFFERENCE STATISTICS

During the generation of a report, JDiff also reports a percentage difference between the two APIs being compared, e.g. "Approximately 10% difference between the APIs". This statistic is calculated in the following way:
 
Percentage change = 100 * (added + removed + 2*changed)
                    -----------------------------------
                    sum of public elements in BOTH APIs
So if there are 15 packages in the old API, and 2 of these are removed, and 17 packages in the new API, 1 of which is newly added, and only 3 of which have changed, then the simple percentage difference would be:
100 * (1 + 2 + 2*3)/ (15 + 17) = 28%
A change of 100% means that there are no packages in common between the two APIs. A change of 0% indicates that nothing changed between the two APIs. This formula is applied recursively in JDiff for classes and their members. That is, the value for the number of packages changed is not an integer, but instead is the value obtained by applying the same formula to the all the classes in the changed packages, and then to all the members of the changed classes. This results in a lower, but more accurate, percentage difference. The percentage difference value does not appear anywhere in the HTML report files generated by JDiff. The test suite for JDiff v1.0 had a difference value of approximately 63%. A real-world value is the value for the differences between J2SE1.2 and J2SE1.3, which is approximately 8%.

LIMITATIONS

While Java is highly backward compatible, so that, for example, the XML for a J2SE1.2 application can be generated using JDiff with J2SE1.3, there are a few cases where classes will appear in the XML of the API which are not present in the source code. These classes appear to be inserted by javac or javadoc. An example of this is the class java.awt.Robot, which is inserted into the XML for J2SE1.2 if javadoc in J2SE1.3 is used, but not does not appear in the XML if javadoc in J2SE1.2 is used.
To avoid these (rare) cases, it is recommended that you use the same version of the J2SE that the application was written for.

JDiff does not tell you how two Javadoc web pages differ in layout, though it can tell you how the content has changed. Nor does it compare what the methods in an API do; if JDiff could tell you what had changed about the way two versions of an API execute, the Halting Problem would be solved, and our lives would be very different.

On a P3 450MHz machine, to scan all of the J2SE Java and javax packages and generate XML takes about 2 minutes per version. To generate a report from the XML files takes about 30s

JDiff User Documentation

CONTENTS

OVERVIEW

INSTALLATION

SYNOPSIS

OUTPUT

ADDING COMMENTS TO A REPORT

TROUBLESHOOTING

ERRORS AND WARNING MESSAGES

DIFFERENCE STATISTICS

LIMITATIONS

FURTHER READING

Attribute	Description	Required
destdir	The location where the JDiff report will be generated. Defaults to a directory "jdiff_report" in the directory from where Ant was executed.	No
stats	Generate an HTML page of statistical information about the differences between the two APIs. Defaults to "off".	No
docchanges	Enables comparison of Javadoc documentation. Defaults to "off".	No
verbose	Increase the logging vebosity of the task. Defaults to "off".	No

PROBLEM	POSSIBLE SOLUTION
Error: two projects are needed, one <old> and one <new>	The Ant JDiff task needs Ant 1.6.1 to work correctly
You are not connected to the Internet, or are behind a firewall	See the documentation for how to use the `-baseURI` optionThis only applies to generating JDiff output, not to viewing it.
No changes are seen in the report.	By default, Javadoc and JDiff only show public and protected classes and members.
No changes seen for package and private classes.	Enable both the correct Javadoc visibility level (-public, -protected, -package, -private) and the correct JDiff visibility level (-excludeclass, -excludemember).
No comments were inserted for packages.	You need to use the `-sourcepath` argument to locate the source code files, so that JDiff can deduce where the `package.html` file with comments about the package may be. If no `package.html` file exists or can be found, then no comments can be suggested for packages. Of course, comments can still be added by hand.
JDiff takes a long time to load XML, or throws `java.net.NoRouteToHostException: Operation timed out`.	The validation portion of loading the XML file currently requires the ability to make an HTTP connection. Check your network and try again, or see the `-baseURI` option and the next suggestion.
From behind a firewall, JDiff fails to load one of the required XML DTD files.	Use the following settings to tell the Java2 VM that you are behind a firewall: `java -DproxySet=true -DproxyHost=PROXYSERVER -DproxyPort=PORT` where `PROXYSERVER` is the hostname or IP address of your proxy server, and `PORT` is the port number of the proxy server. The other alternative is to use the local copies of the required files by using the option `-baseURI` when generating the API XML files. For example, `-baseURI "file:///C:/jdiff/lib"` would cause the XML parser to use the copies which are shipped in the `lib` directory, if JDiff is installed in `C:\jdiff`. Note that there are three forward slashes after "file:". The `-baseURI` approach has the advantage that it requires no connectivity to the Internet to be able to run JDiff.
JDiff fails to handle `assert` in J2SE1.4	Be sure to use the `-source 1.4` argument to Javadoc to handle assertions present in J2SE1.4 source code.
Using an XML parser other than Xerces	Set the `org.xml.sax.driver` system property to the name of the XML parser class which you wish to use. Setting a system property is usually done by passing `-Dname=value` to the JVM. To cause Javadoc to pass an argument to the underlying JVM, use `-J-Dname=value`. To pass an argument to Javadoc from within an ANT Javadoc task, use the `additionalparam` attribute, e.g. `additionalparam="-J-Dorg.xml.sax.driver=com.example.my.driver"`
Comparing Jar files results in duplicate class changes being reported.	Be sure to use the `-packagesonly` option when using Jar files as the input to JDiff. You should not need to use `-packagesonly` otherwise.
Documentation difference page becomes all changes part way through.	This problem can occur if incorrect HTML is written in the new documentation. JDiff shows this HTML on the documentation difference page, and can cause entries later on in the page to be displayed incorrectly. One solution is to edit the documentation difference page by hand, but the better solution is to fix the offending HTML in the new source code.
The background color of my HTML report is not correct.	Check that the file `background.gif` from the `lib` is in the same directory as the `changes.html` file.
The names of exceptions are too long in the HTML report.	To use short names for exceptions, set the `showExceptionTypes` boolean to `false` in `XMLToAPI.java` file and recompile.

ERROR MESSAGE	POSSIBLE CAUSE
Error: unknown element type.	The XML file contains an element tag which the current version of JDiff cannot recognize. This may occur if an older version of JDiff is used with XML files generated by a newer version.
Error: IO Error while attempting to create X.	Java was unable to open a file for writing. May occur if the user does not have write permission for the current directory.
Error: no identifier found in the comments XML file.	The XML file for the comments for the report must contain an identifier to indicate which report of differing APIs these comments are written for.
Error: unknown program element type.	Internal JDiff error.
Error: could not create the subdirectory X.	Java was unable to create a directory. May occur if the user does not have write or execute permission for the current directory.
Error: file X does not exist for the [old\|new] API.	The XML files corresponding to the names given to `-oldapi` and `-newapi` are not in the current directory. This may be because the XML files have not yet been generated, or were generated elsewhere. It can also occur if the XML file was generated with one API identifier, and is now being read in with another identifier. Either use the same identifier, or change the <api> name element value in the XML file to the new API identifier.
Error: no API identifier found in the XML file X.	The given XML file does not have an identifier in it, probably due to manual modification.
Error: no packages found in the APIs.	JDiff was unable to find any packages in the arguments given to Javadoc.

WARNING MESSAGE	POSSIBLE CAUSE
Warning: illegal string found in text. Ignoring the comment.	The suggested comments from Javadoc are stored in XML files in a CDATA element, which permits every string except .
Warning: no difference between the APIs.	There was no difference between the APIs. You are probably comparing two identical XML files.
Warning: no classes found in the package X.	A package without classes was encountered.
Warning: change from deprecated to undeprecated for class X.	A class changed from being deprecated to being undeprecated in the next release. This is usually either poor software design or a misplaced @deprecated Javadoc tag.
Warning: change from deprecated to undeprecated for a constructor in class X.	A constructor changed from being deprecated to being undeprecated in the next release. This is usually either poor software design or a misplaced @deprecated Javadoc tag.
Warning: change from deprecated to undeprecated for method X.	A method changed from being deprecated to being undeprecated in the next release. This is usually either poor software design or a misplaced @deprecated Javadoc tag.
Warning: text of comment does not end in a period.	Generated when the `-checkcomments` is used. The suggested comment does not end in a period, question mark or exclamation mark.
Warning: N identical ids in the existing comments file. Using the first instance.	The comments file contains comment for multiple places in the report, but N of the identifiers for the comment are non-unique.
Warning: incorrectly formatted @link in text.	JDiff was unable to parse the @link in the suggested comment.
Warning: comment com.acme.sp is no longer used.	The comment in the comments file intended for the given element is no longer needed, since the element is no longer part of the changes between the APIs. The comment will be moved to the end of the comments file and preserved, but not used.
Warning: API identifier in the comments XML file differs from the name of the file.	The comments file keeps track of which APIs it is to be used for, and has detected a mismatch with the names of the current APIs.
Warning: multiple @deprecated tags found in comments for X. Using the first one only.	A comment with more than one @deprecated tag was encountered in the source code. This is considered poor Javadoc style.
Warning: @ tag seen in comment.	An @ tag other than @link has somehow made its way into a suggested comment. This should not occur, but can be remedied by editing the comments file to use a different comment.
Warning: duplicate class : X found. Using the first instance only.	Multiple instances of the same fully qualified class name were found in the API XML file. Most likely caused by manual modification of the file after it was generated.
Warning: missing @since tag	A class, constructor, method or field was added in the later API but no @since tag was found in the Javadoc comment. This information is logged into a file `missingSinces.txt` in the same directory as `changes.html`. This file is informational only. The boolean to control this behaviour is in the source file `HTMLIndexes.java`.
Warning: API identifier in the XML file X differs from the name of the file Y.	The name given to `-apiname` when the XML file is generated is embedded in the XML file as a top-level attribute. This warning suggests that the XML file has been modified by hand, but that report generation should proceed using the new API identifier.