src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/AbstractBuilder.java

Tue, 09 Oct 2012 19:10:00 -0700

author
jjg
date
Tue, 09 Oct 2012 19:10:00 -0700
changeset 1357
c75be5bc5283
parent 798
4868a36f6fd8
child 1359
25e14ad23cef
permissions
-rw-r--r--

8000663: clean up langtools imports
Reviewed-by: darcy

duke@1 1 /*
jjg@1357 2 * Copyright (c) 2003, 2012, Oracle and/or its affiliates. All rights reserved.
duke@1 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
duke@1 4 *
duke@1 5 * This code is free software; you can redistribute it and/or modify it
duke@1 6 * under the terms of the GNU General Public License version 2 only, as
ohair@554 7 * published by the Free Software Foundation. Oracle designates this
duke@1 8 * particular file as subject to the "Classpath" exception as provided
ohair@554 9 * by Oracle in the LICENSE file that accompanied this code.
duke@1 10 *
duke@1 11 * This code is distributed in the hope that it will be useful, but WITHOUT
duke@1 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
duke@1 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
duke@1 14 * version 2 for more details (a copy is included in the LICENSE file that
duke@1 15 * accompanied this code).
duke@1 16 *
duke@1 17 * You should have received a copy of the GNU General Public License version
duke@1 18 * 2 along with this work; if not, write to the Free Software Foundation,
duke@1 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
duke@1 20 *
ohair@554 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
ohair@554 22 * or visit www.oracle.com if you need additional information or have any
ohair@554 23 * questions.
duke@1 24 */
duke@1 25
duke@1 26 package com.sun.tools.doclets.internal.toolkit.builders;
duke@1 27
duke@1 28 import java.io.*;
duke@1 29 import java.lang.reflect.*;
duke@1 30 import java.util.*;
duke@1 31
jjg@1357 32 import com.sun.tools.doclets.internal.toolkit.*;
jjg@1357 33 import com.sun.tools.doclets.internal.toolkit.util.*;
jjg@1357 34
duke@1 35 /**
duke@1 36 * The superclass for all builders. A builder is a class that provides
duke@1 37 * the structure and content of API documentation. A builder is completely
duke@1 38 * doclet independent which means that any doclet can use builders to
duke@1 39 * construct documentation, as long as it impelements the appropriate
duke@1 40 * writer interfaces. For example, if a doclet wanted to use
duke@1 41 * {@link ConstantsSummaryBuilder} to build a constant summary, all it has to
duke@1 42 * do is implement the ConstantsSummaryWriter interface and pass it to the
duke@1 43 * builder using a WriterFactory.
duke@1 44 *
duke@1 45 * This code is not part of an API.
duke@1 46 * It is implementation that is subject to change.
duke@1 47 * Do not use it as an API
duke@1 48 *
duke@1 49 * @author Jamie Ho
duke@1 50 * @since 1.5
duke@1 51 */
duke@1 52
duke@1 53 public abstract class AbstractBuilder {
duke@1 54
duke@1 55 /**
duke@1 56 * The configuration used in this run of the doclet.
duke@1 57 */
duke@1 58 protected Configuration configuration;
duke@1 59
duke@1 60 /**
duke@1 61 * Keep track of which packages we have seen for
duke@1 62 * efficiency purposes. We don't want to copy the
duke@1 63 * doc files multiple times for a single package.
duke@1 64 */
jjg@74 65 protected static Set<String> containingPackagesSeen;
duke@1 66
duke@1 67 /**
duke@1 68 * True if we want to print debug output.
duke@1 69 */
duke@1 70 protected static final boolean DEBUG = false;
duke@1 71
duke@1 72 /**
duke@1 73 * Construct a Builder.
duke@1 74 * @param configuration the configuration used in this run
duke@1 75 * of the doclet.
duke@1 76 */
duke@1 77 public AbstractBuilder(Configuration configuration) {
duke@1 78 this.configuration = configuration;
duke@1 79 }
duke@1 80
duke@1 81 /**
duke@1 82 * Return the name of this builder.
duke@1 83 *
duke@1 84 * @return the name of the builder.
duke@1 85 */
duke@1 86 public abstract String getName();
duke@1 87
duke@1 88 /**
duke@1 89 * Build the documentation.
duke@1 90 *
duke@1 91 * @throws IOException there was a problem writing the output.
duke@1 92 */
duke@1 93 public abstract void build() throws IOException;
duke@1 94
duke@1 95 /**
jjg@589 96 * Build the documentation, as specified by the given XML element.
duke@1 97 *
jjg@589 98 * @param node the XML element that specifies which component to document.
bpatel@766 99 * @param contentTree content tree to which the documentation will be added
duke@1 100 */
bpatel@766 101 protected void build(XMLNode node, Content contentTree) {
jjg@589 102 String component = node.name;
jjg@589 103 try {
jjg@589 104 invokeMethod("build" + component,
bpatel@766 105 new Class<?>[]{XMLNode.class, Content.class},
bpatel@766 106 new Object[]{node, contentTree});
jjg@589 107 } catch (NoSuchMethodException e) {
jjg@589 108 e.printStackTrace();
jjg@589 109 configuration.root.printError("Unknown element: " + component);
jjg@589 110 throw new DocletAbortException();
jjg@589 111 } catch (InvocationTargetException e) {
jjg@589 112 e.getCause().printStackTrace();
jjg@589 113 } catch (Exception e) {
jjg@589 114 e.printStackTrace();
jjg@589 115 configuration.root.printError("Exception " +
bpatel@766 116 e.getClass().getName() +
bpatel@766 117 " thrown while processing element: " + component);
jjg@589 118 throw new DocletAbortException();
duke@1 119 }
duke@1 120 }
duke@1 121
duke@1 122 /**
jjg@589 123 * Build the documentation, as specified by the children of the given XML element.
jjg@589 124 *
jjg@589 125 * @param node the XML element that specifies which components to document.
bpatel@766 126 * @param contentTree content tree to which the documentation will be added
jjg@589 127 */
bpatel@766 128 protected void buildChildren(XMLNode node, Content contentTree) {
bpatel@766 129 for (XMLNode child : node.children)
bpatel@766 130 build(child, contentTree);
jjg@589 131 }
jjg@589 132
jjg@589 133 /**
duke@1 134 * Given the name and parameters, invoke the method in the builder. This
duke@1 135 * method is required to invoke the appropriate build method as instructed
duke@1 136 * by the builder XML file.
duke@1 137 *
duke@1 138 * @param methodName the name of the method that we would like to invoke.
duke@1 139 * @param paramClasses the types for each parameter.
duke@1 140 * @param params the parameters of the method.
duke@1 141 */
jjg@589 142 protected void invokeMethod(String methodName, Class<?>[] paramClasses,
duke@1 143 Object[] params)
jjg@589 144 throws Exception {
jjg@589 145 if (DEBUG) {
bpatel@766 146 configuration.root.printError("DEBUG: " + this.getClass().getName() + "." + methodName);
jjg@589 147 }
jjg@589 148 Method method = this.getClass().getMethod(methodName, paramClasses);
jjg@589 149 method.invoke(this, params);
jjg@589 150 }
duke@1 151 }

mercurial