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         li.setStyle(HtmlStyle.blockList);
  81         return li;
  82     }
  83 
  84     /**
  85      * Add serializable methods.
  86      *
  87      * @param heading the heading for the section
  88      * @param serializableMethodContent the tree to be added to the serializable methods
  89      *        content tree
  90      * @return a content tree for the serializable methods content
  91      */
  92     public Content getSerializableMethods(String heading, Content serializableMethodContent) {
  93         Content headingContent = new StringContent(heading);
  94         Content serialHeading = HtmlTree.HEADING(Headings.SerializedForm.CLASS_SUBHEADING, headingContent);
  95         Content section = HtmlTree.SECTION(HtmlStyle.detail, serialHeading);
  96         section.add(serializableMethodContent);
  97         return HtmlTree.LI(HtmlStyle.blockList, section);
  98     }
  99 
 100     /**
 101      * Return the no customization message.
 102      *
 103      * @param msg the message to be displayed
 104      * @return no customization message content
 105      */
 106     public Content getNoCustomizationMsg(String msg) {
 107         Content noCustomizationMsg = new StringContent(msg);
 108         return noCustomizationMsg;
 109     }
 110 
 111     /**
 112      * Add the member header.
 113      *
 114      * @param member the method document to be listed
 115      * @param methodsContentTree the content tree to which the member header will be added
 116      */
 117     public void addMemberHeader(ExecutableElement member, Content methodsContentTree) {
 118         Content memberContent = new StringContent(name(member));
 119         Content heading = HtmlTree.HEADING(Headings.SerializedForm.MEMBER_HEADING, memberContent);
 120         methodsContentTree.add(heading);
 121         methodsContentTree.add(getSignature(member));
 122     }
 123 
 124     /**
 125      * Add the deprecated information for this member.
 126      *
 127      * @param member the method to document.
 128      * @param methodsContentTree the tree to which the deprecated info will be added
 129      */
 130     public void addDeprecatedMemberInfo(ExecutableElement member, Content methodsContentTree) {
 131         addDeprecatedInfo(member, methodsContentTree);
 132     }
 133 
 134     /**
 135      * Add the description text for this member.
 136      *
 137      * @param member the method to document.
 138      * @param methodsContentTree the tree to which the deprecated info will be added
 139      */
 140     public void addMemberDescription(ExecutableElement member, Content methodsContentTree) {
 141         addComment(member, methodsContentTree);
 142     }
 143 
 144     /**
 145      * Add the tag information for this member.
 146      *
 147      * @param member the method to document.
 148      * @param methodsContentTree the tree to which the member tags info will be added
 149      */
 150     public void addMemberTags(ExecutableElement member, Content methodsContentTree) {
 151         Content tagContent = new ContentBuilder();
 152         TagletManager tagletManager =
 153             configuration.tagletManager;
 154         TagletWriter.genTagOutput(tagletManager, member,
 155             tagletManager.getSerializedFormTaglets(),
 156             writer.getTagletWriterInstance(false), tagContent);
 157         Content dlTags = new HtmlTree(HtmlTag.DL);
 158         dlTags.add(tagContent);
 159         methodsContentTree.add(dlTags);
 160         if (name(member).compareTo("writeExternal") == 0
 161                 && utils.getSerialDataTrees(member).isEmpty()) {
 162             serialWarning(member, "doclet.MissingSerialDataTag",
 163                 utils.getFullyQualifiedName(member.getEnclosingElement()), name(member));
 164         }
 165     }
 166 }