| package jdiff; |
| |
| import com.sun.javadoc.*; |
| import com.sun.javadoc.ParameterizedType; |
| import com.sun.javadoc.Type; |
| |
| import java.util.*; |
| import java.io.*; |
| import java.lang.reflect.*; |
| |
| /** |
| * Converts a Javadoc RootDoc object into a representation in an |
| * XML file. |
| * |
| * See the file LICENSE.txt for copyright details. |
| * @author Matthew Doar, mdoar@pobox.com |
| */ |
| public class RootDocToXML { |
| |
| /** Default constructor. */ |
| public RootDocToXML() { |
| } |
| |
| /** |
| * Write the XML representation of the API to a file. |
| * |
| * @param root the RootDoc object passed by Javadoc |
| * @return true if no problems encountered |
| */ |
| public static boolean writeXML(RootDoc root) { |
| String tempFileName = outputFileName; |
| if (outputDirectory != null) { |
| tempFileName = outputDirectory; |
| if (!tempFileName.endsWith(JDiff.DIR_SEP)) |
| tempFileName += JDiff.DIR_SEP; |
| tempFileName += outputFileName; |
| } |
| |
| try { |
| FileOutputStream fos = new FileOutputStream(tempFileName); |
| outputFile = new PrintWriter(fos); |
| System.out.println("JDiff: writing the API to file '" + tempFileName + "'..."); |
| if (root.specifiedPackages().length != 0 || root.specifiedClasses().length != 0) { |
| RootDocToXML apiWriter = new RootDocToXML(); |
| apiWriter.emitXMLHeader(); |
| apiWriter.logOptions(); |
| apiWriter.processPackages(root); |
| apiWriter.emitXMLFooter(); |
| } |
| outputFile.close(); |
| } catch(IOException e) { |
| System.out.println("IO Error while attempting to create " + tempFileName); |
| System.out.println("Error: " + e.getMessage()); |
| System.exit(1); |
| } |
| // If validation is desired, write out the appropriate api.xsd file |
| // in the same directory as the XML file. |
| if (XMLToAPI.validateXML) { |
| writeXSD(); |
| } |
| return true; |
| } |
| |
| /** |
| * Write the XML Schema file used for validation. |
| */ |
| public static void writeXSD() { |
| String xsdFileName = outputFileName; |
| if (outputDirectory == null) { |
| int idx = xsdFileName.lastIndexOf('\\'); |
| int idx2 = xsdFileName.lastIndexOf('/'); |
| if (idx == -1 && idx2 == -1) { |
| xsdFileName = ""; |
| } else if (idx == -1 && idx2 != -1) { |
| xsdFileName = xsdFileName.substring(0, idx2); |
| } else if (idx != -1 && idx2 == -1) { |
| xsdFileName = xsdFileName.substring(0, idx); |
| } else if (idx != -1 && idx2 != -1) { |
| int max = idx2 > idx ? idx2 : idx; |
| xsdFileName = xsdFileName.substring(0, max); |
| } |
| } else { |
| xsdFileName = outputDirectory; |
| if (!xsdFileName.endsWith(JDiff.DIR_SEP)) |
| xsdFileName += JDiff.DIR_SEP; |
| } |
| xsdFileName += "api.xsd"; |
| try { |
| FileOutputStream fos = new FileOutputStream(xsdFileName); |
| PrintWriter xsdFile = new PrintWriter(fos); |
| // The contents of the api.xsd file |
| xsdFile.println("<?xml version=\"1.0\" encoding=\"iso-8859-1\" standalone=\"no\"?>"); |
| xsdFile.println("<xsd:schema xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\">"); |
| xsdFile.println(""); |
| xsdFile.println("<xsd:annotation>"); |
| xsdFile.println(" <xsd:documentation>"); |
| xsdFile.println(" Schema for JDiff API representation."); |
| xsdFile.println(" </xsd:documentation>"); |
| xsdFile.println("</xsd:annotation>"); |
| xsdFile.println(); |
| xsdFile.println("<xsd:element name=\"api\" type=\"apiType\"/>"); |
| xsdFile.println(""); |
| xsdFile.println("<xsd:complexType name=\"apiType\">"); |
| xsdFile.println(" <xsd:sequence>"); |
| xsdFile.println(" <xsd:element name=\"package\" type=\"packageType\" minOccurs='1' maxOccurs='unbounded'/>"); |
| xsdFile.println(" </xsd:sequence>"); |
| xsdFile.println(" <xsd:attribute name=\"name\" type=\"xsd:string\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"jdversion\" type=\"xsd:string\"/>"); |
| xsdFile.println("</xsd:complexType>"); |
| xsdFile.println(); |
| xsdFile.println("<xsd:complexType name=\"packageType\">"); |
| xsdFile.println(" <xsd:sequence>"); |
| xsdFile.println(" <xsd:choice maxOccurs='unbounded'>"); |
| xsdFile.println(" <xsd:element name=\"class\" type=\"classType\"/>"); |
| xsdFile.println(" <xsd:element name=\"interface\" type=\"classType\"/>"); |
| xsdFile.println(" </xsd:choice>"); |
| xsdFile.println(" <xsd:element name=\"doc\" type=\"xsd:string\" minOccurs='0' maxOccurs='1'/>"); |
| xsdFile.println(" </xsd:sequence>"); |
| xsdFile.println(" <xsd:attribute name=\"name\" type=\"xsd:string\"/>"); |
| xsdFile.println("</xsd:complexType>"); |
| xsdFile.println(); |
| xsdFile.println("<xsd:complexType name=\"classType\">"); |
| xsdFile.println(" <xsd:sequence>"); |
| xsdFile.println(" <xsd:element name=\"implements\" type=\"interfaceTypeName\" minOccurs='0' maxOccurs='unbounded'/>"); |
| xsdFile.println(" <xsd:element name=\"constructor\" type=\"constructorType\" minOccurs='0' maxOccurs='unbounded'/>"); |
| xsdFile.println(" <xsd:element name=\"method\" type=\"methodType\" minOccurs='0' maxOccurs='unbounded'/>"); |
| xsdFile.println(" <xsd:element name=\"field\" type=\"fieldType\" minOccurs='0' maxOccurs='unbounded'/>"); |
| xsdFile.println(" <xsd:element name=\"doc\" type=\"xsd:string\" minOccurs='0' maxOccurs='1'/>"); |
| xsdFile.println(" </xsd:sequence>"); |
| xsdFile.println(" <xsd:attribute name=\"name\" type=\"xsd:string\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"extends\" type=\"xsd:string\" use='optional'/>"); |
| xsdFile.println(" <xsd:attribute name=\"abstract\" type=\"xsd:boolean\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"src\" type=\"xsd:string\" use='optional'/>"); |
| xsdFile.println(" <xsd:attribute name=\"static\" type=\"xsd:boolean\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"final\" type=\"xsd:boolean\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"deprecated\" type=\"xsd:string\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"visibility\" type=\"xsd:string\"/>"); |
| xsdFile.println("</xsd:complexType>"); |
| xsdFile.println(); |
| xsdFile.println("<xsd:complexType name=\"interfaceTypeName\">"); |
| xsdFile.println(" <xsd:attribute name=\"name\" type=\"xsd:string\"/>"); |
| xsdFile.println("</xsd:complexType>"); |
| xsdFile.println(); |
| xsdFile.println("<xsd:complexType name=\"constructorType\">"); |
| xsdFile.println(" <xsd:sequence>"); |
| xsdFile.println(" <xsd:element name=\"exception\" type=\"exceptionType\" minOccurs='0' maxOccurs='unbounded'/>"); |
| xsdFile.println(" <xsd:element name=\"doc\" type=\"xsd:string\" minOccurs='0' maxOccurs='1'/>"); |
| xsdFile.println(" </xsd:sequence>"); |
| xsdFile.println(" <xsd:attribute name=\"name\" type=\"xsd:string\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"type\" type=\"xsd:string\" use='optional'/>"); |
| xsdFile.println(" <xsd:attribute name=\"src\" type=\"xsd:string\" use='optional'/>"); |
| xsdFile.println(" <xsd:attribute name=\"static\" type=\"xsd:boolean\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"final\" type=\"xsd:boolean\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"deprecated\" type=\"xsd:string\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"visibility\" type=\"xsd:string\"/>"); |
| xsdFile.println("</xsd:complexType>"); |
| xsdFile.println(); |
| xsdFile.println("<xsd:complexType name=\"paramsType\">"); |
| xsdFile.println(" <xsd:attribute name=\"name\" type=\"xsd:string\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"type\" type=\"xsd:string\"/>"); |
| xsdFile.println("</xsd:complexType>"); |
| xsdFile.println(); |
| xsdFile.println("<xsd:complexType name=\"exceptionType\">"); |
| xsdFile.println(" <xsd:attribute name=\"name\" type=\"xsd:string\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"type\" type=\"xsd:string\"/>"); |
| xsdFile.println("</xsd:complexType>"); |
| xsdFile.println(); |
| xsdFile.println("<xsd:complexType name=\"methodType\">"); |
| xsdFile.println(" <xsd:sequence>"); |
| xsdFile.println(" <xsd:element name=\"param\" type=\"paramsType\" minOccurs='0' maxOccurs='unbounded'/>"); |
| xsdFile.println(" <xsd:element name=\"exception\" type=\"exceptionType\" minOccurs='0' maxOccurs='unbounded'/>"); |
| xsdFile.println(" <xsd:element name=\"doc\" type=\"xsd:string\" minOccurs='0' maxOccurs='1'/>"); |
| xsdFile.println(" </xsd:sequence>"); |
| xsdFile.println(" <xsd:attribute name=\"name\" type=\"xsd:string\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"return\" type=\"xsd:string\" use='optional'/>"); |
| xsdFile.println(" <xsd:attribute name=\"abstract\" type=\"xsd:boolean\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"native\" type=\"xsd:boolean\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"synchronized\" type=\"xsd:boolean\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"src\" type=\"xsd:string\" use='optional'/>"); |
| xsdFile.println(" <xsd:attribute name=\"static\" type=\"xsd:boolean\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"final\" type=\"xsd:boolean\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"deprecated\" type=\"xsd:string\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"visibility\" type=\"xsd:string\"/>"); |
| xsdFile.println("</xsd:complexType>"); |
| xsdFile.println(); |
| xsdFile.println("<xsd:complexType name=\"fieldType\">"); |
| xsdFile.println(" <xsd:sequence>"); |
| xsdFile.println(" <xsd:element name=\"doc\" type=\"xsd:string\" minOccurs='0' maxOccurs='1'/>"); |
| xsdFile.println(" </xsd:sequence>"); |
| xsdFile.println(" <xsd:attribute name=\"name\" type=\"xsd:string\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"type\" type=\"xsd:string\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"transient\" type=\"xsd:boolean\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"volatile\" type=\"xsd:boolean\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"value\" type=\"xsd:string\" use='optional'/>"); |
| xsdFile.println(" <xsd:attribute name=\"src\" type=\"xsd:string\" use='optional'/>"); |
| xsdFile.println(" <xsd:attribute name=\"static\" type=\"xsd:boolean\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"final\" type=\"xsd:boolean\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"deprecated\" type=\"xsd:string\"/>"); |
| xsdFile.println(" <xsd:attribute name=\"visibility\" type=\"xsd:string\"/>"); |
| xsdFile.println("</xsd:complexType>"); |
| xsdFile.println(); |
| xsdFile.println("</xsd:schema>"); |
| xsdFile.close(); |
| } catch(IOException e) { |
| System.out.println("IO Error while attempting to create " + xsdFileName); |
| System.out.println("Error: " + e.getMessage()); |
| System.exit(1); |
| } |
| } |
| |
| /** |
| * Write the options which were used to generate this XML file |
| * out as XML comments. |
| */ |
| public void logOptions() { |
| outputFile.print("<!-- "); |
| outputFile.print(" Command line arguments = " + Options.cmdOptions); |
| outputFile.println(" -->"); |
| } |
| |
| /** |
| * Process each package and the classes/interfaces within it. |
| * |
| * @param pd an array of PackageDoc objects |
| */ |
| public void processPackages(RootDoc root) { |
| PackageDoc[] specified_pd = root.specifiedPackages(); |
| Map pdl = new TreeMap(); |
| for (int i = 0; specified_pd != null && i < specified_pd.length; i++) { |
| pdl.put(specified_pd[i].name(), specified_pd[i]); |
| } |
| |
| // Classes may be specified separately, so merge their packages into the |
| // list of specified packages. |
| ClassDoc[] cd = root.specifiedClasses(); |
| // This is lists of the specific classes to document |
| Map classesToUse = new HashMap(); |
| for (int i = 0; cd != null && i < cd.length; i++) { |
| PackageDoc cpd = cd[i].containingPackage(); |
| if (cpd == null && !packagesOnly) { |
| // If the RootDoc object has been created from a jar file |
| // this duplicates classes, so we have to be able to disable it. |
| // TODO this is still null? |
| cpd = root.packageNamed("anonymous"); |
| } |
| String pkgName = cpd.name(); |
| String className = cd[i].name(); |
| if (trace) System.out.println("Found package " + pkgName + " for class " + className); |
| if (!pdl.containsKey(pkgName)) { |
| if (trace) System.out.println("Adding new package " + pkgName); |
| pdl.put(pkgName, cpd); |
| } |
| |
| // Keep track of the specific classes to be used for this package |
| List classes; |
| if (classesToUse.containsKey(pkgName)) { |
| classes = (ArrayList) classesToUse.get(pkgName); |
| } else { |
| classes = new ArrayList(); |
| } |
| classes.add(cd[i]); |
| classesToUse.put(pkgName, classes); |
| } |
| |
| PackageDoc[] pd = (PackageDoc[]) pdl.values().toArray(new PackageDoc[0]); |
| for (int i = 0; pd != null && i < pd.length; i++) { |
| String pkgName = pd[i].name(); |
| |
| // Check for an exclude tag in the package doc block, but not |
| // in the package.htm[l] file. |
| if (!shownElement(pd[i], null)) |
| continue; |
| |
| if (trace) System.out.println("PROCESSING PACKAGE: " + pkgName); |
| outputFile.println("<package name=\"" + pkgName + "\">"); |
| |
| int tagCount = pd[i].tags().length; |
| if (trace) System.out.println("#tags: " + tagCount); |
| |
| List classList; |
| if (classesToUse.containsKey(pkgName)) { |
| // Use only the specified classes in the package |
| System.out.println("Using the specified classes"); |
| classList = (ArrayList) classesToUse.get(pkgName); |
| } else { |
| // Use all classes in the package |
| classList = new LinkedList(Arrays.asList(pd[i].allClasses())); |
| } |
| Collections.sort(classList); |
| ClassDoc[] classes = new ClassDoc[classList.size()]; |
| classes = (ClassDoc[])classList.toArray(classes); |
| processClasses(classes, pkgName); |
| |
| addPkgDocumentation(root, pd[i], 2); |
| |
| outputFile.println("</package>"); |
| } |
| } // processPackages |
| |
| /** |
| * Process classes and interfaces. |
| * |
| * @param cd An array of ClassDoc objects. |
| */ |
| public void processClasses(ClassDoc[] cd, String pkgName) { |
| if (cd.length == 0) |
| return; |
| if (trace) System.out.println("PROCESSING CLASSES, number=" + cd.length); |
| for (int i = 0; i < cd.length; i++) { |
| String className = cd[i].name(); |
| if (trace) System.out.println("PROCESSING CLASS/IFC: " + className); |
| // Only save the shown elements |
| if (!shownElement(cd[i], classVisibilityLevel)) |
| continue; |
| boolean isInterface = false; |
| if (cd[i].isInterface()) |
| isInterface = true; |
| if (isInterface) { |
| outputFile.println(" <!-- start interface " + pkgName + "." + className + " -->"); |
| outputFile.print(" <interface name=\"" + className + "\""); |
| } else { |
| outputFile.println(" <!-- start class " + pkgName + "." + className + " -->"); |
| outputFile.print(" <class name=\"" + className + "\""); |
| } |
| // Add attributes to the class element |
| Type parent = cd[i].superclassType(); |
| if (parent != null) |
| outputFile.println(" extends=\"" + buildEmittableTypeString(parent) + "\""); |
| outputFile.println(" abstract=\"" + cd[i].isAbstract() + "\""); |
| addCommonModifiers(cd[i], 4); |
| outputFile.println(">"); |
| // Process class members. (Treat inner classes as members.) |
| processInterfaces(cd[i].interfaceTypes()); |
| processConstructors(cd[i].constructors()); |
| processMethods(cd[i], cd[i].methods()); |
| processFields(cd[i].fields()); |
| |
| addDocumentation(cd[i], 4); |
| |
| if (isInterface) { |
| outputFile.println(" </interface>"); |
| outputFile.println(" <!-- end interface " + pkgName + "." + className + " -->"); |
| } else { |
| outputFile.println(" </class>"); |
| outputFile.println(" <!-- end class " + pkgName + "." + className + " -->"); |
| } |
| // Inner classes have already been added. |
| /* |
| ClassDoc[] ic = cd[i].innerClasses(); |
| for (int k = 0; k < ic.length; k++) { |
| System.out.println("Inner class " + k + ", name = " + ic[k].name()); |
| } |
| */ |
| }//for |
| }//processClasses() |
| |
| /** |
| * Add qualifiers for the program element as attributes. |
| * |
| * @param ped The given program element. |
| */ |
| public void addCommonModifiers(ProgramElementDoc ped, int indent) { |
| addSourcePosition(ped, indent); |
| // Static and final and visibility on one line |
| for (int i = 0; i < indent; i++) outputFile.print(" "); |
| outputFile.print("static=\"" + ped.isStatic() + "\""); |
| outputFile.print(" final=\"" + ped.isFinal() + "\""); |
| // Visibility |
| String visibility = null; |
| if (ped.isPublic()) |
| visibility = "public"; |
| else if (ped.isProtected()) |
| visibility = "protected"; |
| else if (ped.isPackagePrivate()) |
| visibility = "package"; |
| else if (ped.isPrivate()) |
| visibility = "private"; |
| outputFile.println(" visibility=\"" + visibility + "\""); |
| |
| // Deprecation on its own line |
| for (int i = 0; i < indent; i++) outputFile.print(" "); |
| boolean isDeprecated = false; |
| Tag[] ta = ((Doc)ped).tags("deprecated"); |
| if (ta.length != 0) { |
| isDeprecated = true; |
| } |
| if (ta.length > 1) { |
| System.out.println("JDiff: warning: multiple @deprecated tags found in comments for " + ped.name() + ". Using the first one only."); |
| System.out.println("Text is: " + ((Doc)ped).getRawCommentText()); |
| } |
| if (isDeprecated) { |
| String text = ta[0].text(); // Use only one @deprecated tag |
| if (text != null && text.compareTo("") != 0) { |
| int idx = endOfFirstSentence(text); |
| if (idx == 0) { |
| // No useful comment |
| outputFile.print("deprecated=\"deprecated, no comment\""); |
| } else { |
| String fs = null; |
| if (idx == -1) |
| fs = text; |
| else |
| fs = text.substring(0, idx+1); |
| String st = API.hideHTMLTags(fs); |
| outputFile.print("deprecated=\"" + st + "\""); |
| } |
| } else { |
| outputFile.print("deprecated=\"deprecated, no comment\""); |
| } |
| } else { |
| outputFile.print("deprecated=\"not deprecated\""); |
| } |
| |
| } //addQualifiers() |
| |
| /** |
| * Insert the source code details, if available. |
| * |
| * @param ped The given program element. |
| */ |
| public void addSourcePosition(ProgramElementDoc ped, int indent) { |
| if (!addSrcInfo) |
| return; |
| if (JDiff.javaVersion.startsWith("1.1") || |
| JDiff.javaVersion.startsWith("1.2") || |
| JDiff.javaVersion.startsWith("1.3")) { |
| return; // position() only appeared in J2SE1.4 |
| } |
| try { |
| // Could cache the method for improved performance |
| Class c = ProgramElementDoc.class; |
| Method m = c.getMethod("position", (Class[]) null); |
| Object sp = m.invoke(ped, (Object[]) null); |
| if (sp != null) { |
| for (int i = 0; i < indent; i++) outputFile.print(" "); |
| outputFile.println("src=\"" + sp + "\""); |
| } |
| } catch (NoSuchMethodException e2) { |
| System.err.println("Error: method \"position\" not found"); |
| e2.printStackTrace(); |
| } catch (IllegalAccessException e4) { |
| System.err.println("Error: class not permitted to be instantiated"); |
| e4.printStackTrace(); |
| } catch (InvocationTargetException e5) { |
| System.err.println("Error: method \"position\" could not be invoked"); |
| e5.printStackTrace(); |
| } catch (Exception e6) { |
| System.err.println("Error: "); |
| e6.printStackTrace(); |
| } |
| } |
| |
| /** |
| * Process the interfaces implemented by the class. |
| * |
| * @param ifaces An array of ClassDoc objects |
| */ |
| public void processInterfaces(Type[] ifaces) { |
| if (trace) System.out.println("PROCESSING INTERFACES, number=" + ifaces.length); |
| for (int i = 0; i < ifaces.length; i++) { |
| String ifaceName = buildEmittableTypeString(ifaces[i]); |
| if (trace) System.out.println("PROCESSING INTERFACE: " + ifaceName); |
| outputFile.println(" <implements name=\"" + ifaceName + "\"/>"); |
| }//for |
| }//processInterfaces() |
| |
| /** |
| * Process the constructors in the class. |
| * |
| * @param ct An array of ConstructorDoc objects |
| */ |
| public void processConstructors(ConstructorDoc[] ct) { |
| if (trace) System.out.println("PROCESSING CONSTRUCTORS, number=" + ct.length); |
| for (int i = 0; i < ct.length; i++) { |
| String ctorName = ct[i].name(); |
| if (trace) System.out.println("PROCESSING CONSTRUCTOR: " + ctorName); |
| // Only save the shown elements |
| if (!shownElement(ct[i], memberVisibilityLevel)) |
| continue; |
| outputFile.print(" <constructor name=\"" + ctorName + "\""); |
| |
| Parameter[] params = ct[i].parameters(); |
| boolean first = true; |
| if (params.length != 0) { |
| outputFile.print(" type=\""); |
| for (int j = 0; j < params.length; j++) { |
| if (!first) |
| outputFile.print(", "); |
| emitType(params[j].type()); |
| first = false; |
| } |
| outputFile.println("\""); |
| } else |
| outputFile.println(); |
| addCommonModifiers(ct[i], 6); |
| outputFile.println(">"); |
| |
| // Generate the exception elements if any exceptions are thrown |
| processExceptions(ct[i].thrownExceptions()); |
| |
| addDocumentation(ct[i], 6); |
| |
| outputFile.println(" </constructor>"); |
| }//for |
| }//processConstructors() |
| |
| /** |
| * Process all exceptions thrown by a constructor or method. |
| * |
| * @param cd An array of ClassDoc objects |
| */ |
| public void processExceptions(ClassDoc[] cd) { |
| if (trace) System.out.println("PROCESSING EXCEPTIONS, number=" + cd.length); |
| for (int i = 0; i < cd.length; i++) { |
| String exceptionName = cd[i].name(); |
| if (trace) System.out.println("PROCESSING EXCEPTION: " + exceptionName); |
| outputFile.print(" <exception name=\"" + exceptionName + "\" type=\""); |
| emitType(cd[i]); |
| outputFile.println("\"/>"); |
| }//for |
| }//processExceptions() |
| |
| /** |
| * Process the methods in the class. |
| * |
| * @param md An array of MethodDoc objects |
| */ |
| public void processMethods(ClassDoc cd, MethodDoc[] md) { |
| if (trace) System.out.println("PROCESSING " +cd.name()+" METHODS, number = " + md.length); |
| for (int i = 0; i < md.length; i++) { |
| String methodName = md[i].name(); |
| if (trace) System.out.println("PROCESSING METHOD: " + methodName); |
| // Skip <init> and <clinit> |
| if (methodName.startsWith("<")) |
| continue; |
| // Only save the shown elements |
| if (!shownElement(md[i], memberVisibilityLevel)) |
| continue; |
| outputFile.print(" <method name=\"" + methodName + "\""); |
| com.sun.javadoc.Type retType = md[i].returnType(); |
| if (retType.qualifiedTypeName().compareTo("void") == 0) { |
| // Don't add a return attribute if the return type is void |
| outputFile.println(); |
| } else { |
| outputFile.print(" return=\""); |
| emitType(retType); |
| outputFile.println("\""); |
| } |
| outputFile.print(" abstract=\"" + md[i].isAbstract() + "\""); |
| outputFile.print(" native=\"" + md[i].isNative() + "\""); |
| outputFile.println(" synchronized=\"" + md[i].isSynchronized() + "\""); |
| addCommonModifiers(md[i], 6); |
| outputFile.println(">"); |
| // Generate the parameter elements, if any |
| Parameter[] params = md[i].parameters(); |
| for (int j = 0; j < params.length; j++) { |
| outputFile.print(" <param name=\"" + params[j].name() + "\""); |
| outputFile.print(" type=\""); |
| emitType(params[j].type()); |
| outputFile.println("\"/>"); |
| } |
| |
| // Generate the exception elements if any exceptions are thrown |
| processExceptions(md[i].thrownExceptions()); |
| |
| addDocumentation(md[i], 6); |
| |
| outputFile.println(" </method>"); |
| }//for |
| }//processMethods() |
| |
| /** |
| * Process the fields in the class. |
| * |
| * @param fd An array of FieldDoc objects |
| */ |
| public void processFields(FieldDoc[] fd) { |
| if (trace) System.out.println("PROCESSING FIELDS, number=" + fd.length); |
| for (int i = 0; i < fd.length; i++) { |
| String fieldName = fd[i].name(); |
| if (trace) System.out.println("PROCESSING FIELD: " + fieldName); |
| // Only save the shown elements |
| if (!shownElement(fd[i], memberVisibilityLevel)) |
| continue; |
| outputFile.print(" <field name=\"" + fieldName + "\""); |
| outputFile.print(" type=\""); |
| emitType(fd[i].type()); |
| outputFile.println("\""); |
| outputFile.print(" transient=\"" + fd[i].isTransient() + "\""); |
| outputFile.println(" volatile=\"" + fd[i].isVolatile() + "\""); |
| /* JDK 1.4 and later */ |
| /* |
| String value = fd[i].constantValueExpression(); |
| if (value != null) |
| outputFile.println(" value=\"" + value + "\""); |
| */ |
| addCommonModifiers(fd[i], 6); |
| outputFile.println(">"); |
| |
| addDocumentation(fd[i], 6); |
| |
| outputFile.println(" </field>"); |
| |
| }//for |
| }//processFields() |
| |
| /** |
| * Emit the type name. Removed any prefixed warnings about ambiguity. |
| * The type maybe an array. |
| * |
| * @param type A Type object. |
| */ |
| public void emitType(com.sun.javadoc.Type type) { |
| String name = buildEmittableTypeString(type); |
| if (name == null) |
| return; |
| outputFile.print(name); |
| } |
| |
| /** |
| * Build the emittable type name. The type may be an array and/or |
| * a generic type. |
| * |
| * @param type A Type object |
| * @return The emittable type name |
| */ |
| private String buildEmittableTypeString(com.sun.javadoc.Type type) { |
| if (type == null) { |
| return null; |
| } |
| // type.toString() returns the fully qualified name of the type |
| // including the dimension and the parameters we just need to |
| // escape the generic parameters brackets so that the XML |
| // generated is correct |
| String name = type.toString().replaceAll("<", "<").replaceAll(">", ">"); |
| if (name.startsWith("<<ambiguous>>")) { |
| name = name.substring(13); |
| } |
| return name; |
| } |
| |
| /** |
| * Emit the XML header. |
| */ |
| public void emitXMLHeader() { |
| outputFile.println("<?xml version=\"1.0\" encoding=\"iso-8859-1\" standalone=\"no\"?>"); |
| outputFile.println("<!-- Generated by the JDiff Javadoc doclet -->"); |
| outputFile.println("<!-- (" + JDiff.jDiffLocation + ") -->"); |
| outputFile.println("<!-- on " + new Date() + " -->"); |
| outputFile.println(); |
| /* No need for this any longer, since doc block text is in an CDATA element |
| outputFile.println("<!-- XML Schema is used, but XHTML transitional DTD is needed for nbsp -->"); |
| outputFile.println("<!-- entity definitions etc.-->"); |
| outputFile.println("<!DOCTYPE api"); |
| outputFile.println(" PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\""); |
| outputFile.println(" \"" + baseURI + "/TR/xhtml1/DTD/xhtml1-transitional.dtd\">"); |
| */ |
| outputFile.println("<api"); |
| outputFile.println(" xmlns:xsi='" + baseURI + "/2001/XMLSchema-instance'"); |
| outputFile.println(" xsi:noNamespaceSchemaLocation='api.xsd'"); |
| outputFile.println(" name=\"" + apiIdentifier + "\""); |
| outputFile.println(" jdversion=\"" + JDiff.version + "\">"); |
| outputFile.println(); |
| } |
| |
| /** |
| * Emit the XML footer. |
| */ |
| public void emitXMLFooter() { |
| outputFile.println(); |
| outputFile.println("</api>"); |
| } |
| |
| /** |
| * Determine if the program element is shown, according to the given |
| * level of visibility. |
| * |
| * @param ped The given program element. |
| * @param visLevel The desired visibility level; "public", "protected", |
| * "package" or "private". If null, only check for an exclude tag. |
| * @return boolean Set if this element is shown. |
| */ |
| public boolean shownElement(Doc doc, String visLevel) { |
| // If a doc block contains @exclude or a similar such tag, |
| // then don't display it. |
| if (doExclude && excludeTag != null && doc != null) { |
| String rct = doc.getRawCommentText(); |
| if (rct != null && rct.indexOf(excludeTag) != -1) { |
| return false; |
| } |
| } |
| if (visLevel == null) { |
| return true; |
| } |
| ProgramElementDoc ped = null; |
| if (doc instanceof ProgramElementDoc) { |
| ped = (ProgramElementDoc)doc; |
| } |
| if (visLevel.compareTo("private") == 0) |
| return true; |
| // Show all that is not private |
| if (visLevel.compareTo("package") == 0) |
| return !ped.isPrivate(); |
| // Show all that is not private or package |
| if (visLevel.compareTo("protected") == 0) |
| return !(ped.isPrivate() || ped.isPackagePrivate()); |
| // Show all that is not private or package or protected, |
| // i.e. all that is public |
| if (visLevel.compareTo("public") == 0) |
| return ped.isPublic(); |
| return false; |
| } //shownElement() |
| |
| /** |
| * Strip out non-printing characters, replacing them with a character |
| * which will not change where the end of the first sentence is found. |
| * This character is the hash mark, '#'. |
| */ |
| public String stripNonPrintingChars(String s, Doc doc) { |
| if (!stripNonPrintables) |
| return s; |
| char[] sa = s.toCharArray(); |
| for (int i = 0; i < sa.length; i++) { |
| char c = sa[i]; |
| // TODO still have an issue with Unicode: 0xfc in java.lang.String.toUpperCase comments |
| // if (Character.isDefined(c)) |
| if (Character.isLetterOrDigit(c)) |
| continue; |
| // There must be a better way that is still platform independent! |
| if (c == ' ' || |
| c == '.' || |
| c == ',' || |
| c == '\r' || |
| c == '\t' || |
| c == '\n' || |
| c == '!' || |
| c == '?' || |
| c == ';' || |
| c == ':' || |
| c == '[' || |
| c == ']' || |
| c == '(' || |
| c == ')' || |
| c == '~' || |
| c == '@' || |
| c == '#' || |
| c == '$' || |
| c == '%' || |
| c == '^' || |
| c == '&' || |
| c == '*' || |
| c == '-' || |
| c == '=' || |
| c == '+' || |
| c == '_' || |
| c == '|' || |
| c == '\\' || |
| c == '/' || |
| c == '\'' || |
| c == '}' || |
| c == '{' || |
| c == '"' || |
| c == '<' || |
| c == '>' || |
| c == '`' |
| ) |
| continue; |
| /* Doesn't seem to return the expected values? |
| int val = Character.getNumericValue(c); |
| // if (s.indexOf("which is also a test for non-printable") != -1) |
| // System.out.println("** Char " + i + "[" + c + "], val =" + val); //DEBUG |
| // Ranges from http://www.unicode.org/unicode/reports/tr20/ |
| // Should really replace 0x2028 and 0x2029 with <br/> |
| if (val == 0x0 || |
| inRange(val, 0x2028, 0x2029) || |
| inRange(val, 0x202A, 0x202E) || |
| inRange(val, 0x206A, 0x206F) || |
| inRange(val, 0xFFF9, 0xFFFC) || |
| inRange(val, 0xE0000, 0xE007F)) { |
| if (trace) { |
| System.out.println("Warning: changed non-printing character " + sa[i] + " in " + doc.name()); |
| } |
| sa[i] = '#'; |
| } |
| */ |
| // Replace the non-printable character with a printable character |
| // which does not change the end of the first sentence |
| sa[i] = '#'; |
| } |
| return new String(sa); |
| } |
| |
| /** Return true if val is in the range [min|max], inclusive. */ |
| public boolean inRange(int val, int min, int max) { |
| if (val < min) |
| return false; |
| if (val > max) |
| return false; |
| return true; |
| } |
| |
| /** |
| * Add at least the first sentence from a doc block to the API. This is |
| * used by the report generator if no comment is provided. |
| * Need to make sure that HTML tags are not confused with XML tags. |
| * This could be done by stuffing the < character to another string |
| * or by handling HTML in the parser. This second option seems neater. Note that |
| * XML expects all element tags to have either a closing "/>" or a matching |
| * end element tag. Due to the difficulties of converting incorrect HTML |
| * to XHTML, the first option is used. |
| */ |
| public void addDocumentation(ProgramElementDoc ped, int indent) { |
| String rct = ((Doc)ped).getRawCommentText(); |
| if (rct != null) { |
| rct = stripNonPrintingChars(rct, (Doc)ped); |
| rct = rct.trim(); |
| if (rct.compareTo("") != 0 && |
| rct.indexOf(Comments.placeHolderText) == -1 && |
| rct.indexOf("InsertOtherCommentsHere") == -1) { |
| int idx = endOfFirstSentence(rct); |
| if (idx == 0) |
| return; |
| for (int i = 0; i < indent; i++) outputFile.print(" "); |
| outputFile.println("<doc>"); |
| for (int i = 0; i < indent; i++) outputFile.print(" "); |
| String firstSentence = null; |
| if (idx == -1) |
| firstSentence = rct; |
| else |
| firstSentence = rct.substring(0, idx+1); |
| boolean checkForAts = false; |
| if (checkForAts && firstSentence.indexOf("@") != -1 && |
| firstSentence.indexOf("@link") == -1) { |
| System.out.println("Warning: @ tag seen in comment: " + |
| firstSentence); |
| } |
| String firstSentenceNoTags = API.stuffHTMLTags(firstSentence); |
| outputFile.println(firstSentenceNoTags); |
| for (int i = 0; i < indent; i++) outputFile.print(" "); |
| outputFile.println("</doc>"); |
| } |
| } |
| } |
| |
| /** |
| * Add at least the first sentence from a doc block for a package to the API. This is |
| * used by the report generator if no comment is provided. |
| * The default source tree may not include the package.html files, so |
| * this may be unavailable in many cases. |
| * Need to make sure that HTML tags are not confused with XML tags. |
| * This could be done by stuffing the < character to another string |
| * or by handling HTML in the parser. This second option is neater. Note that |
| * XML expects all element tags to have either a closing "/>" or a matching |
| * end element tag. Due to the difficulties of converting incorrect HTML |
| * to XHTML, the first option is used. |
| */ |
| public void addPkgDocumentation(RootDoc root, PackageDoc pd, int indent) { |
| String rct = null; |
| String filename = pd.name(); |
| try { |
| // See if the source path was specified as part of the |
| // options and prepend it if it was. |
| String srcLocation = null; |
| String[][] options = root.options(); |
| for (int opt = 0; opt < options.length; opt++) { |
| if ((options[opt][0]).compareTo("-sourcepath") == 0) { |
| srcLocation = options[opt][1]; |
| break; |
| } |
| } |
| filename = filename.replace('.', JDiff.DIR_SEP.charAt(0)); |
| if (srcLocation != null) { |
| // Make a relative location absolute |
| if (srcLocation.startsWith("..")) { |
| String curDir = System.getProperty("user.dir"); |
| while (srcLocation.startsWith("..")) { |
| srcLocation = srcLocation.substring(3); |
| int idx = curDir.lastIndexOf(JDiff.DIR_SEP); |
| curDir = curDir.substring(0, idx+1); |
| } |
| srcLocation = curDir + srcLocation; |
| } |
| filename = srcLocation + JDiff.DIR_SEP + filename; |
| } |
| // Try both ".htm" and ".html" |
| filename += JDiff.DIR_SEP + "package.htm"; |
| File f2 = new File(filename); |
| if (!f2.exists()) { |
| filename += "l"; |
| } |
| FileInputStream f = new FileInputStream(filename); |
| BufferedReader d = new BufferedReader(new InputStreamReader(f)); |
| String str = d.readLine(); |
| // Ignore everything except the lines between <body> elements |
| boolean inBody = false; |
| while(str != null) { |
| if (!inBody) { |
| if (str.toLowerCase().trim().startsWith("<body")) { |
| inBody = true; |
| } |
| str = d.readLine(); // Get the next line |
| continue; // Ignore the line |
| } else { |
| if (str.toLowerCase().trim().startsWith("</body")) { |
| inBody = false; |
| continue; // Ignore the line |
| } |
| } |
| if (rct == null) |
| rct = str + "\n"; |
| else |
| rct += str + "\n"; |
| str = d.readLine(); |
| } |
| } catch(java.io.FileNotFoundException e) { |
| // If it doesn't exist, that's fine |
| if (trace) |
| System.out.println("No package level documentation file at '" + filename + "'"); |
| } catch(java.io.IOException e) { |
| System.out.println("Error reading file \"" + filename + "\": " + e.getMessage()); |
| System.exit(5); |
| } |
| if (rct != null) { |
| rct = stripNonPrintingChars(rct, (Doc)pd); |
| rct = rct.trim(); |
| if (rct.compareTo("") != 0 && |
| rct.indexOf(Comments.placeHolderText) == -1 && |
| rct.indexOf("InsertOtherCommentsHere") == -1) { |
| int idx = endOfFirstSentence(rct); |
| if (idx == 0) |
| return; |
| for (int i = 0; i < indent; i++) outputFile.print(" "); |
| outputFile.println("<doc>"); |
| for (int i = 0; i < indent; i++) outputFile.print(" "); |
| String firstSentence = null; |
| if (idx == -1) |
| firstSentence = rct; |
| else |
| firstSentence = rct.substring(0, idx+1); |
| String firstSentenceNoTags = API.stuffHTMLTags(firstSentence); |
| outputFile.println(firstSentenceNoTags); |
| for (int i = 0; i < indent; i++) outputFile.print(" "); |
| outputFile.println("</doc>"); |
| } |
| } |
| } |
| |
| /** |
| * Find the index of the end of the first sentence in the given text, |
| * when writing out to an XML file. |
| * This is an extended version of the algorithm used by the DocCheck |
| * Javadoc doclet. It checks for @tags too. |
| * |
| * @param text The text to be searched. |
| * @return The index of the end of the first sentence. If there is no |
| * end, return -1. If there is no useful text, return 0. |
| * If the whole doc block comment is wanted (default), return -1. |
| */ |
| public static int endOfFirstSentence(String text) { |
| return endOfFirstSentence(text, true); |
| } |
| |
| /** |
| * Find the index of the end of the first sentence in the given text. |
| * This is an extended version of the algorithm used by the DocCheck |
| * Javadoc doclet. It checks for @tags too. |
| * |
| * @param text The text to be searched. |
| * @param writingToXML Set to true when writing out XML. |
| * @return The index of the end of the first sentence. If there is no |
| * end, return -1. If there is no useful text, return 0. |
| * If the whole doc block comment is wanted (default), return -1. |
| */ |
| public static int endOfFirstSentence(String text, boolean writingToXML) { |
| if (saveAllDocs && writingToXML) |
| return -1; |
| int textLen = text.length(); |
| if (textLen == 0) |
| return 0; |
| int index = -1; |
| // Handle some special cases |
| int fromindex = 0; |
| int ellipsis = text.indexOf(". . ."); // Handles one instance of this |
| if (ellipsis != -1) |
| fromindex = ellipsis + 5; |
| // If the first non-whitespace character is an @, go beyond it |
| int i = 0; |
| while (i < textLen && text.charAt(i) == ' ') { |
| i++; |
| } |
| if (text.charAt(i) == '@' && fromindex < textLen-1) |
| fromindex = i + 1; |
| // Use the brute force approach. |
| index = minIndex(index, text.indexOf("? ", fromindex)); |
| index = minIndex(index, text.indexOf("?\t", fromindex)); |
| index = minIndex(index, text.indexOf("?\n", fromindex)); |
| index = minIndex(index, text.indexOf("?\r", fromindex)); |
| index = minIndex(index, text.indexOf("?\f", fromindex)); |
| index = minIndex(index, text.indexOf("! ", fromindex)); |
| index = minIndex(index, text.indexOf("!\t", fromindex)); |
| index = minIndex(index, text.indexOf("!\n", fromindex)); |
| index = minIndex(index, text.indexOf("!\r", fromindex)); |
| index = minIndex(index, text.indexOf("!\f", fromindex)); |
| index = minIndex(index, text.indexOf(". ", fromindex)); |
| index = minIndex(index, text.indexOf(".\t", fromindex)); |
| index = minIndex(index, text.indexOf(".\n", fromindex)); |
| index = minIndex(index, text.indexOf(".\r", fromindex)); |
| index = minIndex(index, text.indexOf(".\f", fromindex)); |
| index = minIndex(index, text.indexOf("@param", fromindex)); |
| index = minIndex(index, text.indexOf("@return", fromindex)); |
| index = minIndex(index, text.indexOf("@throw", fromindex)); |
| index = minIndex(index, text.indexOf("@serial", fromindex)); |
| index = minIndex(index, text.indexOf("@exception", fromindex)); |
| index = minIndex(index, text.indexOf("@deprecate", fromindex)); |
| index = minIndex(index, text.indexOf("@author", fromindex)); |
| index = minIndex(index, text.indexOf("@since", fromindex)); |
| index = minIndex(index, text.indexOf("@see", fromindex)); |
| index = minIndex(index, text.indexOf("@version", fromindex)); |
| if (doExclude && excludeTag != null) |
| index = minIndex(index, text.indexOf(excludeTag)); |
| index = minIndex(index, text.indexOf("@vtexclude", fromindex)); |
| index = minIndex(index, text.indexOf("@vtinclude", fromindex)); |
| index = minIndex(index, text.indexOf("<p>", 2)); // Not at start |
| index = minIndex(index, text.indexOf("<P>", 2)); // Not at start |
| index = minIndex(index, text.indexOf("<blockquote", 2)); // Not at start |
| index = minIndex(index, text.indexOf("<pre", fromindex)); // May contain anything! |
| // Avoid the char at the start of a tag in some cases |
| if (index != -1 && |
| (text.charAt(index) == '@' || text.charAt(index) == '<')) { |
| if (index != 0) |
| index--; |
| } |
| |
| /* Not used for jdiff, since tags are explicitly checked for above. |
| // Look for a sentence terminated by an HTML tag. |
| index = minIndex(index, text.indexOf(".<", fromindex)); |
| if (index == -1) { |
| // If period-whitespace etc was not found, check to see if |
| // last character is a period, |
| int endIndex = text.length()-1; |
| if (text.charAt(endIndex) == '.' || |
| text.charAt(endIndex) == '?' || |
| text.charAt(endIndex) == '!') |
| index = endIndex; |
| } |
| */ |
| return index; |
| } |
| |
| /** |
| * Return the minimum of two indexes if > -1, and return -1 |
| * only if both indexes = -1. |
| * @param i an int index |
| * @param j an int index |
| * @return an int equal to the minimum index > -1, or -1 |
| */ |
| public static int minIndex(int i, int j) { |
| if (i == -1) return j; |
| if (j == -1) return i; |
| return Math.min(i,j); |
| } |
| |
| /** |
| * The name of the file where the XML representing the API will be |
| * stored. |
| */ |
| public static String outputFileName = null; |
| |
| /** |
| * The identifier of the API being written out in XML, e.g. |
| * "SuperProduct 1.3". |
| */ |
| public static String apiIdentifier = null; |
| |
| /** |
| * The file where the XML representing the API will be stored. |
| */ |
| private static PrintWriter outputFile = null; |
| |
| /** |
| * The name of the directory where the XML representing the API will be |
| * stored. |
| */ |
| public static String outputDirectory = null; |
| |
| /** |
| * Do not display a class with a lower level of visibility than this. |
| * Default is to display all public and protected classes. |
| */ |
| public static String classVisibilityLevel = "protected"; |
| |
| /** |
| * Do not display a member with a lower level of visibility than this. |
| * Default is to display all public and protected members |
| * (constructors, methods, fields). |
| */ |
| public static String memberVisibilityLevel = "protected"; |
| |
| /** |
| * If set, then save the entire contents of a doc block comment in the |
| * API file. If not set, then just save the first sentence. Default is |
| * that this is set. |
| */ |
| public static boolean saveAllDocs = true; |
| |
| /** |
| * If set, exclude program elements marked with whatever the exclude tag |
| * is specified as, e.g. "@exclude". |
| */ |
| public static boolean doExclude = false; |
| |
| /** |
| * Exclude program elements marked with this String, e.g. "@exclude". |
| */ |
| public static String excludeTag = null; |
| |
| /** |
| * The base URI for locating necessary DTDs and Schemas. By default, this |
| * is "http://www.w3.org". A typical value to use local copies of DTD files |
| * might be "file:///C:/jdiff/lib" |
| */ |
| public static String baseURI = "http://www.w3.org"; |
| |
| /** |
| * If set, then strip out non-printing characters from documentation. |
| * Default is that this is set. |
| */ |
| static boolean stripNonPrintables = true; |
| |
| /** |
| * If set, then add the information about the source file and line number |
| * which is available in J2SE1.4. Default is that this is not set. |
| */ |
| static boolean addSrcInfo = false; |
| |
| /** |
| * If set, scan classes with no packages. |
| * If the source is a jar file this may duplicates classes, so |
| * disable it using the -packagesonly option. Default is that this is |
| * not set. |
| */ |
| static boolean packagesOnly = false; |
| |
| /** Set to enable increased logging verbosity for debugging. */ |
| private static boolean trace = false; |
| |
| } //RootDocToXML |
