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
26package jdk.javadoc.internal.doclets.formats.html;
27
28import java.util.*;
29
30import javax.lang.model.element.Modifier;
31import javax.lang.model.element.PackageElement;
32import javax.lang.model.element.TypeElement;
33import javax.lang.model.element.VariableElement;
34
35import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
36import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants;
37import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
38import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
39import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
40import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;
41import jdk.javadoc.internal.doclets.toolkit.ConstantsSummaryWriter;
42import jdk.javadoc.internal.doclets.toolkit.Content;
43import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
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    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}
387