package jdiff;
import java.io.*;
import java.util.*;
/* For SAX parsing in APIHandler */
import org.xml.sax.Attributes;
import org.xml.sax.SAXException;
import org.xml.sax.SAXParseException;
import org.xml.sax.XMLReader;
import org.xml.sax.helpers.DefaultHandler;
/**
* Handle the parsing of an XML file and the generation of an API object.
*
* See the file LICENSE.txt for copyright details.
* @author Matthew Doar, mdoar@pobox.com
*/
class APIHandler extends DefaultHandler {
/** The API object which is populated from the XML file. */
public API api_;
/** Default constructor. */
public APIHandler(API api, boolean createGlobalComments) {
api_ = api;
createGlobalComments_ = createGlobalComments;
tagStack = new LinkedList();
}
/** If set, then check that each comment is a sentence. */
public static boolean checkIsSentence = false;
/**
* Contains the name of the current package element type
* where documentation is being added. Also used as the level
* at which to add documentation into an element, i.e. class-level
* or package-level.
*/
private String currentElement = null;
/** If set, then create the global list of comments. */
private boolean createGlobalComments_ = false;
/** Set if inside a doc element. */
private boolean inDoc = false;
/** The current comment text being assembled. */
private String currentText = null;
/** The current text from deprecation, null if empty. */
private String currentDepText = null;
/**
* The stack of SingleComment objects awaiting the comment text
* currently being assembled.
*/
private LinkedList tagStack = null;
/** Called at the start of the document. */
public void startDocument() {
}
/** Called when the end of the document is reached. */
public void endDocument() {
if (trace)
api_.dump();
System.out.println(" finished");
}
/** Called when a new element is started. */
public void startElement(java.lang.String uri, java.lang.String localName,
java.lang.String qName, Attributes attributes) {
// The change to JAXP compliance produced this change.
if (localName.equals(""))
localName = qName;
if (localName.compareTo("api") == 0) {
String apiName = attributes.getValue("name");
String version = attributes.getValue("jdversion"); // Not used yet
XMLToAPI.nameAPI(apiName);
} else if (localName.compareTo("package") == 0) {
currentElement = localName;
String pkgName = attributes.getValue("name");
XMLToAPI.addPackage(pkgName);
} else if (localName.compareTo("class") == 0) {
currentElement = localName;
String className = attributes.getValue("name");
String parentName = attributes.getValue("extends");
boolean isAbstract = false;
if (attributes.getValue("abstract").compareTo("true") == 0)
isAbstract = true;
XMLToAPI.addClass(className, parentName, isAbstract, getModifiers(attributes));
} else if (localName.compareTo("interface") == 0) {
currentElement = localName;
String className = attributes.getValue("name");
String parentName = attributes.getValue("extends");
boolean isAbstract = false;
if (attributes.getValue("abstract").compareTo("true") == 0)
isAbstract = true;
XMLToAPI.addInterface(className, parentName, isAbstract, getModifiers(attributes));
} else if (localName.compareTo("implements") == 0) {
String interfaceName = attributes.getValue("name");
XMLToAPI.addImplements(interfaceName);
} else if (localName.compareTo("constructor") == 0) {
currentElement = localName;
String ctorType = attributes.getValue("type");
XMLToAPI.addCtor(ctorType, getModifiers(attributes));
} else if (localName.compareTo("method") == 0) {
currentElement = localName;
String methodName = attributes.getValue("name");
String returnType = attributes.getValue("return");
boolean isAbstract = false;
if (attributes.getValue("abstract").compareTo("true") == 0)
isAbstract = true;
boolean isNative = false;
if (attributes.getValue("native").compareTo("true") == 0)
isNative = true;
boolean isSynchronized = false;
if (attributes.getValue("synchronized").compareTo("true") == 0)
isSynchronized = true;
XMLToAPI.addMethod(methodName, returnType, isAbstract, isNative,
isSynchronized, getModifiers(attributes));
} else if (localName.compareTo("field") == 0) {
currentElement = localName;
String fieldName = attributes.getValue("name");
String fieldType = attributes.getValue("type");
boolean isTransient = false;
if (attributes.getValue("transient").compareTo("true") == 0)
isTransient = true;
boolean isVolatile = false;
if (attributes.getValue("volatile").compareTo("true") == 0)
isVolatile = true;
String value = attributes.getValue("value");
XMLToAPI.addField(fieldName, fieldType, isTransient, isVolatile,
value, getModifiers(attributes));
} else if (localName.compareTo("param") == 0) {
String paramName = attributes.getValue("name");
String paramType = attributes.getValue("type");
XMLToAPI.addParam(paramName, paramType);
} else if (localName.compareTo("exception") == 0) {
String paramName = attributes.getValue("name");
String paramType = attributes.getValue("type");
XMLToAPI.addException(paramName, paramType, currentElement);
} else if (localName.compareTo("doc") == 0) {
inDoc = true;
currentText = null;
} else {
if (inDoc) {
// Start of an element, probably an HTML element
addStartTagToText(localName, attributes);
} else {
System.out.println("Error: unknown element type: " + localName);
System.exit(-1);
}
}
}
/** Called when the end of an element is reached. */
public void endElement(java.lang.String uri, java.lang.String localName,
java.lang.String qName) {
if (localName.equals(""))
localName = qName;
// Deal with the end of doc blocks
if (localName.compareTo("doc") == 0) {
inDoc = false;
// Add the assembled comment text to the appropriate current
// program element, as determined by currentElement.
addTextToComments();
} else if (inDoc) {
// An element was found inside the HTML text
addEndTagToText(localName);
} else if (currentElement.compareTo("constructor") == 0 &&
localName.compareTo("constructor") == 0) {
currentElement = "class";
} else if (currentElement.compareTo("method") == 0 &&
localName.compareTo("method") == 0) {
currentElement = "class";
} else if (currentElement.compareTo("field") == 0 &&
localName.compareTo("field") == 0) {
currentElement = "class";
} else if (currentElement.compareTo("class") == 0 ||
currentElement.compareTo("interface") == 0) {
// Feature request 510307 and bug 517383: duplicate comment ids.
// The end of a member element leaves the currentElement at the
// "class" level, but the next class may in fact be an interface
// and so the currentElement here will be "interface".
if (localName.compareTo("class") == 0 ||
localName.compareTo("interface") == 0) {
currentElement = "package";
}
}
}
/** Called to process text. */
public void characters(char[] ch, int start, int length) {
if (inDoc) {
String chunk = new String(ch, start, length);
if (currentText == null)
currentText = chunk;
else
currentText += chunk;
}
}
/**
* Trim the current text, check it is a sentence and add it to the
* current program element.
*/
public void addTextToComments() {
// Eliminate any whitespace at each end of the text.
currentText = currentText.trim();
// Convert any @link tags to HTML links.
if (convertAtLinks) {
currentText = Comments.convertAtLinks(currentText, currentElement,
api_.currPkg_, api_.currClass_);
}
// Check that it is a sentence
if (checkIsSentence && !currentText.endsWith(".") &&
currentText.compareTo(Comments.placeHolderText) != 0) {
System.out.println("Warning: text of comment does not end in a period: " + currentText);
}
// The construction of the commentID assumes that the
// documentation is the final element to be parsed. The format matches
// the format used in the report generator to look up comments in the
// the existingComments object.
String commentID = null;
// Add this comment to the current API element.
if (currentElement.compareTo("package") == 0) {
api_.currPkg_.doc_ = currentText;
commentID = api_.currPkg_.name_;
} else if (currentElement.compareTo("class") == 0 ||
currentElement.compareTo("interface") == 0) {
api_.currClass_.doc_ = currentText;
commentID = api_.currPkg_.name_ + "." + api_.currClass_.name_;
} else if (currentElement.compareTo("constructor") == 0) {
api_.currCtor_.doc_ = currentText;
commentID = api_.currPkg_.name_ + "." + api_.currClass_.name_ +
".ctor_changed(";
if (api_.currCtor_.type_.compareTo("void") == 0)
commentID = commentID + ")";
else
commentID = commentID + api_.currCtor_.type_ + ")";
} else if (currentElement.compareTo("method") == 0) {
api_.currMethod_.doc_ = currentText;
commentID = api_.currPkg_.name_ + "." + api_.currClass_.name_ +
"." + api_.currMethod_.name_ + "_changed(" +
api_.currMethod_.getSignature() + ")";
} else if (currentElement.compareTo("field") == 0) {
api_.currField_.doc_ = currentText;
commentID = api_.currPkg_.name_ + "." + api_.currClass_.name_ +
"." + api_.currField_.name_;
}
// Add to the list of possible comments for use when an
// element has changed (not removed or added).
if (createGlobalComments_ && commentID != null) {
String ct = currentText;
// Use any deprecation text as the possible comment, ignoring
// any other comment text.
if (currentDepText != null) {
ct = currentDepText;
currentDepText = null; // Never reuse it. Bug 469794
}
String ctOld = (String)(Comments.allPossibleComments.put(commentID, ct));
if (ctOld != null) {
System.out.println("Error: duplicate comment id: " + commentID);
System.exit(5);
}
}
}
/**
* Add the start tag to the current comment text.
*/
public void addStartTagToText(String localName, Attributes attributes) {
// Need to insert the HTML tag into the current text
String currentHTMLTag = localName;
// Save the tag in a stack
tagStack.add(currentHTMLTag);
String tag = "<" + currentHTMLTag;
// Now add all the attributes into the current text
int len = attributes.getLength();
for (int i = 0; i < len; i++) {
String name = attributes.getLocalName(i);
String value = attributes.getValue(i);
tag += " " + name + "=\"" + value+ "\"";
}
// End the tag
if (Comments.isMinimizedTag(currentHTMLTag)) {
tag += "/>";
} else {
tag += ">";
}
// Now insert the HTML tag into the current text
if (currentText == null)
currentText = tag;
else
currentText += tag;
}
/**
* Add the end tag to the current comment text.
*/
public void addEndTagToText(String localName) {
// Close the current HTML tag
String currentHTMLTag = (String)(tagStack.removeLast());
if (!Comments.isMinimizedTag(currentHTMLTag))
currentText += "</" + currentHTMLTag + ">";
}
/** Extra modifiers which are common to all program elements. */
public Modifiers getModifiers(Attributes attributes) {
Modifiers modifiers = new Modifiers();
modifiers.isStatic = false;
if (attributes.getValue("static").compareTo("true") == 0)
modifiers.isStatic = true;
modifiers.isFinal = false;
if (attributes.getValue("final").compareTo("true") == 0)
modifiers.isFinal = true;
modifiers.isDeprecated = false;
String cdt = attributes.getValue("deprecated");
if (cdt.compareTo("not deprecated") == 0) {
modifiers.isDeprecated = false;
currentDepText = null;
} else if (cdt.compareTo("deprecated, no comment") == 0) {
modifiers.isDeprecated = true;
currentDepText = null;
} else {
modifiers.isDeprecated = true;
currentDepText = API.showHTMLTags(cdt);
}
modifiers.visibility = attributes.getValue("visibility");
return modifiers;
}
public void warning(SAXParseException e) {
System.out.println("Warning (" + e.getLineNumber() + "): parsing XML API file:" + e);
e.printStackTrace();
}
public void error(SAXParseException e) {
System.out.println("Error (" + e.getLineNumber() + "): parsing XML API file:" + e);
e.printStackTrace();
System.exit(1);
}
public void fatalError(SAXParseException e) {
System.out.println("Fatal Error (" + e.getLineNumber() + "): parsing XML API file:" + e);
e.printStackTrace();
System.exit(1);
}
/**
* If set, then attempt to convert @link tags to HTML links.
* A few of the HTML links may be broken links.
*/
private static boolean convertAtLinks = true;
/** Set to enable increased logging verbosity for debugging. */
private static boolean trace = false;
}