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 += ""; } /** 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; }