jdiff
Class HTMLReportGenerator

java.lang.Object
  extended byjdiff.HTMLReportGenerator

public class HTMLReportGenerator
extends java.lang.Object

Emit HTML based on the changes between two sets of APIs. See the file LICENSE.txt for copyright details.


Field Summary
static java.lang.String docTitle
          The title used on the first page of the report.
static boolean doStats
          To generate statistical output, set this to true.
static java.lang.String newDocPrefix
          Define the prefix for HTML links to the existing set of Javadoc- generated documentation for the new API.
static boolean noCommentsOnAdditions
          If set, then do not suggest comments for additions from the first sentence of the doc block of the new API.
static boolean noCommentsOnChanges
          If set, then do not suggest comments for changes from the first sentence of the doc block of the new API.
static boolean noCommentsOnRemovals
          If set, then do not suggest comments for removals from the first sentence of the doc block of the old API.
static java.lang.String oldDocPrefix
          Define the prefix for HTML links to the existing set of Javadoc- generated documentation for the old API.
static java.lang.String outputDir
          The destination directory for output files.
static boolean reportDocChanges
          If set, then report changes in documentation (Javadoc comments) between the old and the new API.
static java.lang.String windowTitle
          The browser window title for the report.
 
Constructor Summary
HTMLReportGenerator()
          Default constructor.
 
Method Summary
 void emitChanges(jdiff.MemberDiff memberDiff, int memberType)
          Emit all changes associated with a MemberDiff as an entry in a table.
 void emitComment(java.lang.String commentID, java.lang.String possibleComment, int linkType)
          Find any existing comment and emit it.
 void emitException(java.lang.String ex)
          Emit a string which is an exception by surrounding it with <code> tags.
 void emitType(java.lang.String type)
          Emit a string which is a type by surrounding it with <code> tags.
static void emitTypeWithNoParens(java.lang.String type)
          Emit a string which is a type by surrounding it with <code> tags.
static void emitTypeWithParens(java.lang.String type)
          Emit a string which is a type by surrounding it with <code> tags.
static void emitTypeWithParens(java.lang.String type, boolean addBreaks)
          Emit a string which is a type by surrounding it with <code> tags.
 void generate(APIComparator comp, Comments existingComments)
          Generate the report.
 Comments getNewComments()
          Accessor method for the freshly generated Comments object.
 void indent(int indent)
          Emit some non-breaking space for indentation.
 java.lang.String makeTwoRows(java.lang.String name)
          If a class or package name is considered to be too long for convenient display, insert
in the middle of it at a period.
 void reportAllCtors(java.lang.String pkgName, jdiff.ClassDiff classDiff)
          Write out the details of constructors in a class.
 void reportAllFields(java.lang.String pkgName, jdiff.ClassDiff classDiff)
          Write out the details of fields in a class.
 void reportAllMethods(java.lang.String pkgName, jdiff.ClassDiff classDiff)
          Write out the details of methods in a class.
 void reportChangedClass(java.lang.String pkgName, jdiff.ClassDiff[] classDiffs, int classIndex)
          Write out the details of a changed class in a separate file.
 void reportChangedPackage(jdiff.PackageDiff[] pkgDiffs, int pkgIndex)
          Write out the details of a changed package in a separate file.
