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