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 List<String> 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 ArrayList<>();
96 constantsTableHeader.add(getModifierTypeHeader());
97 constantsTableHeader.add(configuration.getText("doclet.ConstantField"));
98 constantsTableHeader.add(configuration.getText("doclet.Value"));
99 }
100
101 /**
102 * {@inheritDoc}
103 */
104 public Content getHeader() {
105 String label = configuration.getText("doclet.Constants_Summary");
106 HtmlTree bodyTree = getBody(true, getWindowTitle(label));
107 HtmlTree htmlTree = (configuration.allowTag(HtmlTag.HEADER))
108 ? HtmlTree.HEADER()
109 : bodyTree;
110 addTop(htmlTree);
111 addNavLinks(true, htmlTree);
112 if (configuration.allowTag(HtmlTag.HEADER)) {
113 bodyTree.addContent(htmlTree);
114 }
115 return bodyTree;
116 }
117
118 /**
119 * {@inheritDoc}
120 */
121 public Content getContentsHeader() {
122 return new HtmlTree(HtmlTag.UL);
123 }
124
125 /**
126 * {@inheritDoc}
127 */
128 public void addLinkToPackageContent(PackageElement pkg,
129 Set<PackageElement> printedPackageHeaders, Content contentListTree) {
130 //add link to summary
131 Content link;
132 if (pkg.isUnnamed()) {
133 link = getHyperLink(getDocLink(
134 SectionName.UNNAMED_PACKAGE_ANCHOR),
135 contents.defaultPackageLabel, "", "");
136 } else {
137 String parsedPackageName = utils.parsePackageName(pkg);
138 Content packageNameContent = getPackageLabel(parsedPackageName);
139 packageNameContent.addContent(".*");
140 link = getHyperLink(DocLink.fragment(parsedPackageName),
141 packageNameContent, "", "");
142 PackageElement abbrevPkg = configuration.workArounds.getAbbreviatedPackageElement(pkg);
143 printedPackageHeaders.add(abbrevPkg);
144 }
145 contentListTree.addContent(HtmlTree.LI(link));
146 }
147
148 /**
149 * {@inheritDoc}
150 */
151 public void addContentsList(Content contentTree, Content contentListTree) {
152 Content titleContent = contents.constantsSummaryTitle;
153 Content pHeading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, true,
154 HtmlStyle.title, titleContent);
155 Content div = HtmlTree.DIV(HtmlStyle.header, pHeading);
156 Content headingContent = contents.contentsHeading;
157 Content heading = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, true,
158 headingContent);
159 if (configuration.allowTag(HtmlTag.SECTION)) {
160 HtmlTree section = HtmlTree.SECTION(heading);
161 section.addContent(contentListTree);
162 div.addContent(section);
163 mainTree.addContent(div);
164 } else {
165 div.addContent(heading);
166 div.addContent(contentListTree);
167 contentTree.addContent(div);
168 }
169 }
170
171 /**
172 * {@inheritDoc}
173 */
174 public Content getConstantSummaries() {
175 HtmlTree summariesDiv = new HtmlTree(HtmlTag.DIV);
176 summariesDiv.addStyle(HtmlStyle.constantValuesContainer);
177 return summariesDiv;
178 }
179
180 /**
181 * {@inheritDoc}
182 */
183 public void addPackageName(PackageElement pkg, Content summariesTree, boolean first) {
184 Content pkgNameContent;
185 if (!first && configuration.allowTag(HtmlTag.SECTION)) {
186 summariesTree.addContent(summaryTree);
187 }
188 if (pkg.isUnnamed()) {
189 summariesTree.addContent(getMarkerAnchor(
190 SectionName.UNNAMED_PACKAGE_ANCHOR));
191 pkgNameContent = contents.defaultPackageLabel;
192 } else {
193 String parsedPackageName = utils.parsePackageName(pkg);
194 summariesTree.addContent(getMarkerAnchor(parsedPackageName));
195 pkgNameContent = getPackageLabel(parsedPackageName);
196 }
197 Content headingContent = new StringContent(".*");
198 Content heading = HtmlTree.HEADING(HtmlConstants.PACKAGE_HEADING, true,
199 pkgNameContent);
200 heading.addContent(headingContent);
201 if (configuration.allowTag(HtmlTag.SECTION)) {
202 summaryTree = HtmlTree.SECTION(heading);
203 } else {
204 summariesTree.addContent(heading);
205 }
206 }
207
208 /**
209 * {@inheritDoc}
210 */
211 public Content getClassConstantHeader() {
212 HtmlTree ul = new HtmlTree(HtmlTag.UL);
213 ul.addStyle(HtmlStyle.blockList);
214 return ul;
215 }
216
217 /**
218 * {@inheritDoc}
219 */
220 public void addClassConstant(Content summariesTree, Content classConstantTree) {
221 if (configuration.allowTag(HtmlTag.SECTION)) {
222 summaryTree.addContent(classConstantTree);
223 } else {
224 summariesTree.addContent(classConstantTree);
225 }
226 }
227
228 /**
229 * Get the table caption and header for the constant summary table
230 *
231 * @param typeElement the TypeElement to be documented
232 * @return constant members header content
233 */
234 public Content getConstantMembersHeader(TypeElement typeElement) {
235 //generate links backward only to public classes.
236 Content classlink = (utils.isPublic(typeElement) || utils.isProtected(typeElement)) ?
237 getLink(new LinkInfoImpl(configuration,
238 LinkInfoImpl.Kind.CONSTANT_SUMMARY, typeElement)) :
239 new StringContent(utils.getFullyQualifiedName(typeElement));
240
241 PackageElement enclosingPackage = utils.containingPackage(typeElement);
242 if (!enclosingPackage.isUnnamed()) {
243 Content cb = new ContentBuilder();
244 cb.addContent(enclosingPackage.getQualifiedName());
245 cb.addContent(".");
246 cb.addContent(classlink);
247 return getClassName(cb);
248 } else {
249 return getClassName(classlink);
250 }
251 }
252
253 /**
254 * Get the class name in the table caption and the table header.
255 *
256 * @param classStr the class name to print.
257 * @return the table caption and header
258 */
259 protected Content getClassName(Content classStr) {
260 Content caption = getTableCaption(classStr);
261 Content table = (configuration.isOutputHtml5())
262 ? HtmlTree.TABLE(HtmlStyle.constantsSummary, caption)
263 : HtmlTree.TABLE(HtmlStyle.constantsSummary, constantsTableSummary, caption);
264 table.addContent(getSummaryTableHeader(constantsTableHeader, "col"));
265 return table;
266 }
267
268 /**
269 * {@inheritDoc}
270 */
271 public void addConstantMembers(TypeElement typeElement, Collection<VariableElement> fields,
272 Content classConstantTree) {
273 currentTypeElement = typeElement;
274 Content tbody = new HtmlTree(HtmlTag.TBODY);
275 boolean altColor = true;
276 for (VariableElement field : fields) {
277 HtmlTree tr = new HtmlTree(HtmlTag.TR);
278 tr.addStyle(altColor ? HtmlStyle.altColor : HtmlStyle.rowColor);
279 addConstantMember(field, tr);
280 tbody.addContent(tr);
281 altColor = !altColor;
282 }
283 Content table = getConstantMembersHeader(typeElement);
284 table.addContent(tbody);
285 Content li = HtmlTree.LI(HtmlStyle.blockList, table);
286 classConstantTree.addContent(li);
287 }
288
289 /**
290 * Add the row for the constant summary table.
291 *
292 * @param member the field to be documented.
293 * @param trTree an htmltree object for the table row
294 */
295 private void addConstantMember(VariableElement member, HtmlTree trTree) {
296 trTree.addContent(getTypeColumn(member));
297 trTree.addContent(getNameColumn(member));
298 trTree.addContent(getValue(member));
299 }
300
301 /**
302 * Get the type column for the constant summary table row.
303 *
304 * @param member the field to be documented.
305 * @return the type column of the constant table row
306 */
307 private Content getTypeColumn(VariableElement member) {
308 Content anchor = getMarkerAnchor(currentTypeElement.getQualifiedName() +
309 "." + member.getSimpleName());
310 Content tdType = HtmlTree.TD(HtmlStyle.colFirst, anchor);
311 Content code = new HtmlTree(HtmlTag.CODE);
312 for (Modifier mod : member.getModifiers()) {
313 Content modifier = new StringContent(mod.toString());
314 code.addContent(modifier);
315 code.addContent(Contents.SPACE);
316 }
317 Content type = getLink(new LinkInfoImpl(configuration,
318 LinkInfoImpl.Kind.CONSTANT_SUMMARY, member.asType()));
319 code.addContent(type);
320 tdType.addContent(code);
321 return tdType;
322 }
323
324 /**
325 * Get the name column for the constant summary table row.
326 *
327 * @param member the field to be documented.
328 * @return the name column of the constant table row
329 */
330 private Content getNameColumn(VariableElement member) {
331 Content nameContent = getDocLink(LinkInfoImpl.Kind.CONSTANT_SUMMARY,
332 member, member.getSimpleName(), false);
333 Content code = HtmlTree.CODE(nameContent);
334 return HtmlTree.TH_ROW_SCOPE(HtmlStyle.colSecond, code);
335 }
336
337 /**
338 * Get the value column for the constant summary table row.
339 *
340 * @param member the field to be documented.
341 * @return the value column of the constant table row
342 */
343 private Content getValue(VariableElement member) {
344 String value = utils.constantValueExpresion(member);
345 Content valueContent = new StringContent(value);
346 Content code = HtmlTree.CODE(valueContent);
347 return HtmlTree.TD(HtmlStyle.colLast, code);
348 }
349
350 /**
351 * {@inheritDoc}
352 */
353 public void addConstantSummaries(Content contentTree, Content summariesTree) {
354 if (configuration.allowTag(HtmlTag.SECTION) && summaryTree != null) {
355 summariesTree.addContent(summaryTree);
356 }
357 if (configuration.allowTag(HtmlTag.MAIN)) {
358 mainTree.addContent(summariesTree);
359 contentTree.addContent(mainTree);
360 } else {
361 contentTree.addContent(summariesTree);
362 }
363 }
364
365 /**
366 * {@inheritDoc}
367 */
368 public void addFooter(Content contentTree) {
369 Content htmlTree = (configuration.allowTag(HtmlTag.FOOTER))
370 ? HtmlTree.FOOTER()
371 : contentTree;
372 addNavLinks(false, htmlTree);
373 addBottom(htmlTree);
374 if (configuration.allowTag(HtmlTag.FOOTER)) {
375 contentTree.addContent(htmlTree);
376 }
377 }
378
379 /**
380 * {@inheritDoc}
381 */
382 @Override
383 public void printDocument(Content contentTree) throws DocFileIOException {
384 printHtmlDocument(null, true, contentTree);
385 }
386 }