AnnotationTypeWriterImpl.java revision 3568:99470b5ea8d8 
1/*
2 * Copyright (c) 2003, 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.IOException;
29import java.util.List;
30
31import javax.lang.model.element.PackageElement;
32import javax.lang.model.element.TypeElement;
33import javax.lang.model.type.TypeMirror;
34
35import com.sun.source.doctree.DocTree;
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.AnnotationTypeWriter;
42import jdk.javadoc.internal.doclets.toolkit.Content;
43import jdk.javadoc.internal.doclets.toolkit.builders.MemberSummaryBuilder;
44import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
45import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
46import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
47import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException;
48import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberMap;
49
50/**
51 * Generate the Class Information Page.
52 *
53 *  <p><b>This is NOT part of any supported API.
54 *  If you write code that depends on this, you do so at your own risk.
55 *  This code and its internal interfaces are subject to change or
56 *  deletion without notice.</b>
57 *
58 * @see java.util.Collections
59 * @see java.util.List
60 * @see java.util.ArrayList
61 * @see java.util.HashMap
62 *
63 * @author Atul M Dambalkar
64 * @author Robert Field
65 * @author Bhavesh Patel (Modified)
66 */
67public class AnnotationTypeWriterImpl extends SubWriterHolderWriter
68        implements AnnotationTypeWriter {
69
70    protected TypeElement annotationType;
71
72    protected TypeMirror prev;
73
74    protected TypeMirror next;
75
76    /**
77     * @param configuration the configuration
78     * @param annotationType the annotation type being documented.
79     * @param prevType the previous class that was documented.
80     * @param nextType the next class being documented.
81     * @throws java.lang.Exception
82     */
83    public AnnotationTypeWriterImpl(ConfigurationImpl configuration,
84            TypeElement annotationType, TypeMirror prevType, TypeMirror nextType)
85            throws Exception {
86        super(configuration, DocPath.forClass(configuration.utils, annotationType));
87        this.annotationType = annotationType;
88        configuration.currentTypeElement = annotationType;
89        this.prev = prevType;
90        this.next = nextType;
91    }
92
93    /**
94     * Get the module link.
95     *
96     * @return a content tree for the module link
97     */
98    @Override
99    protected Content getNavLinkModule() {
100        Content linkContent = getModuleLink(utils.elementUtils.getModuleOf(annotationType),
101                contents.moduleLabel);
102        Content li = HtmlTree.LI(linkContent);
103        return li;
104    }
105
106    /**
107     * Get this package link.
108     *
109     * @return a content tree for the package link
110     */
111    @Override
112    protected Content getNavLinkPackage() {
113        Content linkContent = getHyperLink(DocPaths.PACKAGE_SUMMARY,
114                contents.packageLabel);
115        Content li = HtmlTree.LI(linkContent);
116        return li;
117    }
118
119    /**
120     * Get the class link.
121     *
122     * @return a content tree for the class link
123     */
124    @Override
125    protected Content getNavLinkClass() {
126        Content li = HtmlTree.LI(HtmlStyle.navBarCell1Rev, contents.classLabel);
127        return li;
128    }
129
130    /**
131     * Get the class use link.
132     *
133     * @return a content tree for the class use link
134     */
135    @Override
136    protected Content getNavLinkClassUse() {
137        Content linkContent = getHyperLink(DocPaths.CLASS_USE.resolve(filename), contents.useLabel);
138        Content li = HtmlTree.LI(linkContent);
139        return li;
140    }
141
142    /**
143     * Get link to previous class.
144     *
145     * @return a content tree for the previous class link
146     */
147    @Override
148    public Content getNavLinkPrevious() {
149        Content li;
150        if (prev != null) {
151            Content prevLink = getLink(new LinkInfoImpl(configuration,
152                    LinkInfoImpl.Kind.CLASS, utils.asTypeElement(prev))
153                    .label(contents.prevClassLabel).strong(true));
154            li = HtmlTree.LI(prevLink);
155        }
156        else
157            li = HtmlTree.LI(contents.prevClassLabel);
158        return li;
159    }
160
161    /**
162     * Get link to next class.
163     *
164     * @return a content tree for the next class link
165     */
166    @Override
167    public Content getNavLinkNext() {
168        Content li;
169        if (next != null) {
170            Content nextLink = getLink(new LinkInfoImpl(configuration,
171                    LinkInfoImpl.Kind.CLASS, utils.asTypeElement(next))
172                    .label(contents.nextClassLabel).strong(true));
173            li = HtmlTree.LI(nextLink);
174        }
175        else
176            li = HtmlTree.LI(contents.nextClassLabel);
177        return li;
178    }
179
180    /**
181     * {@inheritDoc}
182     */
183    @Override
184    public Content getHeader(String header) {
185        HtmlTree bodyTree = getBody(true, getWindowTitle(utils.getSimpleName(annotationType)));
186        HtmlTree htmlTree = (configuration.allowTag(HtmlTag.HEADER))
187                ? HtmlTree.HEADER()
188                : bodyTree;
189        addTop(htmlTree);
190        addNavLinks(true, htmlTree);
191        if (configuration.allowTag(HtmlTag.HEADER)) {
192            bodyTree.addContent(htmlTree);
193        }
194        bodyTree.addContent(HtmlConstants.START_OF_CLASS_DATA);
195        HtmlTree div = new HtmlTree(HtmlTag.DIV);
196        div.addStyle(HtmlStyle.header);
197        PackageElement pkg = utils.containingPackage(annotationType);
198        if (!pkg.isUnnamed()) {
199            Content pkgNameContent = new StringContent(utils.getPackageName(pkg));
200            Content pkgNameDiv = HtmlTree.DIV(HtmlStyle.subTitle, pkgNameContent);
201            div.addContent(pkgNameDiv);
202        }
203        LinkInfoImpl linkInfo = new LinkInfoImpl(configuration,
204                LinkInfoImpl.Kind.CLASS_HEADER, annotationType);
205        Content headerContent = new StringContent(header);
206        Content heading = HtmlTree.HEADING(HtmlConstants.CLASS_PAGE_HEADING, true,
207                HtmlStyle.title, headerContent);
208        heading.addContent(getTypeParameterLinks(linkInfo));
209        div.addContent(heading);
210        if (configuration.allowTag(HtmlTag.MAIN)) {
211            mainTree.addContent(div);
212        } else {
213            bodyTree.addContent(div);
214        }
215        return bodyTree;
216    }
217
218    /**
219     * {@inheritDoc}
220     */
221    @Override
222    public Content getAnnotationContentHeader() {
223        return getContentHeader();
224    }
225
226    /**
227     * {@inheritDoc}
228     */
229    @Override
230    public void addFooter(Content contentTree) {
231        contentTree.addContent(HtmlConstants.END_OF_CLASS_DATA);
232        Content htmlTree = (configuration.allowTag(HtmlTag.FOOTER))
233                ? HtmlTree.FOOTER()
234                : contentTree;
235        addNavLinks(false, htmlTree);
236        addBottom(htmlTree);
237        if (configuration.allowTag(HtmlTag.FOOTER)) {
238            contentTree.addContent(htmlTree);
239        }
240    }
241
242    /**
243     * {@inheritDoc}
244     */
245    @Override
246    public void printDocument(Content contentTree) throws IOException {
247        printHtmlDocument(configuration.metakeywords.getMetaKeywords(annotationType),
248                true, contentTree);
249    }
250
251    /**
252     * {@inheritDoc}
253     */
254    @Override
255    public Content getAnnotationInfoTreeHeader() {
256        return getMemberTreeHeader();
257    }
258
259    /**
260     * {@inheritDoc}
261     */
262    @Override
263    public Content getAnnotationInfo(Content annotationInfoTree) {
264        return getMemberTree(HtmlStyle.description, annotationInfoTree);
265    }
266
267    /**
268     * {@inheritDoc}
269     */
270    @Override
271    public void addAnnotationTypeSignature(String modifiers, Content annotationInfoTree) {
272        annotationInfoTree.addContent(new HtmlTree(HtmlTag.BR));
273        Content pre = new HtmlTree(HtmlTag.PRE);
274        addAnnotationInfo(annotationType, pre);
275        pre.addContent(modifiers);
276        LinkInfoImpl linkInfo = new LinkInfoImpl(configuration,
277                LinkInfoImpl.Kind.CLASS_SIGNATURE, annotationType);
278        Content annotationName = new StringContent(utils.getSimpleName(annotationType));
279        Content parameterLinks = getTypeParameterLinks(linkInfo);
280        if (configuration.linksource) {
281            addSrcLink(annotationType, annotationName, pre);
282            pre.addContent(parameterLinks);
283        } else {
284            Content span = HtmlTree.SPAN(HtmlStyle.memberNameLabel, annotationName);
285            span.addContent(parameterLinks);
286            pre.addContent(span);
287        }
288        annotationInfoTree.addContent(pre);
289    }
290
291    /**
292     * {@inheritDoc}
293     */
294    @Override
295    public void addAnnotationTypeDescription(Content annotationInfoTree) {
296        if(!configuration.nocomment) {
297            if (!utils.getBody(annotationType).isEmpty()) {
298                addInlineComment(annotationType, annotationInfoTree);
299            }
300        }
301    }
302
303    /**
304     * {@inheritDoc}
305     */
306    @Override
307    public void addAnnotationTypeTagInfo(Content annotationInfoTree) {
308        if(!configuration.nocomment) {
309            addTagsInfo(annotationType, annotationInfoTree);
310        }
311    }
312
313    /**
314     * {@inheritDoc}
315     */
316    @Override
317    public void addAnnotationTypeDeprecationInfo(Content annotationInfoTree) {
318        Content hr = new HtmlTree(HtmlTag.HR);
319        annotationInfoTree.addContent(hr);
320        List<? extends DocTree> deprs = utils.getBlockTags(annotationType, DocTree.Kind.DEPRECATED);
321        if (utils.isDeprecated(annotationType)) {
322            CommentHelper ch = utils.getCommentHelper(annotationType);
323            Content deprLabel = HtmlTree.SPAN(HtmlStyle.deprecatedLabel, contents.deprecatedPhrase);
324            Content div = HtmlTree.DIV(HtmlStyle.block, deprLabel);
325            if (!deprs.isEmpty()) {
326
327                List<? extends DocTree> commentTags = ch.getDescription(configuration, deprs.get(0));
328                if (!commentTags.isEmpty()) {
329                    div.addContent(Contents.SPACE);
330                    addInlineDeprecatedComment(annotationType, deprs.get(0), div);
331                }
332            }
333            annotationInfoTree.addContent(div);
334        }
335    }
336
337    /**
338     * {@inheritDoc}
339     */
340    @Override
341    protected Content getNavLinkTree() {
342        Content treeLinkContent = getHyperLink(DocPaths.PACKAGE_TREE,
343                contents.treeLabel, "", "");
344        Content li = HtmlTree.LI(treeLinkContent);
345        return li;
346    }
347
348    /**
349     * Add summary details to the navigation bar.
350     *
351     * @param subDiv the content tree to which the summary detail links will be added
352     */
353    @Override
354    protected void addSummaryDetailLinks(Content subDiv) {
355        try {
356            Content div = HtmlTree.DIV(getNavSummaryLinks());
357            div.addContent(getNavDetailLinks());
358            subDiv.addContent(div);
359        } catch (Exception e) {
360            throw new DocletAbortException(e);
361        }
362    }
363
364    /**
365     * Get summary links for navigation bar.
366     *
367     * @return the content tree for the navigation summary links
368     * @throws java.lang.Exception
369     */
370    protected Content getNavSummaryLinks() throws Exception {
371        Content li = HtmlTree.LI(contents.summaryLabel);
372        li.addContent(Contents.SPACE);
373        Content ulNav = HtmlTree.UL(HtmlStyle.subNavList, li);
374        MemberSummaryBuilder memberSummaryBuilder = (MemberSummaryBuilder)
375                configuration.getBuilderFactory().getMemberSummaryBuilder(this);
376        Content liNavField = new HtmlTree(HtmlTag.LI);
377        addNavSummaryLink(memberSummaryBuilder,
378                "doclet.navField",
379                VisibleMemberMap.Kind.ANNOTATION_TYPE_FIELDS, liNavField);
380        addNavGap(liNavField);
381        ulNav.addContent(liNavField);
382        Content liNavReq = new HtmlTree(HtmlTag.LI);
383        addNavSummaryLink(memberSummaryBuilder,
384                "doclet.navAnnotationTypeRequiredMember",
385                VisibleMemberMap.Kind.ANNOTATION_TYPE_MEMBER_REQUIRED, liNavReq);
386        addNavGap(liNavReq);
387        ulNav.addContent(liNavReq);
388        Content liNavOpt = new HtmlTree(HtmlTag.LI);
389        addNavSummaryLink(memberSummaryBuilder,
390                "doclet.navAnnotationTypeOptionalMember",
391                VisibleMemberMap.Kind.ANNOTATION_TYPE_MEMBER_OPTIONAL, liNavOpt);
392        ulNav.addContent(liNavOpt);
393        return ulNav;
394    }
395
396    /**
397     * Add the navigation summary link.
398     *
399     * @param builder builder for the member to be documented
400     * @param label the label for the navigation
401     * @param type type to be documented
402     * @param liNav the content tree to which the navigation summary link will be added
403     */
404    protected void addNavSummaryLink(MemberSummaryBuilder builder,
405            String label, VisibleMemberMap.Kind type, Content liNav) {
406        AbstractMemberWriter writer = ((AbstractMemberWriter) builder.
407                getMemberSummaryWriter(type));
408        if (writer == null) {
409            liNav.addContent(contents.getContent(label));
410        } else {
411            liNav.addContent(writer.getNavSummaryLink(null,
412                    ! builder.getVisibleMemberMap(type).noVisibleMembers()));
413        }
414    }
415
416    /**
417     * Get detail links for the navigation bar.
418     *
419     * @return the content tree for the detail links
420     * @throws java.lang.Exception
421     */
422    protected Content getNavDetailLinks() throws Exception {
423        Content li = HtmlTree.LI(contents.detailLabel);
424        li.addContent(Contents.SPACE);
425        Content ulNav = HtmlTree.UL(HtmlStyle.subNavList, li);
426        MemberSummaryBuilder memberSummaryBuilder = (MemberSummaryBuilder)
427                configuration.getBuilderFactory().getMemberSummaryBuilder(this);
428        AbstractMemberWriter writerField =
429                ((AbstractMemberWriter) memberSummaryBuilder.
430                getMemberSummaryWriter(VisibleMemberMap.Kind.ANNOTATION_TYPE_FIELDS));
431        AbstractMemberWriter writerOptional =
432                ((AbstractMemberWriter) memberSummaryBuilder.
433                getMemberSummaryWriter(VisibleMemberMap.Kind.ANNOTATION_TYPE_MEMBER_OPTIONAL));
434        AbstractMemberWriter writerRequired =
435                ((AbstractMemberWriter) memberSummaryBuilder.
436                getMemberSummaryWriter(VisibleMemberMap.Kind.ANNOTATION_TYPE_MEMBER_REQUIRED));
437        Content liNavField = new HtmlTree(HtmlTag.LI);
438        if (writerField != null) {
439            writerField.addNavDetailLink(!utils.getAnnotationFields(annotationType).isEmpty(), liNavField);
440        } else {
441            liNavField.addContent(contents.navField);
442        }
443        addNavGap(liNavField);
444        ulNav.addContent(liNavField);
445        if (writerOptional != null){
446            Content liNavOpt = new HtmlTree(HtmlTag.LI);
447            writerOptional.addNavDetailLink(!annotationType.getAnnotationMirrors().isEmpty(), liNavOpt);
448            ulNav.addContent(liNavOpt);
449        } else if (writerRequired != null){
450            Content liNavReq = new HtmlTree(HtmlTag.LI);
451            writerRequired.addNavDetailLink(!annotationType.getAnnotationMirrors().isEmpty(), liNavReq);
452            ulNav.addContent(liNavReq);
453        } else {
454            Content liNav = HtmlTree.LI(contents.navAnnotationTypeMember);
455            ulNav.addContent(liNav);
456        }
457        return ulNav;
458    }
459
460    /**
461     * {@inheritDoc}
462     */
463    @Override
464    public TypeElement getAnnotationTypeElement() {
465        return annotationType;
466    }
467}
468