static java.lang.String simpleName(java.lang.String fqNames)
          Return a String with the simple names of the classes in fqName.
 void writeClassTableEntry(java.lang.String pkgName, java.lang.String className, int linkType, boolean isInterface, java.lang.String possibleComment, boolean useOld)
          Write a table entry for a class or interface.
 void writeCtorChangedTableEntry(java.lang.String pkgName, java.lang.String className, jdiff.MemberDiff memberDiff)
          Write a table entry for a changed constructor.
 void writeCtorTableEntry(java.lang.String pkgName, java.lang.String className, java.lang.String type, int linkType, java.lang.String possibleComment, boolean useOld)
          Write a table entry for a constructor.
 void writeFieldChangedTableEntry(java.lang.String pkgName, java.lang.String className, jdiff.MemberDiff memberDiff)
          Write a table entry for a changed field.
 void writeFieldTableEntry(java.lang.String pkgName, java.lang.String className, jdiff.FieldAPI fieldAPI, int linkType, java.lang.String possibleComment, boolean useOld)
          Write a table entry for a field.
 void writeHTMLFooter()
          Write the HTML footer.
 void writeHTMLTitle(java.lang.String title)
          Write the HTML title
 void writeMethodChangedTableEntry(java.lang.String pkgName, java.lang.String className, jdiff.MemberDiff memberDiff)
          Write a table entry for a changed method.
 void writeMethodTableEntry(java.lang.String pkgName, java.lang.String className, jdiff.MethodAPI methodAPI, int linkType, java.lang.String possibleComment, boolean useOld)
          Write a table entry for a method.
 void writeNavigationBar(java.lang.String pkgName, java.lang.String prevElemLink, java.lang.String nextElemLink, java.lang.String className, int level, boolean upperNavigationBar, boolean hasRemovals, boolean hasAdditions, boolean hasChanges)
          Write a navigation bar section header.
 void writePackageTableEntry(java.lang.String pkgName, int linkType, java.lang.String possibleComment, boolean useOld)
          Write a table entry for a package, with support for links to Javadoc for removed packages.
 void writeReport(APIDiff apiDiff)
          Write the HTML report.
 void writeSectionFooter(java.lang.String packageName, java.lang.String prevElemLink, java.lang.String nextElemLink, java.lang.String className, int level)
          Write a section footer, which includes a navigation bar.
 void writeSectionHeader(java.lang.String title, java.lang.String packageName, java.lang.String prevElemLink, java.lang.String nextElemLink, java.lang.String className, int level, boolean hasRemovals, boolean hasAdditions, boolean hasChanges)
          Write a section header, which includes a navigation bar.
 void writeStartHTMLHeader()
          Write the start of the HTML header.
 void writeStartHTMLHeader(boolean addDate)
          Write the start of the HTML header.
 void writeStartHTMLHeaderWithDate()
          Write the start of the HTML header, together with the current date and time in an HTML comment.
 void writeStyleSheetRef()
          Write the HTML style sheet reference for files in the subdirectory.
 void writeStyleSheetRef(boolean inSameDir)
          Write the HTML style sheet reference.
 void writeTableEnd()
          Write the end of a table.
 void writeTableStart(java.lang.String title, int colSpan)
          Write the start of a table.
 void writeText()
          Write a newline out.
 void writeText(java.lang.String text)
          Write some text out.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

noCommentsOnRemovals

public static boolean noCommentsOnRemovals
If set, then do not suggest comments for removals from the first sentence of the doc block of the old API.


noCommentsOnAdditions

public static boolean noCommentsOnAdditions
If set, then do not suggest comments for additions from the first sentence of the doc block of the new API.


noCommentsOnChanges

public static boolean noCommentsOnChanges
If set, then do not suggest comments for changes from the first sentence of the doc block of the new API.


reportDocChanges

public static boolean reportDocChanges
If set, then report changes in documentation (Javadoc comments) between the old and the new API. The default is that this is not set.


newDocPrefix

public static java.lang.String newDocPrefix
Define the prefix for HTML links to the existing set of Javadoc- generated documentation for the new API. E.g. For J2SE1.3.x, use "http://java.sun.com/j2se/1.3/docs/api/"


oldDocPrefix

public static java.lang.String oldDocPrefix
Define the prefix for HTML links to the existing set of Javadoc- generated documentation for the old API.


doStats

public static boolean doStats
To generate statistical output, set this to true.


outputDir

public static java.lang.String outputDir
The destination directory for output files.


docTitle

public static java.lang.String docTitle
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>". It can be set by using the -doctitle option.


windowTitle

public static java.lang.String windowTitle
The browser window title for the report. By default, this is "API Differences Between <name of old API> and <name of new API>". It can be set by using the -windowtitle option.

Constructor Detail

HTMLReportGenerator

public HTMLReportGenerator()
Default constructor.

Method Detail

getNewComments

public Comments getNewComments()
Accessor method for the freshly generated Comments object. The list of comments is sorted before the object is returned.


generate

public void generate(APIComparator comp,
                     Comments existingComments)
Generate the report.


writeReport

public void writeReport(APIDiff apiDiff)
Write the HTML report. The top section describes all the packages added (with links) and removed, and the changed packages section has links which takes you to a section for each package. This pattern continues for classes and constructors, methods and fields.


reportChangedPackage

public void reportChangedPackage(jdiff.PackageDiff[] pkgDiffs,
                                 int pkgIndex)
