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