001: /*
002: * Copyright 2003-2004 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package com.sun.tools.doclets.internal.toolkit;
027:
028: import com.sun.tools.doclets.internal.toolkit.builders.*;
029: import com.sun.tools.doclets.internal.toolkit.util.*;
030: import com.sun.javadoc.*;
031: import java.util.*;
032: import java.io.*;
033:
034: /**
035: * An abstract implementation of a Doclet.
036: *
037: * This code is not part of an API.
038: * It is implementation that is subject to change.
039: * Do not use it as an API.
040: *
041: * @author Jamie Ho
042: */
043: public abstract class AbstractDoclet {
044:
045: /**
046: * The global configuration information for this run.
047: */
048: public Configuration configuration = configuration();
049:
050: /**
051: * The only doclet that may use this toolkit is {@value}
052: */
053: private static final String TOOLKIT_DOCLET_NAME = new com.sun.tools.doclets.formats.html.HtmlDoclet()
054: .getClass().getName();
055:
056: /**
057: * Verify that the only doclet that is using this toolkit is
058: * {@value #TOOLKIT_DOCLET_NAME}.
059: */
060: private boolean isValidDoclet(AbstractDoclet doclet) {
061: if (!doclet.getClass().getName().equals(TOOLKIT_DOCLET_NAME)) {
062: configuration.message.error(
063: "doclet.Toolkit_Usage_Violation",
064: TOOLKIT_DOCLET_NAME);
065: return false;
066: }
067: return true;
068: }
069:
070: /**
071: * The method that starts the execution of the doclet.
072: *
073: * @param doclet the doclet to start the execution for.
074: * @param root the {@link RootDoc} that points to the source to document.
075: * @return true if the doclet executed without error. False otherwise.
076: */
077: public boolean start(AbstractDoclet doclet, RootDoc root) {
078: configuration.root = root;
079: if (!isValidDoclet(doclet)) {
080: return false;
081: }
082: try {
083: doclet.startGeneration(root);
084: } catch (Exception exc) {
085: exc.printStackTrace();
086: return false;
087: }
088: return true;
089: }
090:
091: /**
092: * Indicate that this doclet supports the 1.5 language features.
093: * @return JAVA_1_5, indicating that the new features are supported.
094: */
095: public static LanguageVersion languageVersion() {
096: return LanguageVersion.JAVA_1_5;
097: }
098:
099: /**
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 genrate 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(
121: "doclet.build_version",
122: configuration.getDocletSpecificBuildDate());
123: ClassTree classtree = new ClassTree(configuration,
124: configuration.nodeprecated);
125:
126: generateClassFiles(root, classtree);
127: if (configuration.sourcepath != null
128: && configuration.sourcepath.length() > 0) {
129: StringTokenizer pathTokens = new StringTokenizer(
130: configuration.sourcepath, String
131: .valueOf(File.pathSeparatorChar));
132: boolean first = true;
133: while (pathTokens.hasMoreTokens()) {
134: Util.copyDocFiles(configuration, pathTokens.nextToken()
135: + File.separator,
136: DocletConstants.DOC_FILES_DIR_NAME, first);
137: first = false;
138: }
139: }
140:
141: PackageListWriter.generate(configuration);
142: generatePackageFiles(classtree);
143:
144: generateOtherFiles(root, classtree);
145: configuration.tagletManager.printReport();
146: }
147:
148: /**
149: * Generate additional documentation that is added to the API documentation.
150: *
151: * @param root the RootDoc of source to document.
152: * @param classtree the data structure representing the class tree.
153: */
154: protected void generateOtherFiles(RootDoc root, ClassTree classtree)
155: throws Exception {
156: BuilderFactory builderFactory = configuration
157: .getBuilderFactory();
158: AbstractBuilder constantsSummaryBuilder = builderFactory
159: .getConstantsSummaryBuider();
160: constantsSummaryBuilder.build();
161: AbstractBuilder serializedFormBuilder = builderFactory
162: .getSerializedFormBuilder();
163: serializedFormBuilder.build();
164: }
165:
166: /**
167: * Generate the package documentation.
168: *
169: * @param classtree the data structure representing the class tree.
170: */
171: protected abstract void generatePackageFiles(ClassTree classtree)
172: throws Exception;
173:
174: /**
175: * Generate the class documentation.
176: *
177: * @param classtree the data structure representing the class tree.
178: */
179: protected abstract void generateClassFiles(ClassDoc[] arr,
180: ClassTree classtree);
181:
182: /**
183: * Iterate through all classes and construct documentation for them.
184: *
185: * @param root the RootDoc of source to document.
186: * @param classtree the data structure representing the class tree.
187: */
188: protected void generateClassFiles(RootDoc root, ClassTree classtree) {
189: generateClassFiles(classtree);
190: PackageDoc[] packages = root.specifiedPackages();
191: for (int i = 0; i < packages.length; i++) {
192: generateClassFiles(packages[i].allClasses(), classtree);
193: }
194: }
195:
196: /**
197: * Generate the class files for single classes specified on the command line.
198: *
199: * @param classtree the data structure representing the class tree.
200: */
201: private void generateClassFiles(ClassTree classtree) {
202: String[] packageNames = configuration.classDocCatalog
203: .packageNames();
204: for (int packageNameIndex = 0; packageNameIndex < packageNames.length; packageNameIndex++) {
205: generateClassFiles(configuration.classDocCatalog
206: .allClasses(packageNames[packageNameIndex]),
207: classtree);
208: }
209: }
210: }
|