Write out the details of a changed package in a separate file.


reportChangedClass

public void reportChangedClass(java.lang.String pkgName,
                               jdiff.ClassDiff[] classDiffs,
                               int classIndex)
Write out the details of a changed class in a separate file.


reportAllCtors

public void reportAllCtors(java.lang.String pkgName,
                           jdiff.ClassDiff classDiff)
Write out the details of constructors in a class.


reportAllMethods

public void reportAllMethods(java.lang.String pkgName,
                             jdiff.ClassDiff classDiff)
Write out the details of methods in a class.


reportAllFields

public void reportAllFields(java.lang.String pkgName,
                            jdiff.ClassDiff classDiff)
Write out the details of fields in a class.


writeStartHTMLHeaderWithDate

public void writeStartHTMLHeaderWithDate()
Write the start of the HTML header, together with the current date and time in an HTML comment.


writeStartHTMLHeader

public void writeStartHTMLHeader()
Write the start of the HTML header.


writeStartHTMLHeader

public void writeStartHTMLHeader(boolean addDate)
Write the start of the HTML header.


writeHTMLTitle

public void writeHTMLTitle(java.lang.String title)
Write the HTML title


writeStyleSheetRef

public void writeStyleSheetRef()
Write the HTML style sheet reference for files in the subdirectory.


writeStyleSheetRef

public void writeStyleSheetRef(boolean inSameDir)
Write the HTML style sheet reference. If inSameDir is set, don't add "../" to the location.


writeHTMLFooter

public void writeHTMLFooter()
Write the HTML footer.


writeSectionHeader

public void writeSectionHeader(java.lang.String title,
                               java.lang.String packageName,
                               java.lang.String prevElemLink,
                               java.lang.String nextElemLink,
                               java.lang.String className,
                               int level,
                               boolean hasRemovals,
                               boolean hasAdditions,
                               boolean hasChanges)
Write a section header, which includes a navigation bar.

Parameters:
title - Title of the header. Contains any links necessary.
packageName - The name of the current package, with no slashes or links in it. May be null
prevElemLink - An HTML link to the previous element (a package or class). May be null.
nextElemLink - An HTML link to the next element (a package or class). May be null.
className - The name of the current class, with no slashes or links in it. May be null.
level - 0 = overview, 1 = package, 2 = class/interface

writeSectionFooter

public void writeSectionFooter(java.lang.String packageName,
                               java.lang.String prevElemLink,
                               java.lang.String nextElemLink,
                               java.lang.String className,
                               int level)
Write a section footer, which includes a navigation bar.

Parameters:
packageName - The name of the current package, with no slashes or links in it. may be null
prevElemLink - An HTML link to the previous element (a package or class). May be null.
nextElemLink - An HTML link to the next element (a package or class). May be null.
className - The name of the current class, with no slashes or links in it. May be null
level - 0 = overview, 1 = package, 2 = class/interface

writeNavigationBar

public void writeNavigationBar(java.lang.String pkgName,
                               java.lang.String prevElemLink,
                               java.lang.String nextElemLink,
                               java.lang.String className,
                               int level,
                               boolean upperNavigationBar,
                               boolean hasRemovals,
                               boolean hasAdditions,
                               boolean hasChanges)
Write a navigation bar section header.

Parameters:
pkgName - The name of the current package, with no slashes or links in it.
prevElemLink - An HTML link to the previous element (a package or class). May be null.
nextElemLink - An HTML link to the next element (a package or class). May be null.
className - The name of the current class, with no slashes or links in it. May be null.
level - 0 = overview, 1 = package, 2 = class/interface

writeTableStart

public void writeTableStart(java.lang.String title,
                            int colSpan)
Write the start of a table.


makeTwoRows

public java.lang.String makeTwoRows(java.lang.String name)
If a class or package name is considered to be too long for convenient display, insert
in the middle of it at a period.


writePackageTableEntry

public void writePackageTableEntry(java.lang.String pkgName,
                                   int linkType,
                                   java.lang.String possibleComment,
                                   boolean useOld)
Write a table entry for a package, with support for links to Javadoc for removed packages. linkType: 0 - no link by default, 1 = link to Javadoc HTML file, 2 = link to JDiff file


writeClassTableEntry

public void writeClassTableEntry(java.lang.String pkgName,
                                 java.lang.String className,
                                 int linkType,
                                 boolean isInterface,
                                 java.lang.String possibleComment,
                                 boolean useOld)
