<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
<TITLE>JDiff User Documentation</TITLE>
</HEAD>
<BODY BGCOLOR="#ffffff">
<table width="100%">
<tr>
<td align="left"><A href="http://sourceforge.net/projects/javadiff/">
<IMG src="http://javadiff.cvs.sourceforge.net/*checkout*/javadiff/jdiff/lib/jdiff_logo.gif"
width="88" height="31" border="0" alt="JDiff Logo"></A></td>
<td align="right"><A href="http://sourceforge.net"> <IMG src="http://sourceforge.net/sflogo.php?group_id=37160" width="88" height="31" border="0" alt="SourceForge Logo"></A></td>
</tr>
</table>
<center>
<H1>JDiff User Documentation</H1><br>
</center>
<BLOCKQUOTE>
<b>JDiff</b> is a Javadoc <a
href="http://java.sun.com/j2se/javadoc">doclet</a> 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.
</BLOCKQUOTE>
<HR>
<H2>CONTENTS</H2>
<UL>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#overview"><B>Overview</B></A></P></LI>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#installation"><B>Installation</B></A></P></LI>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#synopsis"><B>Synopsis</B></A></P></LI>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#output"><B>Output</B></A></P></LI>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#addingcomments"><B>Adding
Comments to a Report</B></A></P></LI>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#troubleshooting"><B>Troubleshooting</B></A></P></LI>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#errorswarnings"><B>Errors
and Warning Messages</B></A></P></LI>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#differencestatistics"><B>Difference Statistics</B></A></P></LI>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#limitations"><B>Limitations</B></A></P></LI>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#furtherreading"><B>Further Reading</B></A></P></LI>
</UL>
<HR>
<A NAME="overview"></A>
<H2>OVERVIEW</H2>
<BLOCKQUOTE>
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.
</BLOCKQUOTE>
<BLOCKQUOTE>
The results are written into a file called <code>changes.html</code>,
with more files in a subdirectory called <code>changes</code>. These
files can contain links to existing Javadoc documentation. A CSS
stylesheet is also generated in the file
<code>stylesheet-jdiff.css</code>, and this uses a background image in
<code>background.gif</code>. <i>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</i>. If the <code>-stats</code>
option was used, then the file <code>black.gif</code> should also be
shipped.
</BLOCKQUOTE>
<BLOCKQUOTE>
There is a working example of how to use JDiff in the <code>examples</code>
directory of the source distribution.
</BLOCKQUOTE>
<hr>
<A NAME="installation"></A>
<H2>INSTALLATION</H2>
<BLOCKQUOTE>
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.
</BLOCKQUOTE>
<BLOCKQUOTE>
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.
</BLOCKQUOTE>
<BLOCKQUOTE>
The Ant JDiff task needs Ant 1.6.1 to work correctly. Using Ant
1.5 will produce the error:
<pre>
Error: two projects are needed, one <old> and one <new>
</pre>
</BLOCKQUOTE>
<BLOCKQUOTE>
No Windows registry entries are changed by JDiff. To remove JDiff,
simply delete the directory where it is was unpacked.
</BLOCKQUOTE>
<hr>
<H2><A NAME="synopsis"></A>SYNOPSIS</H2>
<BLOCKQUOTE>
The Ant JDiff task has the following parameters:
</BLOCKQUOTE>
<BLOCKQUOTE>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td><b>Attribute</b></td>
<td><b>Description</b></td>
<td align="center"><b>Required</b></td>
</tr>
<tr>
<td>destdir</td>
<td>The location where the JDiff report will be generated. Defaults to a directory "jdiff_report" in the directory from where Ant was executed.</td>
<td align="center">No</td>
</tr>
<tr>
<td>stats</td>
<td>Generate an HTML page of statistical information about the
differences between the two APIs. Defaults to "off".</td>
<td align="center">No</td>
</tr>
<tr>
<td>docchanges</td>
<td>Enables comparison of Javadoc documentation. Defaults to "off".</td>
<td align="center">No</td>
</tr>
<tr>
<td>verbose</td>
<td>Increase the logging vebosity of the task. Defaults to "off".</td>
<td align="center">No</td>
</tr>
</table>
</BLOCKQUOTE>
<BLOCKQUOTE>
<b>Parameters specified as nested elements</b>
</BLOCKQUOTE>
<BLOCKQUOTE>
The <code>old</code> and <code>new</code> elements are used to describe the projects to be compared.
</BLOCKQUOTE>
<BLOCKQUOTE>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td><b>Attribute</b></td>
<td><b>Description</b></td>
<td align="center"><b>Required</b></td>
</tr>
<tr>
<td>name</td>
<td>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 <code>destdir</code>,
which is generated by JDiff to represent the structure of the source files of this project.</td>
<td align="center">Yes</td>
</tr>
<tr>
<td>javadoc</td>
<td>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 <code>name</code> in <code>destdir</code>.</td>
<td align="center">No</td>
</tr>
</table>
</BLOCKQUOTE>
<BLOCKQUOTE>
Note: the <code>old</code> and <code>new</code> elements only have <code>DirSet</code> nested elements, not <code>FileSet</code> ones.
</BLOCKQUOTE>
<BLOCKQUOTE>
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:
</BLOCKQUOTE>
<PRE STYLE="margin-left: 1cm; margin-right: 1cm; margin-bottom:0.5cm">
javadoc -doclet <b>jdiff.JDiff</b> -docletpath jdiff.jar
[-apiname <<i>API name</i>>]
[-apidir <<i>optional directory where the API XML file is to be placed</i>>]
[-oldapi <<i>name of old API</i>>]
[-oldapidir <<i>optional directory where the old API XML file is located</i>>]
[-newapi <<i>name of new API</i>>]
[-newapidir <<i>optional directory where the new API XML file is located</i>>]
[-sourcepath <<i>source path</i>>]
[-javadocnew <<i>javadoc files location for the new API</i>>]
[-javadocold <<i>javadoc files location for the old API</i>>]
[-baseURI <<i>base</i>>]
[-excludeclass <<i>exclusion level</i>>]
[-excludemember <<i>exclusion level</i>>]
[-nosuggest <<i>suggestion level</i>>]
[-firstsentence]
[-docchanges]
[-checkcomments]
[-packagesonly]
[-showallchanges]
[-retainnonprinting]
[-excludetag <<i>exclude tag</i>>]
[-stats]
[-windowtitle <<i>text</i>>]
[-doctitle <<i>HTML text</i>>]
[-version]
[-help]
</PRE>
<BLOCKQUOTE>
NOTE: Either <code>-apiname</code>, or both <code>-oldapi</code> and
<code>-newapi</code> must be used. All other arguments are optional.
</BLOCKQUOTE>
<BLOCKQUOTE>
The <code>-d directory</code> argument works just as with Javadoc, redirecting
the HTML output to the given directory.
</BLOCKQUOTE>
<P STYLE="margin-left: 1cm; margin-bottom: 0cm">The arguments for the JDiff doclet are:</P>
<DL>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-apiname</code> <<i>API name</i>></DT>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
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 <code>-apidir</code> argument.
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-oldapi</code> <<i>name of old API</i>></DT>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
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 <code>-apiname</code> when
the XML file was generated.
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-newapi</code> <<i>name of old API</i>></DT>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
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 <code>-apiname</code> when
the XML file was generated.
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-apidir</code> <<i>API directory</i>></DT>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
Defines the directory where the API XML file is to be placed. Used in
conjunction with the <code>-apiname</code> argument.
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-oldapidir</code> <<i>old API directory</i>></DT>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
Defines the directory where the XML file for the old API is located.
Used in conjunction with the <code>-oldapi</code> argument. Default is the current
directory.
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-newapidir</code> <<i>new API directory</i>></DT>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
Defines the directory where the XML file for the new API is located.
Used in conjunction with the <code>-newapi</code> argument. Default is the current
directory.
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-sourcepath</code> <<i>source path</i>></DT>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
Define the path to the set of Java source
files (the API)
to be scanned, e.g. <code>examples/SuperProduct1.0</code>. The
slashes in this argument should match the local architecture.
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-javadocnew</code> <<i>javadoc files location for the new API</i>></DT>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
The location of existing Javadoc files
for the new API, e.g. "http://java.sun.com/j2se/<b>1.5.0</b>/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. <b>The argument
should also always end in a forward slash.</b> If a relative value is
given, it should be relative to files in the "changes" directory
generated by JDiff.
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-javadocold</code> <<i>javadoc files location for the old API</i>></DT>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm"> The location of existing
Javadoc files for the old API, e.g. "http://java.sun.com/j2se/<b>1.5.0</b>/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. <b>The argument should also always end in a forward slash.</b> If a relative
value is given, it should be relative to files in the "changes" directory
generated by JDiff.
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<A NAME="baseURIoption"></A>
<code>-baseURI</code> <<i>base</i>></DT>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
Use \"base\" as the base location of the various DTDs used by
JDiff. For example, <code>-baseURI "file:///C:/jdiff/lib"</code> would cause
the XML parser to use the copies which are shipped in the
<code>lib</code> directory, if JDiff is installed in
<code>C:\jdiff</code>. Note that there are <i>three</i> forward slashes
after "file:".
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-excludeclass</code> <<i>exclusion level</i>></DT>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
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 <code>-private</code>
argument must also be passed to Javadoc.
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-excludemember</code> <<i>exclusion level</i>></DT>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
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 <code>-private</code>
argument must also be passed to Javadoc.
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-firstsentence</code></dt>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
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 <code>-docchanges</code> for how to
note documentation changes as differences.<br>
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-docchanges</code></dt>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
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 <code>-firstsentence</code> option for how to compare just
the first sentence in Javadoc documentation.
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-nosuggest</code> <<i>suggestion level</i>></dt>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
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 <a href="#addingcomments">below</a>).
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.
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-checkcomments</code></DT>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
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.
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-packagesonly</code></DT>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
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.
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-showallchanges</code></DT>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
If this argument is used, JDiff will show changes in
native and synchronized modifiers. See <a href="http://java.sun.com/j2se/1.4.1/docs/tooldocs/solaris/javadoc.html#generatedapideclarations">here</a> for why these are not shown by default.
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-retainnonprinting</code></DT>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
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.
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-excludetag <<i>exclude tag</i>></code></DT>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
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 <code>foo</code>, containing
<code>-excludetag @exclude</code>.
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-stats</code></DT>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
Generate an HTML page of statistical information about the
differences between the two APIs.
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-windowtitle <<i>text</i>></code></DT>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
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>".
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-doctitle <<i>HTML text</i>></code></DT>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
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>".
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-version</code></DT>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
Display the version of JDiff.
</DD>
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
<code>-help</code></DT>
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
Display the usage summary for JDiff.
</DD>
</DL>
<hr>
<H2><A NAME="output"></A>OUTPUT</H2>
<BLOCKQUOTE>
<ul>
<li>Interfaces appear in <i>italics</i>, just as in Javadoc documentation.</li>
<li>When a package or class appears in <b>bold</b>, it has been added in
the new version or API.</li>
<li>When a package or class appears <strike>struck through</strike>, it has been removed in
the new version or API.</li>
<li>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.</li>
<li>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.</li>
<li>With large packages, it is often necessary to change the memory parameters for
Javadoc, e.g. pass in <code>-J-Xmx128m</code> to Javadoc.</li>
<li>The <code>api.xsd</code> template describes the format of the XML
for the APIs, and the <code>comments.xsd</code> 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 <i>de facto</i> standard in the future, whilst retaining backward
compatibility. To enable validation, set the boolean <code>validateXML</code> in
the file <code>XMLToAPI.java</code> and recompile.</li>
<li>Comments in the comments XML file do get reordered during
regeneration. This is harmless.</li>
</ul>
</BLOCKQUOTE>
<hr>
<H2><A NAME="addingcomments"></A>ADDING COMMENTS TO A REPORT</H2>
<BLOCKQUOTE>
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 <code>-d directory</code> argument is used, the user comments XML
file also appears, and is expected, in the named directory.
<p>Comments which become unused are
moved to the end of the file and placed inside XML comments.
</BLOCKQUOTE>
<BLOCKQUOTE> 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 <a href="http://www.w3.org/TR/xhtml1/diffs.html">XHTML</a>. 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.
</BLOCKQUOTE>
<BLOCKQUOTE>
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.
</BLOCKQUOTE>
<BLOCKQUOTE>
Adding links to comments can be accomplished in two ways: with the {@link} Javadoc tag, or by using HTML links directly.
<ul>
<li>
To link to a class, use the package and class name, e.g. <nobr>{@link
packagename.classname}.</nobr>
</li>
<li>
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. <nobr>{@link packagename.classname#methodname(params)}.</nobr>
</li>
<li>
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. <nobr>{@link packagename.classname#classname(params)}.</nobr>
</li>
<li>
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. <nobr>{@link packagename.classname#fieldname}.</nobr>
</li>
</ul>
Alternatively, you can use an explicit HTML
<a> element. e.g.
<nobr><a href="packagename.classname.html#methodname">link text<a></nobr>.
The specific HTML named anchor can be found by looking at the HTML
source of a report.
</BLOCKQUOTE>
<BLOCKQUOTE>
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.
</BLOCKQUOTE>
<BLOCKQUOTE>
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.
</BLOCKQUOTE>
<br><hr><br>
<H2><A NAME="troubleshooting"></A>TROUBLESHOOTING</H2>
<BLOCKQUOTE>
<TABLE border="1" width="80%">
<TR>
<TD VALIGN="top" align="center"><b>PROBLEM</b></TD>
<TD VALIGN="top" align="center"><b>POSSIBLE SOLUTION</b></TD>
</TR>
<TR>
<TD VALIGN="top"><pre>Error: two projects are needed, one
<old> and one <new></pre></TD>
<TD VALIGN="top">The Ant JDiff task needs Ant 1.6.1 to work correctly</TD>
</TR>
<TR>
<TD VALIGN="top">You are not connected to the Internet, or are behind a firewall</TD>
<TD VALIGN="top">See the <a href="#baseURIoption">documentation</a> for how to use
the <code>-baseURI</code>
optionThis only applies to generating JDiff output,
not to viewing it.</TD>
</TR>
<TR>
<TD VALIGN="top">No changes are seen in the report.</TD>
<TD VALIGN="top">By default, Javadoc and JDiff only show public
and protected classes and members.</TD>
</TR>
<TR>
<TD VALIGN="top">No changes seen for package and private classes.</TD>
<TD VALIGN="top">Enable both the correct Javadoc visibility level
(-public, -protected, -package, -private) and the correct JDiff
visibility level (-excludeclass, -excludemember).</TD>
</TR>
<TR>
<TD VALIGN="top">No comments were inserted for packages.</TD>
<TD VALIGN="top">You need to use the <code>-sourcepath</code> argument to
locate the source code files, so that
JDiff can deduce where the <code>package.html</code> file with
comments about the package may be. If no <code>package.html</code>
file exists or can be found, then no comments can be suggested
for packages. Of course, comments can still be
<a href="#addingcomments">added by hand</a>.</TD>
</TR>
<TR>
<TD VALIGN="top">JDiff takes a long time to load XML, or throws
<code>java.net.NoRouteToHostException: Operation timed out</code>.</TD>
<TD VALIGN="top">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 <code>-baseURI</code>
option and the next suggestion.</TD>
</TR>
<TR>
<TD VALIGN="top">From behind a firewall,
<A NAME="troubleshootingFirewall"></A>
JDiff fails to load one of the required XML DTD files.</TD>
<TD VALIGN="top">Use the following settings to tell the Java2 VM
that you are behind a firewall:<br>
<code><nobr>java -DproxySet=true -DproxyHost=PROXYSERVER</nobr><nobr> -DproxyPort=PORT</nobr></code><br>
where <code>PROXYSERVER</code> is the hostname or IP address of
your proxy server, and <code>PORT</code> is the port number of the
proxy server.<br><br>
The other alternative is to use the local copies of the required
files by using the option <code>-baseURI</code> when generating the API XML
files. For example, <code>-baseURI "file:///C:/jdiff/lib"</code> would cause
the XML parser to use the copies which are shipped in the
<code>lib</code> directory, if JDiff is installed in
<code>C:\jdiff</code>. Note that there are <i>three</i> forward slashes
after "file:".
The <code>-baseURI</code> approach has the advantage that it
requires <i>no</i> connectivity to the Internet to be able to run JDiff.
</TD>
</TR>
<TR>
<TD VALIGN="top">JDiff fails to handle <code>assert</code> in J2SE1.4</TD>
<TD VALIGN="top">Be sure to use the <code>-source 1.4</code> argument to
Javadoc to handle assertions present in J2SE1.4 source code.
</TD>
</TR>
<TR>
<TD VALIGN="top">Using an XML parser other than Xerces</TD>
<TD VALIGN="top">Set the <code>org.xml.sax.driver</code> system property to
the name of the XML parser class which you wish to use. Setting a system
property is usually done by passing <nobr><code>-Dname=value</code></nobr> to the JVM.
To cause Javadoc to pass an argument to the underlying JVM, use
<code>-J-Dname=value</code>. To pass an argument to Javadoc from within
an ANT Javadoc task, use the <code>additionalparam</code> attribute, e.g.
<nobr><code>additionalparam="-J-Dorg.xml.sax.driver=com.example.my.driver"</code><nobr>
</TD>
</TR>
<TR>
<TD VALIGN="top">Comparing Jar files results in duplicate class
changes being reported.</TD>
<TD VALIGN="top">Be sure to use the <code>-packagesonly</code>
option when using Jar files as the input to JDiff. You should not
need to use <code>-packagesonly</code> otherwise.
</TD>
</TR>
<TR>
<TD VALIGN="top">Documentation difference page becomes all changes
part way through.</TD>
<TD VALIGN="top">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.
<p>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.
</TD>
</TR>
<TR>
<TD VALIGN="top">The background color of my HTML report is not correct.</TD>
<TD VALIGN="top">Check that the file <code>background.gif</code> from the <code>lib</code> is in the same directory as the <code>changes.html</code> file.
</TD>
</TR>
<TR>
<TD VALIGN="top">The names of exceptions are too long in the HTML report.</TD>
<TD VALIGN="top">To use short names for exceptions, set the
<code>showExceptionTypes</code> boolean to <code>false</code> in
<code>XMLToAPI.java</code> file and recompile.
</TD>
</TR>
</TABLE>
</BLOCKQUOTE>
<hr>
<H2><A NAME="errorswarnings"></A>ERRORS AND WARNING MESSAGES</H2>
<BLOCKQUOTE>
The warnings and error messages which can be generated by JDiff are as
follows:
</BLOCKQUOTE>
<BLOCKQUOTE>
<TABLE border="1">
<TR>
<TD VALIGN="top" align="center" width="25%"><b>ERROR MESSAGE</b></TD>
<TD VALIGN="top" align="center"><b>POSSIBLE CAUSE</b></TD>
</TR>
<TR>
<TD VALIGN="top">Error: unknown element type.</TD>
<TD VALIGN="top">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.</TD>
</TR>
<TR>
<TD VALIGN="top">Error: IO Error while attempting to create <i>X</i>.</TD>
<TD VALIGN="top">Java was unable to open a file for writing. May
occur if the user does not have write permission for the current
directory.</TD>
</TR>
<TR>
<TD VALIGN="top">Error: no identifier found in the comments XML file.</TD>
<TD VALIGN="top">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.</TD>
</TR>
<TR>
<TD VALIGN="top">Error: unknown program element type.</TD>
<TD VALIGN="top">Internal JDiff error.</TD>
</TR>
<TR>
<TD VALIGN="top">Error: could not create the subdirectory <i>X</i>.</TD>
<TD VALIGN="top">Java was unable to create a directory. May
occur if the user does not have write or execute permission for the current
directory.</TD>
</TR>
<TR>
<TD VALIGN="top">Error: file <i>X</i> does not exist for the [old|new] API.</TD>
<TD VALIGN="top">The XML files corresponding to the names given to
<code>-oldapi</code> and <code>-newapi</code> are not in the
current directory. This may be because the XML files have not yet been
generated, or were generated elsewhere.<br>
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.</TD>
</TR>
<TR>
<TD VALIGN="top">Error: no API identifier found in the XML file <i>X</i>.</TD>
<TD VALIGN="top">The given XML file does not have an identifier in
it, probably due to manual modification.</TD>
</TR>
<TR>
<TD VALIGN="top">Error: no packages found in the APIs.</TD>
<TD VALIGN="top">JDiff was unable to find any packages in the
arguments given to Javadoc.</TD>
</TR>
</TABLE>
</BLOCKQUOTE>
<BLOCKQUOTE>
<TABLE border="1">
<TR>
<TD VALIGN="top" align="center" width="25%"><b>WARNING MESSAGE</b></TD>
<TD VALIGN="top" align="center"><b>POSSIBLE CAUSE</b></TD>
</TR>
<TR>
<TD VALIGN="top">Warning: illegal string found in text. Ignoring the comment.</TD>
<TD VALIGN="top">The suggested comments from Javadoc are stored in
XML files in a CDATA element, which permits every string except .</TD>
</TR>
<TR>
<TD VALIGN="top">Warning: no difference between the APIs.</TD>
<TD VALIGN="top">There was no difference between the APIs. You are
probably comparing two identical XML files.</TD>
</TR>
<TR>
<TD VALIGN="top">Warning: no classes found in the package <i>X</i>.</TD>
<TD VALIGN="top">A package without classes was encountered.</TD>
</TR>
<TR>
<TD VALIGN="top">Warning: change from deprecated to undeprecated for class <i>X</i>.</TD>
<TD VALIGN="top">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.</TD>
</TR>
<TR>
<TD VALIGN="top">Warning: change from deprecated to undeprecated
for a constructor in class <i>X</i>.</TD>
<TD VALIGN="top">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.</TD>
</TR>
<TR>
<TD VALIGN="top">Warning: change from deprecated to undeprecated for method <i>X</i>.</TD>
<TD VALIGN="top">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.</TD>
</TR>
<TR>
<TD VALIGN="top">Warning: text of comment does not end in a period.</TD>
<TD VALIGN="top">Generated when the <code>-checkcomments</code> is
used. The suggested comment does not end in a period, question mark or exclamation mark.</TD>
</TR>
<TR>
<TD VALIGN="top">Warning: <i>N</i> identical ids in the existing comments file. Using the first instance.</TD>
<TD VALIGN="top">The comments file contains comment for multiple
places in the report, but <i>N</i> of the identifiers for the comment
are non-unique.</TD>
</TR>
<TR>
<TD VALIGN="top">Warning: incorrectly formatted @link in text.</TD>
<TD VALIGN="top">JDiff was unable to parse the @link in the
suggested comment.</TD>
</TR>
<TR>
<TD VALIGN="top">Warning: comment <i>com.acme.sp</i> is no longer used.</TD>
<TD VALIGN="top">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.</TD>
</TR>
<TR>
<TD VALIGN="top">Warning: API identifier in the comments XML file differs from the name of the file.</TD>
<TD VALIGN="top">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.</TD>
</TR>
<TR>
<TD VALIGN="top">Warning: multiple @deprecated tags found in comments for <i>X</i>. Using the first one only.</TD>
<TD VALIGN="top">A comment with more than one @deprecated tag was
encountered in the source code. This is considered poor Javadoc style.</TD>
</TR>
<TR>
<TD VALIGN="top">Warning: @ tag seen in comment.</TD>
<TD VALIGN="top">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.</TD>
</TR>
<TR>
<TD VALIGN="top">Warning: duplicate class : <i>X</i> found. Using the first instance only.</TD>
<TD VALIGN="top">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.</TD>
</TR>
<TR>
<TD VALIGN="top">Warning: missing @since tag</TD>
<TD VALIGN="top">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
<code>missingSinces.txt</code> in the same directory as
<code>changes.html</code>. This file is informational only. The
boolean to control this behaviour is in the source file
<code>HTMLIndexes.java</code>.
</TD>
</TR>
<TR>
<TD VALIGN="top">Warning: API identifier in the XML file <i>X</i> differs from the name of the file <i>Y</i>.</TD>
<TD VALIGN="top">The name given to <code>-apiname</code> 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.</TD>
</TR>
</TABLE>
</BLOCKQUOTE>
<hr>
<H2><A NAME="differencestatistics"></A>DIFFERENCE STATISTICS</H2>
<BLOCKQUOTE>
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:
<pre>
Percentage change = 100 * (added + removed + 2*changed)
-----------------------------------
sum of public elements in BOTH APIs
</pre>
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:
<pre>
100 * (1 + 2 + 2*3)/ (15 + 17) = 28%
</pre>
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%.
</BLOCKQUOTE>
<hr>
<H2><A NAME="limitations"></A>LIMITATIONS</H2>
<BLOCKQUOTE>
<ol>
<li>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
<code>javac</code> or <code>javadoc</code>. An example of this is the class
<code>java.awt.Robot</code>, which is inserted into the XML for
J2SE1.2 if <code>javadoc</code> in J2SE1.3 is used, but not does not appear in
the XML if <code>javadoc</code> in J2SE1.2 is used.<br>
To avoid these (rare) cases, it is recommended that you <i>use the same version
of the J2SE that the application was written for</i>.</li>
<li>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 <a
href="http://en.wikipedia.org/wiki/Halting_Problem">Halting
Problem</a> would be solved, and our lives would be very different.</li>
<li>On a P3 450MHz machine, to scan all of the J2SE <code>Java</code>
and <code>javax</code> packages and generate XML takes about 2 minutes
per version. To generate a report from the XML files takes about 30s</li>
</ol>
</BLOCKQUOTE>
<hr>
<H2><A NAME="furtherreading"></A>FURTHER READING</H2>
<BLOCKQUOTE>
<UL>
<LI><A HREF="http://www.sys-con.com/java">Java Developer's Journal
</A>, April 2002 contained an article about JDiff. The article
can also be <a
href="http://javadiff.cvs.sourceforge.net/*checkout*/javadiff/jdiff/doc/JDiffArticle.pdf">found
here</a>.</LI>
<LI><A HREF="http://java.sun.com/j2se/javadoc/">Javadoc</A> and Doclet
documentation from Sun.</LI>
<LI><A HREF="http://java.sun.com/j2se/javadoc/faq.html#doclets">Third-party
doclets</a> as listed by Sun.</LI>
<LI><A HREF="http://www.doclet.com">Third-party doclets</a> as listed by others.</LI>
</UL>
</BLOCKQUOTE>
<hr>
<center>
This software comes with absolutely NO WARRANTY. See the LGPL in the file <a href="http://javadiff.cvs.sourceforge.net/*checkout*/javadiff/jdiff/LICENSE.txt">LICENSE.txt</a> for
details.
</center>
<p align="center">
<font size="-1">
Copyright © 2001-2007 <a href="mailto:mdoar@pobox.com">Matthew B. Doar</a><br>
</font>
</p>
</BODY>
</HTML>
