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