Write a table entry for a class or interface. linkType: 0 - no link by default, 1 = link to Javadoc HTML file, 2 = link to JDiff file


writeCtorTableEntry

public void writeCtorTableEntry(java.lang.String pkgName,
                                java.lang.String className,
                                java.lang.String type,
                                int linkType,
                                java.lang.String possibleComment,
                                boolean useOld)
Write a table entry for a constructor. linkType: 0 - no link by default, 1 = link to Javadoc HTML file


writeCtorChangedTableEntry

public void writeCtorChangedTableEntry(java.lang.String pkgName,
                                       java.lang.String className,
                                       jdiff.MemberDiff memberDiff)
Write a table entry for a changed constructor.


writeMethodTableEntry

public void writeMethodTableEntry(java.lang.String pkgName,
                                  java.lang.String className,
                                  jdiff.MethodAPI methodAPI,
                                  int linkType,
                                  java.lang.String possibleComment,
                                  boolean useOld)
Write a table entry for a method. linkType: 0 - no link by default, 1 = link to Javadoc HTML file


writeMethodChangedTableEntry

public void writeMethodChangedTableEntry(java.lang.String pkgName,
                                         java.lang.String className,
                                         jdiff.MemberDiff memberDiff)
Write a table entry for a changed method.


writeFieldTableEntry

public void writeFieldTableEntry(java.lang.String pkgName,
                                 java.lang.String className,
                                 jdiff.FieldAPI fieldAPI,
                                 int linkType,
                                 java.lang.String possibleComment,
                                 boolean useOld)
Write a table entry for a field. linkType: 0 - no link by default, 1 = link to Javadoc HTML file


writeFieldChangedTableEntry

public void writeFieldChangedTableEntry(java.lang.String pkgName,
                                        java.lang.String className,
                                        jdiff.MemberDiff memberDiff)
Write a table entry for a changed field.


emitChanges

public void emitChanges(jdiff.MemberDiff memberDiff,
                        int memberType)
Emit all changes associated with a MemberDiff as an entry in a table.

Parameters:
memberType - 0 = ctor, 1 = method, 2 = field

emitException

public void emitException(java.lang.String ex)
Emit a string which is an exception by surrounding it with <code> tags. If there is a space in the type, e.g. "String, File", then surround it with parentheses too. Do not add <code> tags or parentheses if the String is "no exceptions".


emitType

public void emitType(java.lang.String type)
Emit a string which is a type by surrounding it with <code> tags. If there is a space in the type, e.g. "String, File", then surround it with parentheses too.


emitTypeWithParens

public static void emitTypeWithParens(java.lang.String type)
Emit a string which is a type by surrounding it with <code> tags. Also surround it with parentheses too. Used to display methods' parameters. Suggestions for where a browser should break the text are provided with <br> and <nobr> tags.


emitTypeWithParens

public static void emitTypeWithParens(java.lang.String type,
                                      boolean addBreaks)
Emit a string which is a type by surrounding it with <code> tags. Also surround it with parentheses too. Used to display methods' parameters.


emitTypeWithNoParens

public static void emitTypeWithNoParens(java.lang.String type)
Emit a string which is a type by surrounding it with <code> tags. Do not surround it with parentheses. Used to display methods' return types and field types.


simpleName

public static java.lang.String simpleName(java.lang.String fqNames)
Return a String with the simple names of the classes in fqName. "java.lang.String" becomes "String", "java.lang.String, java.io.File" becomes "String, File" and so on. If fqName is null, return null. If fqName is "", return "".


emitComment

public void emitComment(java.lang.String commentID,
                        java.lang.String possibleComment,
                        int linkType)
Find any existing comment and emit it. Add the new comment to the list of new comments. The first instance of the string "@first" in a hand-written comment will be replaced by the first sentence from the associated doc block, if such exists. Also replace @link by an HTML link.

Parameters:
commentID - The identifier for this comment.
possibleComment - A possible comment from another source.
linkType - 0 = remove, 1 = add, 2 = change

writeTableEnd

public void writeTableEnd()
Write the end of a table.


writeText

public void writeText()
Write a newline out.


writeText

public void writeText(java.lang.String text)
Write some text out.


indent

public void indent(int indent)
Emit some non-breaking space for indentation.