jdiff

Class HTMLReportGenerator

public class HTMLReportGenerator extends Object

Emit HTML based on the changes between two sets of APIs. See the file LICENSE.txt for copyright details.
Field Summary
static StringdocTitle
The title used on the first page of the report.
static booleandoStats
To generate statistical output, set this to true.
static StringnewDocPrefix
Define the prefix for HTML links to the existing set of Javadoc- generated documentation for the new API.
static booleannoCommentsOnAdditions
If set, then do not suggest comments for additions from the first sentence of the doc block of the new API.
static booleannoCommentsOnChanges
If set, then do not suggest comments for changes from the first sentence of the doc block of the new API.
static booleannoCommentsOnRemovals
If set, then do not suggest comments for removals from the first sentence of the doc block of the old API.
static StringoldDocPrefix
Define the prefix for HTML links to the existing set of Javadoc- generated documentation for the old API.
static StringoutputDir
The destination directory for output files.
static booleanreportDocChanges
If set, then report changes in documentation (Javadoc comments) between the old and the new API.
static StringwindowTitle
The browser window title for the report.
Constructor Summary
HTMLReportGenerator()
Default constructor.
Method Summary
voidemitChanges(MemberDiff memberDiff, int memberType)
Emit all changes associated with a MemberDiff as an entry in a table.
voidemitComment(String commentID, String possibleComment, int linkType)
Find any existing comment and emit it.
voidemitException(String ex)
Emit a string which is an exception by surrounding it with <code> tags.
voidemitType(String type)
Emit a string which is a type by surrounding it with <code> tags.
static voidemitTypeWithNoParens(String type)
Emit a string which is a type by surrounding it with <code> tags.
static voidemitTypeWithParens(String type)
Emit a string which is a type by surrounding it with <code> tags.
static voidemitTypeWithParens(String type, boolean addBreaks)
Emit a string which is a type by surrounding it with <code> tags.
voidgenerate(APIComparator comp, Comments existingComments)
Generate the report.
CommentsgetNewComments()
Accessor method for the freshly generated Comments object.
voidindent(int indent)
Emit some non-breaking space for indentation.
StringmakeTwoRows(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.
voidreportAllCtors(String pkgName, ClassDiff classDiff)
Write out the details of constructors in a class.
voidreportAllFields(String pkgName, ClassDiff classDiff)
Write out the details of fields in a class.
voidreportAllMethods(String pkgName, ClassDiff classDiff)
Write out the details of methods in a class.
voidreportChangedClass(String pkgName, ClassDiff[] classDiffs, int classIndex)
Write out the details of a changed class in a separate file.
voidreportChangedPackage(PackageDiff[] pkgDiffs, int pkgIndex)
Write out the details of a changed package in a separate file.
static StringsimpleName(String fqNames)
Return a String with the simple names of the classes in fqName.
voidwriteClassTableEntry(String pkgName, String className, int linkType, boolean isInterface, 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
voidwriteCtorChangedTableEntry(String pkgName, String className, MemberDiff memberDiff)
Write a table entry for a changed constructor.
voidwriteCtorTableEntry(String pkgName, String className, String type, int linkType, String possibleComment, boolean useOld)
Write a table entry for a constructor. linkType: 0 - no link by default, 1 = link to Javadoc HTML file
voidwriteFieldChangedTableEntry(String pkgName, String className, MemberDiff memberDiff)
Write a table entry for a changed field.
voidwriteFieldTableEntry(String pkgName, String className, FieldAPI fieldAPI, int linkType, String possibleComment, boolean useOld)
Write a table entry for a field. linkType: 0 - no link by default, 1 = link to Javadoc HTML file
voidwriteHTMLFooter()
Write the HTML footer.
voidwriteHTMLTitle(String title)
Write the HTML title
voidwriteMethodChangedTableEntry(String pkgName, String className, MemberDiff memberDiff)
Write a table entry for a changed method.
voidwriteMethodTableEntry(String pkgName, String className, MethodAPI methodAPI, int linkType, String possibleComment, boolean useOld)
Write a table entry for a method. linkType: 0 - no link by default, 1 = link to Javadoc HTML file
voidwriteNavigationBar(String pkgName, String prevElemLink, String nextElemLink, String className, int level, boolean upperNavigationBar, boolean hasRemovals, boolean hasAdditions, boolean hasChanges)
Write a navigation bar section header.
voidwritePackageTableEntry(String pkgName, int linkType, 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
voidwriteReport(APIDiff apiDiff)
Write the HTML report.
voidwriteSectionFooter(String packageName, String prevElemLink, String nextElemLink, String className, int level)
Write a section footer, which includes a navigation bar.
voidwriteSectionHeader(String title, String packageName, String prevElemLink, String nextElemLink, String className, int level, boolean hasRemovals, boolean hasAdditions, boolean hasChanges)
Write a section header, which includes a navigation bar.
voidwriteStartHTMLHeader()
Write the start of the HTML header.
voidwriteStartHTMLHeader(boolean addDate)
Write the start of the HTML header.
voidwriteStartHTMLHeaderWithDate()
Write the start of the HTML header, together with the current date and time in an HTML comment.
voidwriteStyleSheetRef()
Write the HTML style sheet reference for files in the subdirectory.
voidwriteStyleSheetRef(boolean inSameDir)
Write the HTML style sheet reference.
voidwriteTableEnd()
Write the end of a table.
voidwriteTableStart(String title, int colSpan)
Write the start of a table.
voidwriteText()
Write a newline out.
voidwriteText(String text)
Write some text out.

Field Detail

docTitle

public static 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.

doStats

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

newDocPrefix

public static 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/"

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.

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.

oldDocPrefix

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

outputDir

public static String outputDir
The destination directory for output files.

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.

windowTitle

public static 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

emitChanges

public void emitChanges(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

emitComment

public void emitComment(String commentID, 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

emitException

public void emitException(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(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.

emitTypeWithNoParens

public static void emitTypeWithNoParens(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.

emitTypeWithParens

public static void emitTypeWithParens(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(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.

generate

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

getNewComments

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

indent

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

makeTwoRows

public String makeTwoRows(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.

reportAllCtors

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

reportAllFields

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

reportAllMethods

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

reportChangedClass

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

reportChangedPackage

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

simpleName

public static String simpleName(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 "".

writeClassTableEntry

public void writeClassTableEntry(String pkgName, String className, int linkType, boolean isInterface, 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

writeCtorChangedTableEntry

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

writeCtorTableEntry

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

writeFieldChangedTableEntry

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

writeFieldTableEntry

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

writeHTMLFooter

public void writeHTMLFooter()
Write the HTML footer.

writeHTMLTitle

public void writeHTMLTitle(String title)
Write the HTML title

writeMethodChangedTableEntry

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

writeMethodTableEntry

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

writeNavigationBar

public void writeNavigationBar(String pkgName, String prevElemLink, String nextElemLink, 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

writePackageTableEntry

public void writePackageTableEntry(String pkgName, int linkType, 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

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.

writeSectionFooter

public void writeSectionFooter(String packageName, String prevElemLink, String nextElemLink, 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

writeSectionHeader

public void writeSectionHeader(String title, String packageName, String prevElemLink, String nextElemLink, 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

writeStartHTMLHeader

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

writeStartHTMLHeader

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

writeStartHTMLHeaderWithDate

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

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.

writeTableEnd

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

writeTableStart

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

writeText

public void writeText()
Write a newline out.

writeText

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