duke@1: /* bpatel@1568: * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. duke@1: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. duke@1: * duke@1: * This code is free software; you can redistribute it and/or modify it duke@1: * under the terms of the GNU General Public License version 2 only, as ohair@554: * published by the Free Software Foundation. Oracle designates this duke@1: * particular file as subject to the "Classpath" exception as provided ohair@554: * by Oracle in the LICENSE file that accompanied this code. duke@1: * duke@1: * This code is distributed in the hope that it will be useful, but WITHOUT duke@1: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or duke@1: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License duke@1: * version 2 for more details (a copy is included in the LICENSE file that duke@1: * accompanied this code). duke@1: * duke@1: * You should have received a copy of the GNU General Public License version duke@1: * 2 along with this work; if not, write to the Free Software Foundation, duke@1: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. duke@1: * ohair@554: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA ohair@554: * or visit www.oracle.com if you need additional information or have any ohair@554: * questions. duke@1: */ duke@1: duke@1: package com.sun.tools.doclets.internal.toolkit; duke@1: jjg@1357: import com.sun.javadoc.*; duke@1: import com.sun.tools.doclets.internal.toolkit.builders.*; duke@1: import com.sun.tools.doclets.internal.toolkit.util.*; duke@1: duke@1: /** duke@1: * An abstract implementation of a Doclet. duke@1: * jjg@1359: *

This is NOT part of any supported API. jjg@1359: * If you write code that depends on this, you do so at your own risk. jjg@1359: * This code and its internal interfaces are subject to change or jjg@1359: * deletion without notice. duke@1: * duke@1: * @author Jamie Ho duke@1: */ duke@1: public abstract class AbstractDoclet { duke@1: duke@1: /** duke@1: * The global configuration information for this run. duke@1: */ jjg@140: public Configuration configuration; duke@1: duke@1: /** duke@1: * The only doclet that may use this toolkit is {@value} duke@1: */ jjg@1410: private static final String TOOLKIT_DOCLET_NAME = jjg@1410: com.sun.tools.doclets.formats.html.HtmlDoclet.class.getName(); duke@1: duke@1: /** duke@1: * Verify that the only doclet that is using this toolkit is duke@1: * {@value #TOOLKIT_DOCLET_NAME}. duke@1: */ duke@1: private boolean isValidDoclet(AbstractDoclet doclet) { duke@1: if (! doclet.getClass().getName().equals(TOOLKIT_DOCLET_NAME)) { duke@1: configuration.message.error("doclet.Toolkit_Usage_Violation", duke@1: TOOLKIT_DOCLET_NAME); duke@1: return false; duke@1: } duke@1: return true; duke@1: } duke@1: duke@1: /** duke@1: * The method that starts the execution of the doclet. duke@1: * duke@1: * @param doclet the doclet to start the execution for. duke@1: * @param root the {@link RootDoc} that points to the source to document. duke@1: * @return true if the doclet executed without error. False otherwise. duke@1: */ duke@1: public boolean start(AbstractDoclet doclet, RootDoc root) { jjg@140: configuration = configuration(); duke@1: configuration.root = root; duke@1: if (! isValidDoclet(doclet)) { duke@1: return false; duke@1: } duke@1: try { duke@1: doclet.startGeneration(root); jjg@1611: } catch (Configuration.Fault f) { jjg@1611: root.printError(f.getMessage()); jjg@1611: return false; duke@1: } catch (Exception exc) { duke@1: exc.printStackTrace(); duke@1: return false; duke@1: } duke@1: return true; duke@1: } duke@1: duke@1: /** duke@1: * Indicate that this doclet supports the 1.5 language features. duke@1: * @return JAVA_1_5, indicating that the new features are supported. duke@1: */ duke@1: public static LanguageVersion languageVersion() { duke@1: return LanguageVersion.JAVA_1_5; duke@1: } duke@1: duke@1: duke@1: /** duke@1: * Create the configuration instance and returns it. duke@1: * @return the configuration of the doclet. duke@1: */ duke@1: public abstract Configuration configuration(); duke@1: duke@1: /** duke@1: * Start the generation of files. Call generate methods in the individual jjg@1383: * writers, which will in turn generate the documentation files. Call the duke@1: * TreeWriter generation first to ensure the Class Hierarchy is built duke@1: * first and then can be used in the later generation. duke@1: * duke@1: * @see com.sun.javadoc.RootDoc duke@1: */ jjg@1611: private void startGeneration(RootDoc root) throws Configuration.Fault, Exception { duke@1: if (root.classes().length == 0) { duke@1: configuration.message. duke@1: error("doclet.No_Public_Classes_To_Document"); duke@1: return; duke@1: } duke@1: configuration.setOptions(); duke@1: configuration.getDocletSpecificMsg().notice("doclet.build_version", duke@1: configuration.getDocletSpecificBuildDate()); duke@1: ClassTree classtree = new ClassTree(configuration, configuration.nodeprecated); duke@1: duke@1: generateClassFiles(root, classtree); jjg@1383: Util.copyDocFiles(configuration, DocPaths.DOC_FILES); duke@1: duke@1: PackageListWriter.generate(configuration); duke@1: generatePackageFiles(classtree); bpatel@1568: generateProfileFiles(); duke@1: duke@1: generateOtherFiles(root, classtree); duke@1: configuration.tagletManager.printReport(); duke@1: } duke@1: duke@1: /** duke@1: * Generate additional documentation that is added to the API documentation. duke@1: * duke@1: * @param root the RootDoc of source to document. duke@1: * @param classtree the data structure representing the class tree. duke@1: */ duke@1: protected void generateOtherFiles(RootDoc root, ClassTree classtree) throws Exception { duke@1: BuilderFactory builderFactory = configuration.getBuilderFactory(); duke@1: AbstractBuilder constantsSummaryBuilder = builderFactory.getConstantsSummaryBuider(); duke@1: constantsSummaryBuilder.build(); duke@1: AbstractBuilder serializedFormBuilder = builderFactory.getSerializedFormBuilder(); duke@1: serializedFormBuilder.build(); duke@1: } duke@1: duke@1: /** bpatel@1568: * Generate the profile documentation. bpatel@1568: * bpatel@1568: */ bpatel@1568: protected abstract void generateProfileFiles() throws Exception; bpatel@1568: bpatel@1568: /** duke@1: * Generate the package documentation. duke@1: * duke@1: * @param classtree the data structure representing the class tree. duke@1: */ duke@1: protected abstract void generatePackageFiles(ClassTree classtree) throws Exception; duke@1: duke@1: /** duke@1: * Generate the class documentation. duke@1: * duke@1: * @param classtree the data structure representing the class tree. duke@1: */ duke@1: protected abstract void generateClassFiles(ClassDoc[] arr, ClassTree classtree); duke@1: duke@1: /** duke@1: * Iterate through all classes and construct documentation for them. duke@1: * duke@1: * @param root the RootDoc of source to document. duke@1: * @param classtree the data structure representing the class tree. duke@1: */ duke@1: protected void generateClassFiles(RootDoc root, ClassTree classtree) { duke@1: generateClassFiles(classtree); duke@1: PackageDoc[] packages = root.specifiedPackages(); duke@1: for (int i = 0; i < packages.length; i++) { duke@1: generateClassFiles(packages[i].allClasses(), classtree); duke@1: } duke@1: } duke@1: duke@1: /** duke@1: * Generate the class files for single classes specified on the command line. duke@1: * duke@1: * @param classtree the data structure representing the class tree. duke@1: */ duke@1: private void generateClassFiles(ClassTree classtree) { duke@1: String[] packageNames = configuration.classDocCatalog.packageNames(); duke@1: for (int packageNameIndex = 0; packageNameIndex < packageNames.length; duke@1: packageNameIndex++) { duke@1: generateClassFiles(configuration.classDocCatalog.allClasses( duke@1: packageNames[packageNameIndex]), classtree); duke@1: } duke@1: } duke@1: }