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
26 package jdk.javadoc.internal.doclets.toolkit.builders;
27
28 import java.util.Arrays;
29 import java.util.List;
30 import java.util.Set;
31 import java.util.SortedSet;
32
33 import javax.lang.model.element.PackageElement;
34 import javax.lang.model.element.TypeElement;
35
36 import jdk.javadoc.internal.doclets.toolkit.Content;
37 import jdk.javadoc.internal.doclets.toolkit.DocletException;
38 import 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 */
52 public 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 }