1 /*
2 * Copyright (c) 2001, 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.formats.html;
27
28 import java.util.*;
29
30 import javax.lang.model.element.Modifier;
31 import javax.lang.model.element.PackageElement;
32 import javax.lang.model.element.TypeElement;
33 import javax.lang.model.element.VariableElement;
34
35 import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
36 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants;
37 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
38 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
39 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
40 import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;
41 import jdk.javadoc.internal.doclets.toolkit.ConstantsSummaryWriter;
42 import jdk.javadoc.internal.doclets.toolkit.Content;
43 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
44 import jdk.javadoc.internal.doclets.toolkit.util.DocLink;
45 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
46
47
48 /**
49 * Write the Constants Summary Page in HTML format.
50 *
51 * <p><b>This is NOT part of any supported API.
52 * If you write code that depends on this, you do so at your own risk.
53 * This code and its internal interfaces are subject to change or
54 * deletion without notice.</b>
55 *
56 * @author Jamie Ho
57 * @author Bhavesh Patel (Modified)
58 */
59 public class ConstantsSummaryWriterImpl extends HtmlDocletWriter implements ConstantsSummaryWriter {
60
61 /**
62 * The configuration used in this run of the standard doclet.
63 */
64 HtmlConfiguration configuration;
65
66 /**
67 * The current class being documented.
68 */
69 private TypeElement currentTypeElement;
70
71 private final String constantsTableSummary;
72
73 private final TableHeader constantsTableHeader;
74
75 /**
76 * The HTML tree for main tag.
77 */
78 private HtmlTree mainTree = HtmlTree.MAIN();
79
80 /**
81 * The HTML tree for constant values summary.
82 */
83 private HtmlTree summaryTree;
84
85 /**
86 * Construct a ConstantsSummaryWriter.
87 * @param configuration the configuration used in this run
88 * of the standard doclet.
89 */
90 public ConstantsSummaryWriterImpl(HtmlConfiguration configuration) {
91 super(configuration, DocPaths.CONSTANT_VALUES);
92 this.configuration = configuration;
93 constantsTableSummary = configuration.getText("doclet.Constants_Table_Summary",
94 configuration.getText("doclet.Constants_Summary"));
95 constantsTableHeader = new TableHeader(
96 contents.modifierAndTypeLabel, contents.constantFieldLabel, contents.valueLabel);
97 }
98
99 /**
100 * {@inheritDoc}
101 */
102 public Content getHeader() {
103 String label = configuration.getText("doclet.Constants_Summary");
104 HtmlTree bodyTree = getBody(true, getWindowTitle(label));
105 HtmlTree htmlTree = (configuration.allowTag(HtmlTag.HEADER))
106 ? HtmlTree.HEADER()
107 : bodyTree;
108 addTop(htmlTree);
109 addNavLinks(true, htmlTree);
110 if (configuration.allowTag(HtmlTag.HEADER)) {
111 bodyTree.addContent(htmlTree);
112 }
113 return bodyTree;
114 }
115
116 /**
117 * {@inheritDoc}
118 */
119 public Content getContentsHeader() {
120 return new HtmlTree(HtmlTag.UL);
121 }
122
123 /**
124 * {@inheritDoc}
125 */
126 public void addLinkToPackageContent(PackageElement pkg,
127 Set<PackageElement> printedPackageHeaders, Content contentListTree) {
128 //add link to summary
129 Content link;
130 if (pkg.isUnnamed()) {
131 link = getHyperLink(getDocLink(
132 SectionName.UNNAMED_PACKAGE_ANCHOR),
133 contents.defaultPackageLabel, "", "");
134 } else {
135 String parsedPackageName = utils.parsePackageName(pkg);
136 Content packageNameContent = getPackageLabel(parsedPackageName);
137 packageNameContent.addContent(".*");
138 link = getHyperLink(DocLink.fragment(parsedPackageName),
139 packageNameContent, "", "");
140 PackageElement abbrevPkg = configuration.workArounds.getAbbreviatedPackageElement(pkg);
141 printedPackageHeaders.add(abbrevPkg);
142 }
143 contentListTree.addContent(HtmlTree.LI(link));
144 }
145
146 /**
147 * {@inheritDoc}
148 */
149 public void addContentsList(Content contentTree, Content contentListTree) {
150 Content titleContent = contents.constantsSummaryTitle;
151 Content pHeading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, true,
152 HtmlStyle.title, titleContent);
153 Content div = HtmlTree.DIV(HtmlStyle.header, pHeading);
154 Content headingContent = contents.contentsHeading;
155 Content heading = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, true,
156 headingContent);
157 if (configuration.allowTag(HtmlTag.SECTION)) {
158 HtmlTree section = HtmlTree.SECTION(heading);
159 section.addContent(contentListTree);
160 div.addContent(section);
161 mainTree.addContent(div);
162 } else {
163 div.addContent(heading);
164 div.addContent(contentListTree);
165 contentTree.addContent(div);
166 }
167 }
168
169 /**
170 * {@inheritDoc}
171 */
172 public Content getConstantSummaries() {
173 HtmlTree summariesDiv = new HtmlTree(HtmlTag.DIV);
174 summariesDiv.addStyle(HtmlStyle.constantValuesContainer);
175 return summariesDiv;
176 }
177
178 /**
179 * {@inheritDoc}
180 */
181 public void addPackageName(PackageElement pkg, Content summariesTree, boolean first) {
182 Content pkgNameContent;
183 if (!first && configuration.allowTag(HtmlTag.SECTION)) {
184 summariesTree.addContent(summaryTree);
185 }
186 if (pkg.isUnnamed()) {
187 summariesTree.addContent(getMarkerAnchor(
188 SectionName.UNNAMED_PACKAGE_ANCHOR));
189 pkgNameContent = contents.defaultPackageLabel;
190 } else {
191 String parsedPackageName = utils.parsePackageName(pkg);
192 summariesTree.addContent(getMarkerAnchor(parsedPackageName));
193 pkgNameContent = getPackageLabel(parsedPackageName);
194 }
195 Content headingContent = new StringContent(".*");
196 Content heading = HtmlTree.HEADING(HtmlConstants.PACKAGE_HEADING, true,
197 pkgNameContent);
198 heading.addContent(headingContent);
199 if (configuration.allowTag(HtmlTag.SECTION)) {
200 summaryTree = HtmlTree.SECTION(heading);
201 } else {
202 summariesTree.addContent(heading);
203 }
204 }
205
206 /**
207 * {@inheritDoc}
208 */
209 public Content getClassConstantHeader() {
210 HtmlTree ul = new HtmlTree(HtmlTag.UL);
211 ul.addStyle(HtmlStyle.blockList);
212 return ul;
213 }
214
215 /**
216 * {@inheritDoc}
217 */
218 public void addClassConstant(Content summariesTree, Content classConstantTree) {
219 if (configuration.allowTag(HtmlTag.SECTION)) {
220 summaryTree.addContent(classConstantTree);
221 } else {
222 summariesTree.addContent(classConstantTree);
223 }
224 }
225
226 /**
227 * Get the table caption and header for the constant summary table
228 *
229 * @param typeElement the TypeElement to be documented
230 * @return constant members header content
231 */
232 public Content getConstantMembersHeader(TypeElement typeElement) {
233 //generate links backward only to public classes.
234 Content classlink = (utils.isPublic(typeElement) || utils.isProtected(typeElement)) ?
235 getLink(new LinkInfoImpl(configuration,
236 LinkInfoImpl.Kind.CONSTANT_SUMMARY, typeElement)) :
237 new StringContent(utils.getFullyQualifiedName(typeElement));
238
239 PackageElement enclosingPackage = utils.containingPackage(typeElement);
240 if (!enclosingPackage.isUnnamed()) {
241 Content cb = new ContentBuilder();
242 cb.addContent(enclosingPackage.getQualifiedName());
243 cb.addContent(".");
244 cb.addContent(classlink);
245 return getClassName(cb);
246 } else {
247 return getClassName(classlink);
248 }
249 }
250
251 /**
252 * Get the class name in the table caption and the table header.
253 *
254 * @param classStr the class name to print.
255 * @return the table caption and header
256 */
257 protected Content getClassName(Content classStr) {
258 Content caption = getTableCaption(classStr);
259 Content table = (configuration.isOutputHtml5())
260 ? HtmlTree.TABLE(HtmlStyle.constantsSummary, caption)
261 : HtmlTree.TABLE(HtmlStyle.constantsSummary, constantsTableSummary, caption);
262 table.addContent(constantsTableHeader.toContent());
263 return table;
264 }
265
266 /**
267 * {@inheritDoc}
268 */
269 public void addConstantMembers(TypeElement typeElement, Collection<VariableElement> fields,
270 Content classConstantTree) {
271 currentTypeElement = typeElement;
272 Content tbody = new HtmlTree(HtmlTag.TBODY);
273 boolean altColor = true;
274 for (VariableElement field : fields) {
275 HtmlTree tr = new HtmlTree(HtmlTag.TR);
276 tr.addStyle(altColor ? HtmlStyle.altColor : HtmlStyle.rowColor);
277 addConstantMember(field, tr);
278 tbody.addContent(tr);
279 altColor = !altColor;
280 }
281 Content table = getConstantMembersHeader(typeElement);
282 table.addContent(tbody);
283 Content li = HtmlTree.LI(HtmlStyle.blockList, table);
284 classConstantTree.addContent(li);
285 }
286
287 /**
288 * Add the row for the constant summary table.
289 *
290 * @param member the field to be documented.
291 * @param trTree an htmltree object for the table row
292 */
293 private void addConstantMember(VariableElement member, HtmlTree trTree) {
294 trTree.addContent(getTypeColumn(member));
295 trTree.addContent(getNameColumn(member));
296 trTree.addContent(getValue(member));
297 }
298
299 /**
300 * Get the type column for the constant summary table row.
301 *
302 * @param member the field to be documented.
303 * @return the type column of the constant table row
304 */
305 private Content getTypeColumn(VariableElement member) {
306 Content anchor = getMarkerAnchor(currentTypeElement.getQualifiedName() +
307 "." + member.getSimpleName());
308 Content tdType = HtmlTree.TD(HtmlStyle.colFirst, anchor);
309 Content code = new HtmlTree(HtmlTag.CODE);
310 for (Modifier mod : member.getModifiers()) {
311 Content modifier = new StringContent(mod.toString());
312 code.addContent(modifier);
313 code.addContent(Contents.SPACE);
314 }
315 Content type = getLink(new LinkInfoImpl(configuration,
316 LinkInfoImpl.Kind.CONSTANT_SUMMARY, member.asType()));
317 code.addContent(type);
318 tdType.addContent(code);
319 return tdType;
320 }
321
322 /**
323 * Get the name column for the constant summary table row.
324 *
325 * @param member the field to be documented.
326 * @return the name column of the constant table row
327 */
328 private Content getNameColumn(VariableElement member) {
329 Content nameContent = getDocLink(LinkInfoImpl.Kind.CONSTANT_SUMMARY,
330 member, member.getSimpleName(), false);
331 Content code = HtmlTree.CODE(nameContent);
332 return HtmlTree.TH_ROW_SCOPE(HtmlStyle.colSecond, code);
333 }
334
335 /**
336 * Get the value column for the constant summary table row.
337 *
338 * @param member the field to be documented.
339 * @return the value column of the constant table row
340 */
341 private Content getValue(VariableElement member) {
342 String value = utils.constantValueExpresion(member);
343 Content valueContent = new StringContent(value);
344 Content code = HtmlTree.CODE(valueContent);
345 return HtmlTree.TD(HtmlStyle.colLast, code);
346 }
347
348 /**
349 * {@inheritDoc}
350 */
351 public void addConstantSummaries(Content contentTree, Content summariesTree) {
352 if (configuration.allowTag(HtmlTag.SECTION) && summaryTree != null) {
353 summariesTree.addContent(summaryTree);
354 }
355 if (configuration.allowTag(HtmlTag.MAIN)) {
356 mainTree.addContent(summariesTree);
357 contentTree.addContent(mainTree);
358 } else {
359 contentTree.addContent(summariesTree);
360 }
361 }
362
363 /**
364 * {@inheritDoc}
365 */
366 public void addFooter(Content contentTree) {
367 Content htmlTree = (configuration.allowTag(HtmlTag.FOOTER))
368 ? HtmlTree.FOOTER()
369 : contentTree;
370 addNavLinks(false, htmlTree);
371 addBottom(htmlTree);
372 if (configuration.allowTag(HtmlTag.FOOTER)) {
373 contentTree.addContent(htmlTree);
374 }
375 }
376
377 /**
378 * {@inheritDoc}
379 */
380 @Override
381 public void printDocument(Content contentTree) throws DocFileIOException {
382 printHtmlDocument(null, true, contentTree);
383 }
384 }