AbstractDoclet.java revision 2571:10fc81ac75b4
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 26package com.sun.tools.doclets.internal.toolkit; 27 28import com.sun.javadoc.*; 29import com.sun.tools.doclets.internal.toolkit.builders.*; 30import 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 */ 42public 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(AbstractDoclet doclet) { 64 if (! doclet.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 doclet the doclet to start the execution for. 76 * @param root the {@link RootDoc} that points to the source to document. 77 * @return true if the doclet executed without error. False otherwise. 78 */ 79 public boolean start(AbstractDoclet doclet, RootDoc root) { 80 configuration = configuration(); 81 configuration.root = root; 82 utils = configuration.utils; 83 if (! isValidDoclet(doclet)) { 84 return false; 85 } 86 try { 87 doclet.startGeneration(root); 88 } catch (Configuration.Fault f) { 89 root.printError(f.getMessage()); 90 return false; 91 } catch (DocletAbortException e) { 92 Throwable cause = e.getCause(); 93 if (cause != null) { 94 if (cause.getLocalizedMessage() != null) { 95 root.printError(cause.getLocalizedMessage()); 96 } else { 97 root.printError(cause.toString()); 98 } 99 } 100 return false; 101 } catch (Exception exc) { 102 return false; 103 } 104 return true; 105 } 106 107 /** 108 * Indicate that this doclet supports the 1.5 language features. 109 * @return JAVA_1_5, indicating that the new features are supported. 110 */ 111 public static LanguageVersion languageVersion() { 112 return LanguageVersion.JAVA_1_5; 113 } 114 115 116 /** 117 * Create the configuration instance and returns it. 118 * @return the configuration of the doclet. 119 */ 120 public abstract Configuration configuration(); 121 122 /** 123 * Start the generation of files. Call generate methods in the individual 124 * writers, which will in turn generate the documentation files. Call the 125 * TreeWriter generation first to ensure the Class Hierarchy is built 126 * first and then can be used in the later generation. 127 * 128 * @see com.sun.javadoc.RootDoc 129 */ 130 private void startGeneration(RootDoc root) throws Configuration.Fault, Exception { 131 if (root.classes().length == 0) { 132 configuration.message. 133 error("doclet.No_Public_Classes_To_Document"); 134 return; 135 } 136 configuration.setOptions(); 137 configuration.getDocletSpecificMsg().notice("doclet.build_version", 138 configuration.getDocletSpecificBuildDate()); 139 ClassTree classtree = new ClassTree(configuration, configuration.nodeprecated); 140 141 generateClassFiles(root, classtree); 142 configuration.utils.copyDocFiles(configuration, DocPaths.DOC_FILES); 143 144 PackageListWriter.generate(configuration); 145 generatePackageFiles(classtree); 146 generateProfileFiles(); 147 148 generateOtherFiles(root, classtree); 149 configuration.tagletManager.printReport(); 150 } 151 152 /** 153 * Generate additional documentation that is added to the API documentation. 154 * 155 * @param root the RootDoc of source to document. 156 * @param classtree the data structure representing the class tree. 157 */ 158 protected void generateOtherFiles(RootDoc root, ClassTree classtree) throws Exception { 159 BuilderFactory builderFactory = configuration.getBuilderFactory(); 160 AbstractBuilder constantsSummaryBuilder = builderFactory.getConstantsSummaryBuider(); 161 constantsSummaryBuilder.build(); 162 AbstractBuilder serializedFormBuilder = builderFactory.getSerializedFormBuilder(); 163 serializedFormBuilder.build(); 164 } 165 166 /** 167 * Generate the profile documentation. 168 * 169 */ 170 protected abstract void generateProfileFiles() throws Exception; 171 172 /** 173 * Generate the package documentation. 174 * 175 * @param classtree the data structure representing the class tree. 176 */ 177 protected abstract void generatePackageFiles(ClassTree classtree) throws Exception; 178 179 /** 180 * Generate the class documentation. 181 * 182 * @param classtree the data structure representing the class tree. 183 */ 184 protected abstract void generateClassFiles(ClassDoc[] arr, ClassTree classtree); 185 186 /** 187 * Iterate through all classes and construct documentation for them. 188 * 189 * @param root the RootDoc of source to document. 190 * @param classtree the data structure representing the class tree. 191 */ 192 protected void generateClassFiles(RootDoc root, ClassTree classtree) { 193 generateClassFiles(classtree); 194 PackageDoc[] packages = root.specifiedPackages(); 195 for (PackageDoc pkg : packages) { 196 generateClassFiles(pkg.allClasses(), classtree); 197 } 198 } 199 200 /** 201 * Generate the class files for single classes specified on the command line. 202 * 203 * @param classtree the data structure representing the class tree. 204 */ 205 private void generateClassFiles(ClassTree classtree) { 206 String[] packageNames = configuration.classDocCatalog.packageNames(); 207 for (String packageName : packageNames) { 208 generateClassFiles(configuration.classDocCatalog.allClasses( 209 packageName), classtree); 210 } 211 } 212} 213