File: jdiff.html

package info (click to toggle)
libspring-java 4.3.30-4
links: PTS, VCS
area: main
in suites: forky, sid
size: 65,728 kB
sloc: java: 566,974; xml: 13,706; sql: 2,313; sh: 87; ruby: 75; jsp: 33; makefile: 29; javascript: 11; python: 4
file content (1032 lines) | stat: -rw-r--r-- 42,959 bytes
parent folder | download | duplicates (4)
<!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="https://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="https://sourceforge.net"> <IMG src="https://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="https://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 &lt;old> and one &lt;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 &lt;<i>API name</i>>]
 [-apidir &lt;<i>optional directory where the API XML file is to be placed</i>>]
 [-oldapi &lt;<i>name of old API</i>>]
 [-oldapidir &lt;<i>optional directory where the old API XML file is located</i>>]
 [-newapi &lt;<i>name of new API</i>>]
 [-newapidir &lt;<i>optional directory where the new API XML file is located</i>>]
 [-sourcepath &lt;<i>source path</i>>]
 [-javadocnew &lt;<i>javadoc files location for the new API</i>>]
 [-javadocold &lt;<i>javadoc files location for the old API</i>>]
 [-baseURI &lt;<i>base</i>>]
 [-excludeclass &lt;<i>exclusion level</i>>]
 [-excludemember &lt;<i>exclusion level</i>>]
 [-nosuggest &lt;<i>suggestion level</i>>]
 [-firstsentence]
 [-docchanges]
 [-checkcomments]
 [-packagesonly]
 [-showallchanges]
 [-retainnonprinting]
 [-excludetag &lt;<i>exclude tag</i>>]
 [-stats]
 [-windowtitle &lt;<i>text</i>>]
 [-doctitle &lt;<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> &lt;<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> &lt;<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> &lt;<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> &lt;<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> &lt;<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> &lt;<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> &lt;<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> &lt;<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. "https://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> &lt;<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. "https://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> &lt;<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> &lt;<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> &lt;<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> &lt;<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 &quot;jdiffjar&quot; script, when
   comparing Jar files.
   If this options is not used when comparing Jar files, duplicate
   classes with no packages (&quot;anonymous&quot; 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="https://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 &lt;<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 &lt;<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 
  &quot;API Differences Between &lt;name of old API&gt; and 
  &lt;name of new API&gt;&quot;.
  </DD>

  <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
  <code>-doctitle &lt;<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 
  &quot;API Differences Between &lt;name of old API&gt; and 
  &lt;name of new API&gt;&quot;.
  </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="https://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 "&lt;p>Here is some 
  text.", with no closing tag. XML requires that either a closing tag exists ("&lt;/p>"), 
  or that the single tag is closed, e.g. "&lt;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
&lt;a> element.  e.g. 
<nobr>&lt;a href="packagename.classname.html#methodname">link text&lt;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
&lt;identifier> elements in a single &lt;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
&lt;old> and one &lt;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 &lt;api&gt; 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="https://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="https://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="https://java.sun.com/j2se/javadoc/">Javadoc</A> and Doclet
	documentation from Sun.</LI>
  <LI><A HREF="https://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 &copy; 2001-2007 <a href="mailto:mdoar@pobox.com">Matthew B. Doar</a><br>
</font>
</p>

</BODY>
</HTML>