duke@1: /*
jjg@1357: * Copyright (c) 1998, 2012, Oracle and/or its affiliates. All rights reserved.
duke@1: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
duke@1: *
duke@1: * This code is free software; you can redistribute it and/or modify it
duke@1: * under the terms of the GNU General Public License version 2 only, as
ohair@554: * published by the Free Software Foundation. Oracle designates this
duke@1: * particular file as subject to the "Classpath" exception as provided
ohair@554: * by Oracle in the LICENSE file that accompanied this code.
duke@1: *
duke@1: * This code is distributed in the hope that it will be useful, but WITHOUT
duke@1: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
duke@1: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
duke@1: * version 2 for more details (a copy is included in the LICENSE file that
duke@1: * accompanied this code).
duke@1: *
duke@1: * You should have received a copy of the GNU General Public License version
duke@1: * 2 along with this work; if not, write to the Free Software Foundation,
duke@1: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
duke@1: *
ohair@554: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
ohair@554: * or visit www.oracle.com if you need additional information or have any
ohair@554: * questions.
duke@1: */
duke@1:
duke@1: package com.sun.tools.doclets.formats.html;
duke@1:
bpatel@233: import java.util.*;
bpatel@233:
bpatel@233: import com.sun.javadoc.*;
jjg@1357: import com.sun.tools.doclets.formats.html.markup.*;
duke@1: import com.sun.tools.doclets.internal.toolkit.*;
duke@1: import com.sun.tools.doclets.internal.toolkit.taglets.*;
duke@1:
duke@1: /**
duke@1: * Generate serialized form for serializable fields.
duke@1: * Documentation denoted by the tags serial
and
duke@1: * serialField
is processed.
duke@1: *
jjg@1359: *
This is NOT part of any supported API.
jjg@1359: * If you write code that depends on this, you do so at your own risk.
jjg@1359: * This code and its internal interfaces are subject to change or
jjg@1359: * deletion without notice.
jjg@1359: *
duke@1: * @author Joe Fialli
bpatel@233: * @author Bhavesh Patel (Modified)
duke@1: */
duke@1: public class HtmlSerialFieldWriter extends FieldWriterImpl
duke@1: implements SerializedFormWriter.SerialFieldWriter {
duke@1: ProgramElementDoc[] members = null;
duke@1:
duke@1: private boolean printedOverallAnchor = false;
duke@1:
duke@1: public HtmlSerialFieldWriter(SubWriterHolderWriter writer,
duke@1: ClassDoc classdoc) {
duke@1: super(writer, classdoc);
duke@1: }
duke@1:
mcimadamore@184: public List members(ClassDoc cd) {
jjg@910: return Arrays.asList(cd.serializableFields());
duke@1: }
duke@1:
duke@1: protected void printTypeLinkNoDimension(Type type) {
duke@1: ClassDoc cd = type.asClassDoc();
duke@1: //Linking to package private classes in serialized for causes
duke@1: //broken links. Don't link to them.
duke@1: if (type.isPrimitive() || cd.isPackagePrivate()) {
duke@1: print(type.typeName());
duke@1: } else {
duke@1: writer.printLink(new LinkInfoImpl(
duke@1: LinkInfoImpl.CONTEXT_SERIAL_MEMBER, type));
duke@1: }
duke@1: }
duke@1:
bpatel@766: /**
bpatel@766: * Return the header for serializable fields section.
bpatel@766: *
bpatel@766: * @return a content tree for the header
bpatel@766: */
bpatel@766: public Content getSerializableFieldsHeader() {
bpatel@766: HtmlTree ul = new HtmlTree(HtmlTag.UL);
bpatel@766: ul.addStyle(HtmlStyle.blockList);
bpatel@766: return ul;
duke@1: }
duke@1:
duke@1: /**
bpatel@766: * Return the header for serializable fields content section.
duke@1: *
bpatel@766: * @param isLastContent true if the cotent being documented is the last content.
bpatel@766: * @return a content tree for the header
duke@1: */
bpatel@766: public Content getFieldsContentHeader(boolean isLastContent) {
bpatel@766: HtmlTree li = new HtmlTree(HtmlTag.LI);
bpatel@766: if (isLastContent)
bpatel@766: li.addStyle(HtmlStyle.blockListLast);
bpatel@766: else
bpatel@766: li.addStyle(HtmlStyle.blockList);
bpatel@766: return li;
duke@1: }
duke@1:
duke@1: /**
bpatel@766: * Add serializable fields.
bpatel@766: *
bpatel@766: * @param heading the heading for the section
bpatel@766: * @param serializableFieldsTree the tree to be added to the serializable fileds
bpatel@766: * content tree
bpatel@766: * @return a content tree for the serializable fields content
bpatel@766: */
bpatel@766: public Content getSerializableFields(String heading, Content serializableFieldsTree) {
bpatel@766: HtmlTree li = new HtmlTree(HtmlTag.LI);
bpatel@766: li.addStyle(HtmlStyle.blockList);
bpatel@766: if (serializableFieldsTree.isValid()) {
bpatel@766: if (!printedOverallAnchor) {
bpatel@766: li.addContent(writer.getMarkerAnchor("serializedForm"));
bpatel@766: printedOverallAnchor = true;
bpatel@766: }
bpatel@766: Content headingContent = new StringContent(heading);
bpatel@766: Content serialHeading = HtmlTree.HEADING(HtmlConstants.SERIALIZED_MEMBER_HEADING,
bpatel@766: headingContent);
bpatel@766: li.addContent(serialHeading);
bpatel@766: li.addContent(serializableFieldsTree);
bpatel@766: }
bpatel@766: return li;
bpatel@766: }
bpatel@766:
bpatel@766: /**
bpatel@766: * Add the member header.
bpatel@766: *
jjg@1358: * @param fieldType the class document to be listed
jjg@1358: * @param fieldTypeStr the string for the field type to be documented
bpatel@766: * @param fieldDimensions the dimensions of the field string to be added
jjg@1358: * @param fieldName name of the field to be added
bpatel@766: * @param contentTree the content tree to which the member header will be added
bpatel@766: */
bpatel@766: public void addMemberHeader(ClassDoc fieldType, String fieldTypeStr,
bpatel@766: String fieldDimensions, String fieldName, Content contentTree) {
bpatel@766: Content nameContent = new RawHtml(fieldName);
bpatel@766: Content heading = HtmlTree.HEADING(HtmlConstants.MEMBER_HEADING, nameContent);
bpatel@766: contentTree.addContent(heading);
bpatel@766: Content pre = new HtmlTree(HtmlTag.PRE);
bpatel@766: if (fieldType == null) {
bpatel@766: pre.addContent(fieldTypeStr);
bpatel@766: } else {
bpatel@766: Content fieldContent = new RawHtml(writer.getLink(new LinkInfoImpl(
bpatel@766: LinkInfoImpl.CONTEXT_SERIAL_MEMBER, fieldType)));
bpatel@766: pre.addContent(fieldContent);
bpatel@766: }
bpatel@766: pre.addContent(fieldDimensions + " ");
bpatel@766: pre.addContent(fieldName);
bpatel@766: contentTree.addContent(pre);
bpatel@766: }
bpatel@766:
bpatel@766: /**
bpatel@766: * Add the deprecated information for this member.
duke@1: *
duke@1: * @param field the field to document.
bpatel@766: * @param contentTree the tree to which the deprecated info will be added
duke@1: */
bpatel@766: public void addMemberDeprecatedInfo(FieldDoc field, Content contentTree) {
bpatel@766: addDeprecatedInfo(field, contentTree);
bpatel@766: }
bpatel@766:
bpatel@766: /**
bpatel@766: * Add the description text for this member.
bpatel@766: *
bpatel@766: * @param field the field to document.
bpatel@766: * @param contentTree the tree to which the deprecated info will be added
bpatel@766: */
bpatel@766: public void addMemberDescription(FieldDoc field, Content contentTree) {
duke@1: if (field.inlineTags().length > 0) {
bpatel@766: writer.addInlineComment(field, contentTree);
duke@1: }
duke@1: Tag[] tags = field.tags("serial");
duke@1: if (tags.length > 0) {
bpatel@766: writer.addInlineComment(field, tags[0], contentTree);
duke@1: }
duke@1: }
duke@1:
duke@1: /**
bpatel@766: * Add the description text for this member represented by the tag.
duke@1: *
bpatel@766: * @param serialFieldTag the field to document (represented by tag)
bpatel@766: * @param contentTree the tree to which the deprecated info will be added
duke@1: */
bpatel@766: public void addMemberDescription(SerialFieldTag serialFieldTag, Content contentTree) {
bpatel@233: String serialFieldTagDesc = serialFieldTag.description().trim();
bpatel@233: if (!serialFieldTagDesc.isEmpty()) {
bpatel@766: Content serialFieldContent = new RawHtml(serialFieldTagDesc);
bpatel@766: Content div = HtmlTree.DIV(HtmlStyle.block, serialFieldContent);
bpatel@766: contentTree.addContent(div);
bpatel@233: }
duke@1: }
duke@1:
duke@1: /**
bpatel@766: * Add the tag information for this member.
duke@1: *
duke@1: * @param field the field to document.
bpatel@766: * @param contentTree the tree to which the member tags info will be added
duke@1: */
bpatel@766: public void addMemberTags(FieldDoc field, Content contentTree) {
duke@1: TagletOutputImpl output = new TagletOutputImpl("");
duke@1: TagletWriter.genTagOuput(configuration().tagletManager, field,
bpatel@766: configuration().tagletManager.getCustomTags(field),
duke@1: writer.getTagletWriterInstance(false), output);
bpatel@233: String outputString = output.toString().trim();
bpatel@766: Content dlTags = new HtmlTree(HtmlTag.DL);
bpatel@233: if (!outputString.isEmpty()) {
bpatel@766: Content tagContent = new RawHtml(outputString);
bpatel@766: dlTags.addContent(tagContent);
duke@1: }
bpatel@766: contentTree.addContent(dlTags);
duke@1: }
bpatel@222:
bpatel@222: /**
bpatel@233: * Check to see if overview details should be printed. If
bpatel@222: * nocomment option set or if there is no text to be printed
bpatel@233: * for deprecation info, comment or tags, do not print overview details.
bpatel@233: *
bpatel@233: * @param field the field to check overview details for.
bpatel@233: * @return true if overview details need to be printed
bpatel@222: */
bpatel@233: public boolean shouldPrintOverview(FieldDoc field) {
bpatel@233: if (!configuration().nocomment) {
bpatel@233: if(!field.commentText().isEmpty() ||
bpatel@233: writer.hasSerializationOverviewTags(field))
bpatel@222: return true;
bpatel@233: }
bpatel@233: if (field.tags("deprecated").length > 0)
bpatel@222: return true;
bpatel@222: return false;
bpatel@222: }
duke@1: }