1 /*
   2  * Copyright (c) 1998, 2019, 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 javax.lang.model.element.ExecutableElement;
  29 import javax.lang.model.element.TypeElement;
  30 
  31 import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
  32 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
  33 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
  34 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
  35 import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;
  36 import jdk.javadoc.internal.doclets.toolkit.Content;
  37 import jdk.javadoc.internal.doclets.toolkit.SerializedFormWriter;
  38 import jdk.javadoc.internal.doclets.toolkit.taglets.TagletManager;
  39 import jdk.javadoc.internal.doclets.toolkit.taglets.TagletWriter;
  40 
  41 
  42 /**
  43  * Generate serialized form for Serializable/Externalizable methods.
  44  * Documentation denoted by the <code>serialData</code> tag is processed.
  45  *
  46  *  <p><b>This is NOT part of any supported API.
  47  *  If you write code that depends on this, you do so at your own risk.
  48  *  This code and its internal interfaces are subject to change or
  49  *  deletion without notice.</b>
  50  *
  51  * @author Joe Fialli
  52  * @author Bhavesh Patel (Modified)
  53  */
  54 public class HtmlSerialMethodWriter extends MethodWriterImpl implements
  55         SerializedFormWriter.SerialMethodWriter{
  56 
  57     public HtmlSerialMethodWriter(SubWriterHolderWriter writer, TypeElement  typeElement) {
  58         super(writer, typeElement);
  59     }
  60 
  61     /**
  62      * Return the header for serializable methods section.
  63      *
  64      * @return a content tree for the header
  65      */
  66     public Content getSerializableMethodsHeader() {
  67         HtmlTree ul = new HtmlTree(HtmlTag.UL);
  68         ul.setStyle(HtmlStyle.blockList);
  69         return ul;
  70     }
  71 
  72     /**
  73      * Return the header for serializable methods content section.
  74      *
  75      * @param isLastContent true if the cotent being documented is the last content.
  76      * @return a content tree for the header
  77      */
  78     public Content getMethodsContentHeader(boolean isLastContent) {
  79         HtmlTree li = new HtmlTree(HtmlTag.LI);
  80         if (isLastContent)
  81             li.setStyle(HtmlStyle.blockListLast);
  82         else
  83             li.setStyle(HtmlStyle.blockList);
  84         return li;
  85     }
  86 
  87     /**
  88      * Add serializable methods.
  89      *
  90      * @param heading the heading for the section
  91      * @param serializableMethodContent the tree to be added to the serializable methods
  92      *        content tree
  93      * @return a content tree for the serializable methods content
  94      */
  95     public Content getSerializableMethods(String heading, Content serializableMethodContent) {
  96         Content headingContent = new StringContent(heading);
  97         Content serialHeading = HtmlTree.HEADING(Headings.SerializedForm.CLASS_SUBHEADING, headingContent);
  98         Content section = HtmlTree.SECTION(HtmlStyle.detail, serialHeading);
  99         section.add(serializableMethodContent);
 100         return HtmlTree.LI(HtmlStyle.blockList, section);
 101     }
 102 
 103     /**
 104      * Return the no customization message.
 105      *
 106      * @param msg the message to be displayed
 107      * @return no customization message content
 108      */
 109     public Content getNoCustomizationMsg(String msg) {
 110         Content noCustomizationMsg = new StringContent(msg);
 111         return noCustomizationMsg;
 112     }
 113 
 114     /**
 115      * Add the member header.
 116      *
 117      * @param member the method document to be listed
 118      * @param methodsContentTree the content tree to which the member header will be added
 119      */
 120     public void addMemberHeader(ExecutableElement member, Content methodsContentTree) {
 121         Content memberContent = new StringContent(name(member));
 122         Content heading = HtmlTree.HEADING(Headings.SerializedForm.MEMBER_HEADING, memberContent);
 123         methodsContentTree.add(heading);
 124         methodsContentTree.add(getSignature(member));
 125     }
 126 
 127     /**
 128      * Add the deprecated information for this member.
 129      *
 130      * @param member the method to document.
 131      * @param methodsContentTree the tree to which the deprecated info will be added
 132      */
 133     public void addDeprecatedMemberInfo(ExecutableElement member, Content methodsContentTree) {
 134         addDeprecatedInfo(member, methodsContentTree);
 135     }
 136 
 137     /**
 138      * Add the description text for this member.
 139      *
 140      * @param member the method to document.
 141      * @param methodsContentTree the tree to which the deprecated info will be added
 142      */
 143     public void addMemberDescription(ExecutableElement member, Content methodsContentTree) {
 144         addComment(member, methodsContentTree);
 145     }
 146 
 147     /**
 148      * Add the tag information for this member.
 149      *
 150      * @param member the method to document.
 151      * @param methodsContentTree the tree to which the member tags info will be added
 152      */
 153     public void addMemberTags(ExecutableElement member, Content methodsContentTree) {
 154         Content tagContent = new ContentBuilder();
 155         TagletManager tagletManager =
 156             configuration.tagletManager;
 157         TagletWriter.genTagOutput(tagletManager, member,
 158             tagletManager.getSerializedFormTaglets(),
 159             writer.getTagletWriterInstance(false), tagContent);
 160         Content dlTags = new HtmlTree(HtmlTag.DL);
 161         dlTags.add(tagContent);
 162         methodsContentTree.add(dlTags);
 163         if (name(member).compareTo("writeExternal") == 0
 164                 && utils.getSerialDataTrees(member).isEmpty()) {
 165             serialWarning(member, "doclet.MissingSerialDataTag",
 166                 utils.getFullyQualifiedName(member.getEnclosingElement()), name(member));
 167         }
 168     }
 169 }