AbstractBuilder.java revision 3896:8e4dbcb99277
1/* 2 * Copyright (c) 2003, 2016, 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 26package jdk.javadoc.internal.doclets.toolkit.builders; 27 28import java.lang.reflect.*; 29import java.util.*; 30 31import javax.lang.model.element.PackageElement; 32 33import jdk.javadoc.internal.doclets.toolkit.Configuration; 34import jdk.javadoc.internal.doclets.toolkit.Content; 35import jdk.javadoc.internal.doclets.toolkit.DocletException; 36import jdk.javadoc.internal.doclets.toolkit.Messages; 37import jdk.javadoc.internal.doclets.toolkit.Resources; 38import jdk.javadoc.internal.doclets.toolkit.util.UncheckedDocletException; 39import jdk.javadoc.internal.doclets.toolkit.util.InternalException; 40import jdk.javadoc.internal.doclets.toolkit.util.SimpleDocletException; 41import jdk.javadoc.internal.doclets.toolkit.util.Utils; 42 43import static javax.tools.Diagnostic.Kind.*; 44 45/** 46 * The superclass for all builders. A builder is a class that provides 47 * the structure and content of API documentation. A builder is completely 48 * doclet independent which means that any doclet can use builders to 49 * construct documentation, as long as it impelements the appropriate 50 * writer interfaces. For example, if a doclet wanted to use 51 * {@link ConstantsSummaryBuilder} to build a constant summary, all it has to 52 * do is implement the ConstantsSummaryWriter interface and pass it to the 53 * builder using a WriterFactory. 54 * 55 * <p><b>This is NOT part of any supported API. 56 * If you write code that depends on this, you do so at your own risk. 57 * This code and its internal interfaces are subject to change or 58 * deletion without notice.</b> 59 * 60 * @author Jamie Ho 61 */ 62 63public abstract class AbstractBuilder { 64 public static class Context { 65 /** 66 * The configuration used in this run of the doclet. 67 */ 68 final Configuration configuration; 69 70 /** 71 * Keep track of which packages we have seen for 72 * efficiency purposes. We don't want to copy the 73 * doc files multiple times for a single package. 74 */ 75 final Set<PackageElement> containingPackagesSeen; 76 77 /** 78 * Shared parser for the builder XML file 79 */ 80 final LayoutParser layoutParser; 81 82 Context(Configuration configuration, 83 Set<PackageElement> containingPackagesSeen, 84 LayoutParser layoutParser) { 85 this.configuration = configuration; 86 this.containingPackagesSeen = containingPackagesSeen; 87 this.layoutParser = layoutParser; 88 } 89 } 90 91 /** 92 * The configuration used in this run of the doclet. 93 */ 94 protected final Configuration configuration; 95 96 protected final Messages messages; 97 protected final Resources resources; 98 protected final Utils utils; 99 100 /** 101 * Keep track of which packages we have seen for 102 * efficiency purposes. We don't want to copy the 103 * doc files multiple times for a single package. 104 */ 105 protected final Set<PackageElement> containingPackagesSeen; 106 107 protected final LayoutParser layoutParser; 108 109 /** 110 * True if we want to print debug output. 111 */ 112 protected static final boolean DEBUG = false; 113 114 /** 115 * Construct a Builder. 116 * @param c a context providing information used in this run of the doclet 117 */ 118 public AbstractBuilder(Context c) { 119 this.configuration = c.configuration; 120 this.messages = configuration.getMessages(); 121 this.resources = configuration.getResources(); 122 this.utils = configuration.utils; 123 this.containingPackagesSeen = c.containingPackagesSeen; 124 this.layoutParser = c.layoutParser; 125 } 126 127 /** 128 * Return the name of this builder. 129 * 130 * @return the name of the builder. 131 */ 132 public abstract String getName(); 133 134 /** 135 * Build the documentation. 136 * 137 * @throws DocletException if there is a problem building the documentation 138 */ 139 public abstract void build() throws DocletException; 140 141 /** 142 * Build the documentation, as specified by the given XML element. 143 * 144 * @param node the XML element that specifies which component to document. 145 * @param contentTree content tree to which the documentation will be added 146 * @throws DocletException if there is a problem building the documentation 147 */ 148 protected void build(XMLNode node, Content contentTree) throws DocletException { 149 String component = node.name; 150 try { 151 String methodName = "build" + component; 152 if (DEBUG) { 153 configuration.reporter.print(ERROR, 154 "DEBUG: " + getClass().getName() + "." + methodName); 155 } 156 Method method = getClass().getMethod(methodName, XMLNode.class, Content.class); 157 method.invoke(this, node, contentTree); 158 159 } catch (NoSuchMethodException e) { 160 // Use SimpleDocletException instead of InternalException because there is nothing 161 // informative about about the place the exception occurred, here in this method. 162 // The problem is either a misconfigured doclet.xml file or a missing method in the 163 // user-supplied(?) doclet 164 String message = resources.getText("doclet.builder.unknown.component", component); 165 throw new SimpleDocletException(message, e); 166 167 } catch (InvocationTargetException e) { 168 Throwable cause = e.getCause(); 169 if (cause instanceof DocletException) { 170 throw (DocletException) cause; 171 } else if (cause instanceof UncheckedDocletException) { 172 throw (DocletException) cause.getCause(); 173 } else { 174 // use InternalException, so that a stacktrace showing the position of 175 // the internal exception is generated 176 String message = resources.getText("doclet.builder.exception.in.component", component, 177 e.getCause()); 178 throw new InternalException(message, e.getCause()); 179 } 180 181 } catch (ReflectiveOperationException e) { 182 // Use SimpleDocletException instead of InternalException because there is nothing 183 // informative about about the place the exception occurred, here in this method. 184 // The problem is specific to the method being invoked, such as illegal access 185 // or illegal argument. 186 String message = resources.getText("doclet.builder.exception.in.component", component, e); 187 throw new SimpleDocletException(message, e.getCause()); 188 } 189 } 190 191 /** 192 * Build the documentation, as specified by the children of the given XML element. 193 * 194 * @param node the XML element that specifies which components to document. 195 * @param contentTree content tree to which the documentation will be added 196 * @throws DocletException if there is a problem while building the children 197 */ 198 protected void buildChildren(XMLNode node, Content contentTree) throws DocletException { 199 for (XMLNode child : node.children) 200 build(child, contentTree); 201 } 202} 203