1 /* 2 * Copyright (c) 2003, 2013, 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 /** 50 * The only doclet that may use this toolkit is {@value} 51 */ 52 private static final String TOOLKIT_DOCLET_NAME = 53 com.sun.tools.doclets.formats.html.HtmlDoclet.class.getName(); 54 55 /** 56 * Verify that the only doclet that is using this toolkit is 57 * {@value #TOOLKIT_DOCLET_NAME}. 58 */ 59 private boolean isValidDoclet(AbstractDoclet doclet) { 60 if (! doclet.getClass().getName().equals(TOOLKIT_DOCLET_NAME)) { 61 configuration.message.error("doclet.Toolkit_Usage_Violation", 62 TOOLKIT_DOCLET_NAME); 63 return false; 64 } 65 return true; 66 } 67 68 /** 69 * The method that starts the execution of the doclet. 70 * 71 * @param doclet the doclet to start the execution for. 72 * @param root the {@link RootDoc} that points to the source to document. 73 * @return true if the doclet executed without error. False otherwise. 74 */ 75 public boolean start(AbstractDoclet doclet, RootDoc root) { 76 configuration = configuration(); 77 configuration.root = root; 78 if (! isValidDoclet(doclet)) { 79 return false; 80 } 81 try { 82 doclet.startGeneration(root); 83 } catch (Exception exc) { 84 exc.printStackTrace(); 85 return false; 86 } 87 return true; 88 } 89 90 /** 91 * Indicate that this doclet supports the 1.5 language features. 92 * @return JAVA_1_5, indicating that the new features are supported. 93 */ 94 public static LanguageVersion languageVersion() { 95 return LanguageVersion.JAVA_1_5; 96 } 97 98 99 /** 100 * Create the configuration instance and returns it. 101 * @return the configuration of the doclet. 102 */ 103 public abstract Configuration configuration(); 104 105 /** 106 * Start the generation of files. Call generate methods in the individual 107 * writers, which will in turn generate the documentation files. Call the 108 * TreeWriter generation first to ensure the Class Hierarchy is built 109 * first and then can be used in the later generation. 110 * 111 * @see com.sun.javadoc.RootDoc 112 */ 113 private void startGeneration(RootDoc root) throws Exception { 114 if (root.classes().length == 0) { 115 configuration.message. 116 error("doclet.No_Public_Classes_To_Document"); 117 return; 118 } 119 configuration.setOptions(); 120 configuration.getDocletSpecificMsg().notice("doclet.build_version", 121 configuration.getDocletSpecificBuildDate()); 122 ClassTree classtree = new ClassTree(configuration, configuration.nodeprecated); 123 124 generateClassFiles(root, classtree); 125 Util.copyDocFiles(configuration, DocPaths.DOC_FILES); 126 127 PackageListWriter.generate(configuration); 128 generatePackageFiles(classtree); 129 generateProfileFiles(); 130 131 generateOtherFiles(root, classtree); 132 configuration.tagletManager.printReport(); 133 } 134 135 /** 136 * Generate additional documentation that is added to the API documentation. 137 * 138 * @param root the RootDoc of source to document. 139 * @param classtree the data structure representing the class tree. 140 */ 141 protected void generateOtherFiles(RootDoc root, ClassTree classtree) throws Exception { 142 BuilderFactory builderFactory = configuration.getBuilderFactory(); 143 AbstractBuilder constantsSummaryBuilder = builderFactory.getConstantsSummaryBuider(); 144 constantsSummaryBuilder.build(); 145 AbstractBuilder serializedFormBuilder = builderFactory.getSerializedFormBuilder(); 146 serializedFormBuilder.build(); 147 } 148 149 /** 150 * Generate the profile documentation. 151 * 152 */ 153 protected abstract void generateProfileFiles() throws Exception; 154 155 /** 156 * Generate the package documentation. 157 * 158 * @param classtree the data structure representing the class tree. 159 */ 160 protected abstract void generatePackageFiles(ClassTree classtree) throws Exception; 161 162 /** 163 * Generate the class documentation. 164 * 165 * @param classtree the data structure representing the class tree. 166 */ 167 protected abstract void generateClassFiles(ClassDoc[] arr, ClassTree classtree); 168 169 /** 170 * Iterate through all classes and construct documentation for them. 171 * 172 * @param root the RootDoc of source to document. 173 * @param classtree the data structure representing the class tree. 174 */ 175 protected void generateClassFiles(RootDoc root, ClassTree classtree) { 176 generateClassFiles(classtree); 177 PackageDoc[] packages = root.specifiedPackages(); 178 for (int i = 0; i < packages.length; i++) { 179 generateClassFiles(packages[i].allClasses(), classtree); 180 } 181 } 182 183 /** 184 * Generate the class files for single classes specified on the command line. 185 * 186 * @param classtree the data structure representing the class tree. 187 */ 188 private void generateClassFiles(ClassTree classtree) { 189 String[] packageNames = configuration.classDocCatalog.packageNames(); 190 for (int packageNameIndex = 0; packageNameIndex < packageNames.length; 191 packageNameIndex++) { 192 generateClassFiles(configuration.classDocCatalog.allClasses( 193 packageNames[packageNameIndex]), classtree); 194 } 195 } 196 }