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.util.Arrays;
29import java.util.List;
30import java.util.Set;
31import java.util.SortedSet;
32
33import javax.lang.model.element.PackageElement;
34import javax.lang.model.element.TypeElement;
35
36import jdk.javadoc.internal.doclets.toolkit.Content;
37import jdk.javadoc.internal.doclets.toolkit.DocletException;
38import jdk.javadoc.internal.doclets.toolkit.PackageSummaryWriter;
39
40
41/**
42 * Builds the summary for a given package.
43 *
44 *  <p><b>This is NOT part of any supported API.
45 *  If you write code that depends on this, you do so at your own risk.
46 *  This code and its internal interfaces are subject to change or
47 *  deletion without notice.</b>
48 *
49 * @author Jamie Ho
50 * @author Bhavesh Patel (Modified)
51 */
52public class PackageSummaryBuilder extends AbstractBuilder {
53    /**
54     * The root element of the package summary XML is {@value}.
55     */
56    public static final String ROOT = "PackageDoc";
57
58    /**
59     * The package being documented.
60     */
61    private final PackageElement packageElement;
62
63    /**
64     * The doclet specific writer that will output the result.
65     */
66    private final PackageSummaryWriter packageWriter;
67
68    /**
69     * The content that will be added to the package summary documentation tree.
70     */
71    private Content contentTree;
72
73    /**
74     * Construct a new PackageSummaryBuilder.
75     *
76     * @param context  the build context.
77     * @param pkg the package being documented.
78     * @param packageWriter the doclet specific writer that will output the
79     *        result.
80     */
81    private PackageSummaryBuilder(Context context,
82            PackageElement pkg,
83            PackageSummaryWriter packageWriter) {
84        super(context);
85        this.packageElement = pkg;
86        this.packageWriter = packageWriter;
87    }
88
89    /**
90     * Construct a new PackageSummaryBuilder.
91     *
92     * @param context  the build context.
93     * @param pkg the package being documented.
94     * @param packageWriter the doclet specific writer that will output the
95     *        result.
96     *
97     * @return an instance of a PackageSummaryBuilder.
98     */
99    public static PackageSummaryBuilder getInstance(Context context,
100            PackageElement pkg, PackageSummaryWriter packageWriter) {
101        return new PackageSummaryBuilder(context, pkg, packageWriter);
102    }
103
104    /**
105     * Build the package summary.
106     *
107     * @throws DocletException if there is a problem while building the documentation
108     */
109    @Override
110    public void build() throws DocletException {
111        if (packageWriter == null) {
112            //Doclet does not support this output.
113            return;
114        }
115        build(layoutParser.parseXML(ROOT), contentTree);
116    }
117
118    /**
119     * {@inheritDoc}
120     */
121    @Override
122    public String getName() {
123        return ROOT;
124    }
125
126    /**
127     * Build the package documentation.
128     *
129     * @param node the XML element that specifies which components to document
130     * @param contentTree the content tree to which the documentation will be added
131     * @throws DocletException if there is a problem while building the documentation
132     */
133    public void buildPackageDoc(XMLNode node, Content contentTree) throws DocletException {
134        contentTree = packageWriter.getPackageHeader(utils.getPackageName(packageElement));
135        buildChildren(node, contentTree);
136        packageWriter.addPackageFooter(contentTree);
137        packageWriter.printDocument(contentTree);
138        utils.copyDocFiles(packageElement);
139    }
140
141    /**
142     * Build the content for the package.
143     *
144     * @param node the XML element that specifies which components to document
145     * @param contentTree the content tree to which the package contents
146     *                    will be added
147     * @throws DocletException if there is a problem while building the documentation
148     */
149    public void buildContent(XMLNode node, Content contentTree) throws DocletException {
150        Content packageContentTree = packageWriter.getContentHeader();
151        buildChildren(node, packageContentTree);
152        packageWriter.addPackageContent(contentTree, packageContentTree);
153    }
154
155    /**
156     * Build the package summary.
157     *
158     * @param node the XML element that specifies which components to document
159     * @param packageContentTree the package content tree to which the summaries will
160     *                           be added
161     * @throws DocletException if there is a problem while building the documentation
162     */
163    public void buildSummary(XMLNode node, Content packageContentTree) throws DocletException {
164        Content summaryContentTree = packageWriter.getSummaryHeader();
165        buildChildren(node, summaryContentTree);
166        packageContentTree.addContent(summaryContentTree);
167    }
168
169    /**
170     * Build the summary for the interfaces in this package.
171     *
172     * @param node the XML element that specifies which components to document
173     * @param summaryContentTree the summary tree to which the interface summary
174     *                           will be added
175     */
176    public void buildInterfaceSummary(XMLNode node, Content summaryContentTree) {
177        String interfaceTableSummary =
178                configuration.getText("doclet.Member_Table_Summary",
179                configuration.getText("doclet.Interface_Summary"),
180                configuration.getText("doclet.interfaces"));
181        List<String> interfaceTableHeader = Arrays.asList(configuration.getText("doclet.Interface"),
182        configuration.getText("doclet.Description"));
183
184        SortedSet<TypeElement> ilist = utils.isSpecified(packageElement)
185                        ? utils.getTypeElementsAsSortedSet(utils.getInterfaces(packageElement))
186                        : configuration.typeElementCatalog.interfaces(packageElement);
187        SortedSet<TypeElement> interfaces = utils.filterOutPrivateClasses(ilist, configuration.javafx);
188        if (!interfaces.isEmpty()) {
189            packageWriter.addClassesSummary(interfaces,
190                    configuration.getText("doclet.Interface_Summary"),
191                    interfaceTableSummary, interfaceTableHeader, summaryContentTree);
192        }
193    }
194
195    /**
196     * Build the summary for the classes in this package.
197     *
198     * @param node the XML element that specifies which components to document
199     * @param summaryContentTree the summary tree to which the class summary will
200     *                           be added
201     */
202    public void buildClassSummary(XMLNode node, Content summaryContentTree) {
203        String classTableSummary =
204                configuration.getText("doclet.Member_Table_Summary",
205                configuration.getText("doclet.Class_Summary"),
206                configuration.getText("doclet.classes"));
207        List<String> classTableHeader = Arrays.asList(configuration.getText("doclet.Class"),
208                configuration.getText("doclet.Description"));
209        SortedSet<TypeElement> clist = utils.isSpecified(packageElement)
210            ? utils.getTypeElementsAsSortedSet(utils.getOrdinaryClasses(packageElement))
211            : configuration.typeElementCatalog.ordinaryClasses(packageElement);
212        SortedSet<TypeElement> classes = utils.filterOutPrivateClasses(clist, configuration.javafx);
213        if (!classes.isEmpty()) {
214            packageWriter.addClassesSummary(classes,
215                    configuration.getText("doclet.Class_Summary"),
216                    classTableSummary, classTableHeader, summaryContentTree);
217        }
218    }
219
220    /**
221     * Build the summary for the enums in this package.
222     *
223     * @param node the XML element that specifies which components to document
224     * @param summaryContentTree the summary tree to which the enum summary will
225     *                           be added
226     */
227    public void buildEnumSummary(XMLNode node, Content summaryContentTree) {
228        String enumTableSummary =
229                configuration.getText("doclet.Member_Table_Summary",
230                configuration.getText("doclet.Enum_Summary"),
231                configuration.getText("doclet.enums"));
232        List<String> enumTableHeader = Arrays.asList(configuration.getText("doclet.Enum"),
233                configuration.getText("doclet.Description"));
234        SortedSet<TypeElement> elist = utils.isSpecified(packageElement)
235            ? utils.getTypeElementsAsSortedSet(utils.getEnums(packageElement))
236            : configuration.typeElementCatalog.enums(packageElement);
237        SortedSet<TypeElement> enums = utils.filterOutPrivateClasses(elist, configuration.javafx);
238        if (!enums.isEmpty()) {
239            packageWriter.addClassesSummary(enums,
240                    configuration.getText("doclet.Enum_Summary"),
241                    enumTableSummary, enumTableHeader, summaryContentTree);
242        }
243    }
244
245    /**
246     * Build the summary for the exceptions in this package.
247     *
248     * @param node the XML element that specifies which components to document
249     * @param summaryContentTree the summary tree to which the exception summary will
250     *                           be added
251     */
252    public void buildExceptionSummary(XMLNode node, Content summaryContentTree) {
253        String exceptionTableSummary =
254                configuration.getText("doclet.Member_Table_Summary",
255                configuration.getText("doclet.Exception_Summary"),
256                configuration.getText("doclet.exceptions"));
257        List<String> exceptionTableHeader = Arrays.asList(configuration.getText("doclet.Exception"),
258                configuration.getText("doclet.Description"));
259        Set<TypeElement> iexceptions =
260            utils.isSpecified(packageElement)
261                ? utils.getTypeElementsAsSortedSet(utils.getExceptions(packageElement))
262                : configuration.typeElementCatalog.exceptions(packageElement);
263        SortedSet<TypeElement> exceptions = utils.filterOutPrivateClasses(iexceptions,
264                configuration.javafx);
265        if (!exceptions.isEmpty()) {
266            packageWriter.addClassesSummary(exceptions,
267                    configuration.getText("doclet.Exception_Summary"),
268                    exceptionTableSummary, exceptionTableHeader, summaryContentTree);
269        }
270    }
271
272    /**
273     * Build the summary for the errors in this package.
274     *
275     * @param node the XML element that specifies which components to document
276     * @param summaryContentTree the summary tree to which the error summary will
277     *                           be added
278     */
279    public void buildErrorSummary(XMLNode node, Content summaryContentTree) {
280        String errorTableSummary =
281                configuration.getText("doclet.Member_Table_Summary",
282                configuration.getText("doclet.Error_Summary"),
283                configuration.getText("doclet.errors"));
284        List<String> errorTableHeader = Arrays.asList(configuration.getText("doclet.Error"),
285                configuration.getText("doclet.Description"));
286        Set<TypeElement> ierrors =
287            utils.isSpecified(packageElement)
288                ? utils.getTypeElementsAsSortedSet(utils.getErrors(packageElement))
289                : configuration.typeElementCatalog.errors(packageElement);
290        SortedSet<TypeElement> errors = utils.filterOutPrivateClasses(ierrors, configuration.javafx);
291        if (!errors.isEmpty()) {
292            packageWriter.addClassesSummary(errors,
293                    configuration.getText("doclet.Error_Summary"),
294                    errorTableSummary, errorTableHeader, summaryContentTree);
295        }
296    }
297
298    /**
299     * Build the summary for the annotation type in this package.
300     *
301     * @param node the XML element that specifies which components to document
302     * @param summaryContentTree the summary tree to which the annotation type
303     *                           summary will be added
304     */
305    public void buildAnnotationTypeSummary(XMLNode node, Content summaryContentTree) {
306        String annotationtypeTableSummary =
307                configuration.getText("doclet.Member_Table_Summary",
308                configuration.getText("doclet.Annotation_Types_Summary"),
309                configuration.getText("doclet.annotationtypes"));
310        List<String> annotationtypeTableHeader = Arrays.asList(
311                configuration.getText("doclet.AnnotationType"),
312                configuration.getText("doclet.Description"));
313        SortedSet<TypeElement> iannotationTypes =
314            utils.isSpecified(packageElement)
315                ? utils.getTypeElementsAsSortedSet(utils.getAnnotationTypes(packageElement))
316                : configuration.typeElementCatalog.annotationTypes(packageElement);
317        SortedSet<TypeElement> annotationTypes = utils.filterOutPrivateClasses(iannotationTypes,
318                configuration.javafx);
319        if (!annotationTypes.isEmpty()) {
320            packageWriter.addClassesSummary(annotationTypes,
321                    configuration.getText("doclet.Annotation_Types_Summary"),
322                    annotationtypeTableSummary, annotationtypeTableHeader,
323                    summaryContentTree);
324        }
325    }
326
327    /**
328     * Build the description of the summary.
329     *
330     * @param node the XML element that specifies which components to document
331     * @param packageContentTree the tree to which the package description will
332     *                           be added
333     */
334    public void buildPackageDescription(XMLNode node, Content packageContentTree) {
335        if (configuration.nocomment) {
336            return;
337        }
338        packageWriter.addPackageDescription(packageContentTree);
339    }
340
341    /**
342     * Build the tags of the summary.
343     *
344     * @param node the XML element that specifies which components to document
345     * @param packageContentTree the tree to which the package tags will be added
346     */
347    public void buildPackageTags(XMLNode node, Content packageContentTree) {
348        if (configuration.nocomment) {
349            return;
350        }
351        packageWriter.addPackageTags(packageContentTree);
352    }
353}
354