1 /* 2 * Copyright (c) 2003, 2014, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package com.sun.tools.doclets.internal.toolkit; 27 28 import com.sun.javadoc.*; 29 import com.sun.tools.doclets.internal.toolkit.builders.*; 30 import com.sun.tools.doclets.internal.toolkit.util.*; 31 32 /** 33 * An abstract implementation of a Doclet. 34 * 35 * <p><b>This is NOT part of any supported API. 36 * If you write code that depends on this, you do so at your own risk. 37 * This code and its internal interfaces are subject to change or 38 * deletion without notice.</b> 39 * 40 * @author Jamie Ho 41 */ 42 public abstract class AbstractDoclet { 43 44 /** 45 * The global configuration information for this run. 46 */ 47 public Configuration configuration; 48 /* 49 * a handle to our utility methods 50 */ 51 protected Utils utils; 52 53 /** 54 * The only doclet that may use this toolkit is {@value} 55 */ 56 private static final String TOOLKIT_DOCLET_NAME = 57 com.sun.tools.doclets.formats.html.HtmlDoclet.class.getName(); 58 59 /** 60 * Verify that the only doclet that is using this toolkit is 61 * {@value #TOOLKIT_DOCLET_NAME}. 62 */ 63 private boolean isValidDoclet() { 64 if (!getClass().getName().equals(TOOLKIT_DOCLET_NAME)) { 65 configuration.message.error("doclet.Toolkit_Usage_Violation", 66 TOOLKIT_DOCLET_NAME); 67 return false; 68 } 69 return true; 70 } 71 72 /** 73 * The method that starts the execution of the doclet. 74 * 75 * @param root the {@link RootDoc} that points to the source to document. 76 * @return true if the doclet executed without error. False otherwise. 77 */ 78 public boolean startDoclet(RootDoc root) { 79 configuration = configuration(); 80 configuration.root = root; 81 utils = configuration.utils; 82 if (!isValidDoclet()) { 83 return false; 84 } 85 try { 86 startGeneration(root); 87 } catch (Configuration.Fault f) { 88 root.printError(f.getMessage()); 89 return false; 90 } catch (DocletAbortException e) { 91 Throwable cause = e.getCause(); 92 if (cause != null) { 93 if (cause.getLocalizedMessage() != null) { 94 root.printError(cause.getLocalizedMessage()); 95 } else { 96 root.printError(cause.toString()); 97 } 98 } 99 return false; 100 } catch (Exception exc) { 101 return false; 102 } 103 return true; 104 } 105 106 /** 107 * Indicate that this doclet supports the 1.5 language features. 108 * @return JAVA_1_5, indicating that the new features are supported. 109 */ 110 public static LanguageVersion languageVersion() { 111 return LanguageVersion.JAVA_1_5; 112 } 113 114 115 /** 116 * Create the configuration instance and returns it. 117 * @return the configuration of the doclet. 118 */ 119 public abstract Configuration configuration(); 120 121 /** 122 * Start the generation of files. Call generate methods in the individual 123 * writers, which will in turn generate the documentation files. Call the 124 * TreeWriter generation first to ensure the Class Hierarchy is built 125 * first and then can be used in the later generation. 126 * 127 * @see com.sun.javadoc.RootDoc 128 */ 129 private void startGeneration(RootDoc root) throws Configuration.Fault, Exception { 130 if (root.classes().length == 0) { 131 configuration.message. 132 error("doclet.No_Public_Classes_To_Document"); 133 return; 134 } 135 configuration.setOptions(); 136 configuration.getDocletSpecificMsg().notice("doclet.build_version", 137 configuration.getDocletSpecificBuildDate()); 138 ClassTree classtree = new ClassTree(configuration, configuration.nodeprecated); 139 140 generateClassFiles(root, classtree); 141 configuration.utils.copyDocFiles(configuration, DocPaths.DOC_FILES); 142 143 PackageListWriter.generate(configuration); 144 generatePackageFiles(classtree); 145 generateProfileFiles(); 146 147 generateOtherFiles(root, classtree); 148 configuration.tagletManager.printReport(); 149 } 150 151 /** 152 * Generate additional documentation that is added to the API documentation. 153 * 154 * @param root the RootDoc of source to document. 155 * @param classtree the data structure representing the class tree. 156 */ 157 protected void generateOtherFiles(RootDoc root, ClassTree classtree) throws Exception { 158 BuilderFactory builderFactory = configuration.getBuilderFactory(); 159 AbstractBuilder constantsSummaryBuilder = builderFactory.getConstantsSummaryBuider(); 160 constantsSummaryBuilder.build(); 161 AbstractBuilder serializedFormBuilder = builderFactory.getSerializedFormBuilder(); 162 serializedFormBuilder.build(); 163 } 164 165 /** 166 * Generate the profile documentation. 167 * 168 */ 169 protected abstract void generateProfileFiles() throws Exception; 170 171 /** 172 * Generate the package documentation. 173 * 174 * @param classtree the data structure representing the class tree. 175 */ 176 protected abstract void generatePackageFiles(ClassTree classtree) throws Exception; 177 178 /** 179 * Generate the class documentation. 180 * 181 * @param classtree the data structure representing the class tree. 182 */ 183 protected abstract void generateClassFiles(ClassDoc[] arr, ClassTree classtree); 184 185 /** 186 * Iterate through all classes and construct documentation for them. 187 * 188 * @param root the RootDoc of source to document. 189 * @param classtree the data structure representing the class tree. 190 */ 191 protected void generateClassFiles(RootDoc root, ClassTree classtree) { 192 generateClassFiles(classtree); 193 PackageDoc[] packages = root.specifiedPackages(); 194 for (PackageDoc pkg : packages) { 195 generateClassFiles(pkg.allClasses(), classtree); 196 } 197 } 198 199 /** 200 * Generate the class files for single classes specified on the command line. 201 * 202 * @param classtree the data structure representing the class tree. 203 */ 204 private void generateClassFiles(ClassTree classtree) { 205 String[] packageNames = configuration.classDocCatalog.packageNames(); 206 for (String packageName : packageNames) { 207 generateClassFiles(configuration.classDocCatalog.allClasses( 208 packageName), classtree); 209 } 210 } 211 } | 1 /* 2 * Copyright (c) 2003, 2016, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package jdk.javadoc.internal.doclets.toolkit; 27 28 import java.util.SortedSet; 29 import java.util.TreeSet; 30 31 import javax.lang.model.SourceVersion; 32 import javax.lang.model.element.PackageElement; 33 import javax.lang.model.element.TypeElement; 34 35 import jdk.javadoc.doclet.DocletEnvironment; 36 import jdk.javadoc.internal.doclets.toolkit.builders.AbstractBuilder; 37 import jdk.javadoc.internal.doclets.toolkit.builders.BuilderFactory; 38 import jdk.javadoc.internal.doclets.toolkit.util.ClassTree; 39 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; 40 import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; 41 import jdk.javadoc.internal.doclets.toolkit.util.PackageListWriter; 42 import jdk.javadoc.internal.doclets.toolkit.util.Utils; 43 44 import static javax.tools.Diagnostic.Kind.*; 45 46 /** 47 * An abstract implementation of a Doclet. 48 * 49 * <p><b>This is NOT part of any supported API. 50 * If you write code that depends on this, you do so at your own risk. 51 * This code and its internal interfaces are subject to change or 52 * deletion without notice.</b> 53 * 54 * @author Jamie Ho 55 */ 56 public abstract class AbstractDoclet { 57 58 /** 59 * The global configuration information for this run. 60 */ 61 public Configuration configuration; 62 /* 63 * a handle to our utility methods 64 */ 65 protected Utils utils; 66 67 /** 68 * The only doclet that may use this toolkit is {@value} 69 */ 70 private static final String TOOLKIT_DOCLET_NAME = 71 jdk.javadoc.internal.doclets.formats.html.HtmlDoclet.class.getName(); 72 73 /** 74 * Verify that the only doclet that is using this toolkit is 75 * {@value #TOOLKIT_DOCLET_NAME}. 76 */ 77 private boolean isValidDoclet() { 78 if (!getClass().getName().equals(TOOLKIT_DOCLET_NAME)) { 79 configuration.message.error("doclet.Toolkit_Usage_Violation", 80 TOOLKIT_DOCLET_NAME); 81 return false; 82 } 83 return true; 84 } 85 86 /** 87 * The method that starts the execution of the doclet. 88 * 89 * @param root the {@link DocletEnvironment} that points to the source to document. 90 * @return true if the doclet executed without error. False otherwise. 91 */ 92 public boolean startDoclet(DocletEnvironment root) { 93 configuration = configuration(); 94 configuration.root = root; 95 configuration.cmtutils = new CommentUtils(configuration); 96 configuration.utils = new Utils(configuration); 97 utils = configuration.utils; 98 configuration.workArounds = new WorkArounds(configuration); 99 if (!isValidDoclet()) { 100 return false; 101 } 102 103 try { 104 startGeneration(root); 105 } catch (Configuration.Fault f) { 106 configuration.reporter.print(ERROR, f.getMessage()); 107 return false; 108 } catch (DocletAbortException e) { 109 Throwable cause = e.getCause(); 110 // e.printStackTrace(); 111 if (cause != null) { 112 if (cause.getLocalizedMessage() != null) { 113 configuration.reporter.print(ERROR, cause.getLocalizedMessage()); 114 } else { 115 configuration.reporter.print(ERROR, cause.toString()); 116 } 117 } 118 return false; 119 } catch (Exception exc) { 120 return false; 121 } 122 return true; 123 } 124 125 /** 126 * Returns the SourceVersion indicating the features supported by this doclet. 127 * @return SourceVersion 128 */ 129 public SourceVersion sourceVersion() { 130 return SourceVersion.RELEASE_8; 131 } 132 133 134 /** 135 * Create the configuration instance and returns it. 136 * @return the configuration of the doclet. 137 */ 138 public abstract Configuration configuration(); 139 140 /** 141 * Start the generation of files. Call generate methods in the individual 142 * writers, which will in turn generate the documentation files. Call the 143 * TreeWriter generation first to ensure the Class Hierarchy is built 144 * first and then can be used in the later generation. 145 * 146 * @see jdk.doclet.DocletEnvironment 147 */ 148 private void startGeneration(DocletEnvironment root) throws Configuration.Fault, Exception { 149 if (root.getIncludedClasses().isEmpty()) { 150 configuration.message. 151 error("doclet.No_Public_Classes_To_Document"); 152 return; 153 } 154 if (!configuration.setOptions()) { 155 return; 156 } 157 configuration.getDocletSpecificMsg().notice("doclet.build_version", 158 configuration.getDocletSpecificBuildDate()); 159 ClassTree classtree = new ClassTree(configuration, configuration.nodeprecated); 160 161 generateClassFiles(root, classtree); 162 configuration.utils.copyDocFiles(DocPaths.DOC_FILES); 163 164 PackageListWriter.generate(configuration); 165 generatePackageFiles(classtree); 166 167 generateOtherFiles(root, classtree); 168 configuration.tagletManager.printReport(); 169 } 170 171 /** 172 * Generate additional documentation that is added to the API documentation. 173 * 174 * @param root the DocletEnvironment of source to document. 175 * @param classtree the data structure representing the class tree. 176 */ 177 protected void generateOtherFiles(DocletEnvironment root, ClassTree classtree) throws Exception { 178 BuilderFactory builderFactory = configuration.getBuilderFactory(); 179 AbstractBuilder constantsSummaryBuilder = builderFactory.getConstantsSummaryBuilder(); 180 constantsSummaryBuilder.build(); 181 AbstractBuilder serializedFormBuilder = builderFactory.getSerializedFormBuilder(); 182 serializedFormBuilder.build(); 183 } 184 185 /** 186 * Generate the package documentation. 187 * 188 * @param classtree the data structure representing the class tree. 189 */ 190 protected abstract void generatePackageFiles(ClassTree classtree) throws Exception; 191 192 /** 193 * Generate the class documentation. 194 * 195 * @param classtree the data structure representing the class tree. 196 */ 197 protected abstract void generateClassFiles(SortedSet<TypeElement> arr, ClassTree classtree); 198 199 /** 200 * Iterate through all classes and construct documentation for them. 201 * 202 * @param root the DocletEnvironment of source to document. 203 * @param classtree the data structure representing the class tree. 204 */ 205 protected void generateClassFiles(DocletEnvironment root, ClassTree classtree) { 206 generateClassFiles(classtree); 207 SortedSet<PackageElement> packages = new TreeSet<>(utils.makePackageComparator()); 208 packages.addAll(utils.getSpecifiedPackages()); 209 packages.stream().forEach((pkg) -> { 210 generateClassFiles(utils.getAllClasses(pkg), classtree); 211 }); 212 } 213 214 /** 215 * Generate the class files for single classes specified on the command line. 216 * 217 * @param classtree the data structure representing the class tree. 218 */ 219 private void generateClassFiles(ClassTree classtree) { 220 SortedSet<PackageElement> packages = configuration.classDocCatalog.packages(); 221 packages.stream().forEach((pkg) -> { 222 generateClassFiles(configuration.classDocCatalog.allClasses(pkg), classtree); 223 }); 224 } 225 } |