1 /*
2 * Copyright (c) 2003, 2019, 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
26 package jdk.javadoc.internal.doclets.toolkit.builders;
27
28 import java.util.Set;
29 import java.util.SortedSet;
30
31 import javax.lang.model.element.PackageElement;
32 import javax.lang.model.element.TypeElement;
33
34 import jdk.javadoc.internal.doclets.toolkit.Content;
35 import jdk.javadoc.internal.doclets.toolkit.DocFilesHandler;
36 import jdk.javadoc.internal.doclets.toolkit.DocletException;
37 import jdk.javadoc.internal.doclets.toolkit.PackageSummaryWriter;
38
39
40 /**
41 * Builds the summary for a given package.
42 *
43 * <p><b>This is NOT part of any supported API.
44 * If you write code that depends on this, you do so at your own risk.
45 * This code and its internal interfaces are subject to change or
46 * deletion without notice.</b>
47 *
48 * @author Jamie Ho
49 * @author Bhavesh Patel (Modified)
50 */
51 public class PackageSummaryBuilder extends AbstractBuilder {
52
53 /**
54 * The package being documented.
55 */
56 private final PackageElement packageElement;
57
58 /**
59 * The doclet specific writer that will output the result.
60 */
61 private final PackageSummaryWriter packageWriter;
62
63 /**
64 * The content that will be added to the package summary documentation tree.
65 */
66 private Content contentTree;
67
68 /**
69 * Construct a new PackageSummaryBuilder.
70 *
71 * @param context the build context.
72 * @param pkg the package being documented.
73 * @param packageWriter the doclet specific writer that will output the
74 * result.
75 */
76 private PackageSummaryBuilder(Context context,
77 PackageElement pkg,
78 PackageSummaryWriter packageWriter) {
79 super(context);
80 this.packageElement = pkg;
81 this.packageWriter = packageWriter;
82 }
83
84 /**
85 * Construct a new PackageSummaryBuilder.
86 *
87 * @param context the build context.
88 * @param pkg the package being documented.
89 * @param packageWriter the doclet specific writer that will output the
90 * result.
91 *
92 * @return an instance of a PackageSummaryBuilder.
93 */
94 public static PackageSummaryBuilder getInstance(Context context,
95 PackageElement pkg, PackageSummaryWriter packageWriter) {
96 return new PackageSummaryBuilder(context, pkg, packageWriter);
97 }
98
99 /**
100 * Build the package summary.
101 *
102 * @throws DocletException if there is a problem while building the documentation
103 */
104 @Override
105 public void build() throws DocletException {
106 if (packageWriter == null) {
107 //Doclet does not support this output.
108 return;
109 }
110 buildPackageDoc(contentTree);
111 }
112
113 /**
114 * Build the package documentation.
115 *
116 * @param contentTree the content tree to which the documentation will be added
117 * @throws DocletException if there is a problem while building the documentation
118 */
119 protected void buildPackageDoc(Content contentTree) throws DocletException {
120 contentTree = packageWriter.getPackageHeader(utils.getPackageName(packageElement));
121
122 buildContent(contentTree);
123
124 packageWriter.addPackageFooter(contentTree);
125 packageWriter.printDocument(contentTree);
126 DocFilesHandler docFilesHandler = configuration
127 .getWriterFactory()
128 .getDocFilesHandler(packageElement);
129 docFilesHandler.copyDocFiles();
130 }
131
132 /**
133 * Build the content for the package.
134 *
135 * @param contentTree the content tree to which the package contents
136 * will be added
137 * @throws DocletException if there is a problem while building the documentation
138 */
139 protected void buildContent(Content contentTree) throws DocletException {
140 Content packageContentTree = packageWriter.getContentHeader();
141
142 buildPackageDescription(packageContentTree);
143 buildPackageTags(packageContentTree);
144 buildSummary(packageContentTree);
145
146 packageWriter.addPackageContent(contentTree, packageContentTree);
147 }
148
149 /**
150 * Build the package summary.
151 *
152 * @param packageContentTree the package content tree to which the summaries will
153 * be added
154 * @throws DocletException if there is a problem while building the documentation
155 */
156 protected void buildSummary(Content packageContentTree) throws DocletException {
157 Content summaryContentTree = packageWriter.getSummaryHeader();
158
159 buildInterfaceSummary(summaryContentTree);
160 buildClassSummary(summaryContentTree);
161 buildEnumSummary(summaryContentTree);
162 buildRecordSummary(summaryContentTree);
163 buildExceptionSummary(summaryContentTree);
164 buildErrorSummary(summaryContentTree);
165 buildAnnotationTypeSummary(summaryContentTree);
166
167 packageContentTree.add(packageWriter.getPackageSummary(summaryContentTree));
168 }
169
170 /**
171 * Build the summary for the interfaces in this package.
172 *
173 * @param summaryContentTree the summary tree to which the interface summary
174 * will be added
175 */
176 protected void buildInterfaceSummary(Content summaryContentTree) {
177 SortedSet<TypeElement> ilist = utils.isSpecified(packageElement)
178 ? utils.getTypeElementsAsSortedSet(utils.getInterfaces(packageElement))
179 : configuration.typeElementCatalog.interfaces(packageElement);
180 SortedSet<TypeElement> interfaces = utils.filterOutPrivateClasses(ilist, configuration.javafx);
181 if (!interfaces.isEmpty()) {
182 packageWriter.addInterfaceSummary(interfaces, summaryContentTree);
183 }
184 }
185
186 /**
187 * Build the summary for the classes in this package.
188 *
189 * @param summaryContentTree the summary tree to which the class summary will
190 * be added
191 */
192 protected void buildClassSummary(Content summaryContentTree) {
193 SortedSet<TypeElement> clist = utils.isSpecified(packageElement)
194 ? utils.getTypeElementsAsSortedSet(utils.getOrdinaryClasses(packageElement))
195 : configuration.typeElementCatalog.ordinaryClasses(packageElement);
196 SortedSet<TypeElement> classes = utils.filterOutPrivateClasses(clist, configuration.javafx);
197 if (!classes.isEmpty()) {
198 packageWriter.addClassSummary(classes, summaryContentTree);
199 }
200 }
201
202 /**
203 * Build the summary for the enums in this package.
204 *
205 * @param summaryContentTree the summary tree to which the enum summary will
206 * be added
207 */
208 protected void buildEnumSummary(Content summaryContentTree) {
209 SortedSet<TypeElement> elist = utils.isSpecified(packageElement)
210 ? utils.getTypeElementsAsSortedSet(utils.getEnums(packageElement))
211 : configuration.typeElementCatalog.enums(packageElement);
212 SortedSet<TypeElement> enums = utils.filterOutPrivateClasses(elist, configuration.javafx);
213 if (!enums.isEmpty()) {
214 packageWriter.addEnumSummary(enums, summaryContentTree);
215 }
216 }
217
218 /**
219 * Build the summary for the records in this package.
220 *
221 * @param summaryContentTree the summary tree to which the record summary will
222 * be added
223 */
224 protected void buildRecordSummary(Content summaryContentTree) {
225 SortedSet<TypeElement> rlist = utils.isSpecified(packageElement)
226 ? utils.getTypeElementsAsSortedSet(utils.getRecords(packageElement))
227 : configuration.typeElementCatalog.records(packageElement);
228 SortedSet<TypeElement> records = utils.filterOutPrivateClasses(rlist, configuration.javafx);
229 if (!records.isEmpty()) {
230 packageWriter.addRecordSummary(records, summaryContentTree);
231 }
232 }
233
234 /**
235 * Build the summary for the exceptions in this package.
236 *
237 * @param summaryContentTree the summary tree to which the exception summary will
238 * be added
239 */
240 protected void buildExceptionSummary(Content summaryContentTree) {
241 Set<TypeElement> iexceptions =
242 utils.isSpecified(packageElement)
243 ? utils.getTypeElementsAsSortedSet(utils.getExceptions(packageElement))
244 : configuration.typeElementCatalog.exceptions(packageElement);
245 SortedSet<TypeElement> exceptions = utils.filterOutPrivateClasses(iexceptions,
246 configuration.javafx);
247 if (!exceptions.isEmpty()) {
248 packageWriter.addExceptionSummary(exceptions, summaryContentTree);
249 }
250 }
251
252 /**
253 * Build the summary for the errors in this package.
254 *
255 * @param summaryContentTree the summary tree to which the error summary will
256 * be added
257 */
258 protected void buildErrorSummary(Content summaryContentTree) {
259 Set<TypeElement> ierrors =
260 utils.isSpecified(packageElement)
261 ? utils.getTypeElementsAsSortedSet(utils.getErrors(packageElement))
262 : configuration.typeElementCatalog.errors(packageElement);
263 SortedSet<TypeElement> errors = utils.filterOutPrivateClasses(ierrors, configuration.javafx);
264 if (!errors.isEmpty()) {
265 packageWriter.addErrorSummary(errors, summaryContentTree);
266 }
267 }
268
269 /**
270 * Build the summary for the annotation type in this package.
271 *
272 * @param summaryContentTree the summary tree to which the annotation type
273 * summary will be added
274 */
275 protected void buildAnnotationTypeSummary(Content summaryContentTree) {
276 SortedSet<TypeElement> iannotationTypes =
277 utils.isSpecified(packageElement)
278 ? utils.getTypeElementsAsSortedSet(utils.getAnnotationTypes(packageElement))
279 : configuration.typeElementCatalog.annotationTypes(packageElement);
280 SortedSet<TypeElement> annotationTypes = utils.filterOutPrivateClasses(iannotationTypes,
281 configuration.javafx);
282 if (!annotationTypes.isEmpty()) {
283 packageWriter.addAnnotationTypeSummary(annotationTypes, summaryContentTree);
284 }
285 }
286
287 /**
288 * Build the description of the summary.
289 *
290 * @param packageContentTree the tree to which the package description will
291 * be added
292 */
293 protected void buildPackageDescription(Content packageContentTree) {
294 if (configuration.nocomment) {
295 return;
296 }
297 packageWriter.addPackageDescription(packageContentTree);
298 }
299
300 /**
301 * Build the tags of the summary.
302 *
303 * @param packageContentTree the tree to which the package tags will be added
304 */
305 protected void buildPackageTags(Content packageContentTree) {
306 if (configuration.nocomment) {
307 return;
308 }
309 packageWriter.addPackageTags(packageContentTree);
310 }
311 }