duke@1: /* jjg@1359: * Copyright (c) 2003, 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.internal.toolkit; duke@1: bpatel@233: import java.io.*; bpatel@233: duke@1: import com.sun.javadoc.*; duke@1: duke@1: /** duke@1: * The interface for writing serialized form output. 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. duke@1: * duke@1: * @author Jamie Ho duke@1: * @since 1.5 duke@1: */ duke@1: duke@1: public interface SerializedFormWriter { duke@1: duke@1: /** bpatel@766: * Get the header. duke@1: * duke@1: * @param header the header to write. bpatel@766: * @return the header content tree duke@1: */ bpatel@766: public Content getHeader(String header); duke@1: duke@1: /** bpatel@766: * Get the serialized form summaries header. duke@1: * bpatel@766: * @return the serialized form summary header tree duke@1: */ bpatel@766: public Content getSerializedSummariesHeader(); duke@1: duke@1: /** bpatel@766: * Get the package serialized form header. duke@1: * bpatel@766: * @return the package serialized form header tree duke@1: */ bpatel@766: public Content getPackageSerializedHeader(); duke@1: duke@1: /** bpatel@766: * Get the given package header. bpatel@766: * bpatel@766: * @param packageName the package header to write bpatel@766: * @return a content tree for the package header bpatel@766: */ bpatel@766: public Content getPackageHeader(String packageName); bpatel@766: bpatel@766: /** bpatel@766: * Get the serialized class header. bpatel@766: * bpatel@766: * @return a content tree for the serialized class header bpatel@766: */ bpatel@766: public Content getClassSerializedHeader(); bpatel@766: bpatel@766: /** bpatel@766: * Get the heading for the serializable class. bpatel@766: * bpatel@766: * @param classDoc the class being processed bpatel@766: * @return a content tree for the class heading bpatel@766: */ bpatel@766: public Content getClassHeader(ClassDoc classDoc); bpatel@766: bpatel@766: /** bpatel@766: * Get the serial UID info header. bpatel@766: * bpatel@766: * @return a content tree for the serial uid info header bpatel@766: */ bpatel@766: public Content getSerialUIDInfoHeader(); bpatel@766: bpatel@766: /** bpatel@766: * Adds the serial UID info. duke@1: * duke@1: * @param header the header that will show up before the UID. duke@1: * @param serialUID the serial UID to print. bpatel@766: * @param serialUidTree the serial UID tree to which the content will be added. duke@1: */ bpatel@766: public void addSerialUIDInfo(String header, String serialUID, bpatel@766: Content serialUidTree); bpatel@766: bpatel@766: /** bpatel@766: * Get the class serialize content header. bpatel@766: * bpatel@766: * @return a content tree for the class serialize content header bpatel@766: */ bpatel@766: public Content getClassContentHeader(); duke@1: duke@1: /** duke@1: * Return an instance of a SerialFieldWriter. duke@1: * duke@1: * @return an instance of a SerialFieldWriter. duke@1: */ duke@1: public SerialFieldWriter getSerialFieldWriter(ClassDoc classDoc); duke@1: duke@1: /** duke@1: * Return an instance of a SerialMethodWriter. duke@1: * duke@1: * @return an instance of a SerialMethodWriter. duke@1: */ duke@1: public SerialMethodWriter getSerialMethodWriter(ClassDoc classDoc); duke@1: duke@1: /** duke@1: * Close the writer. duke@1: */ duke@1: public abstract void close() throws IOException; duke@1: duke@1: /** bpatel@766: * Get the serialized content. bpatel@766: * bpatel@766: * @param serializedTreeContent content for serialized data bpatel@766: * @return a content tree for serialized information duke@1: */ bpatel@766: public Content getSerializedContent(Content serializedTreeContent); bpatel@766: bpatel@766: /** bpatel@766: * Add the footer. bpatel@766: * bpatel@766: * @param serializedTree the serialized tree to be added bpatel@766: */ bpatel@766: public void addFooter(Content serializedTree); bpatel@766: bpatel@766: /** bpatel@766: * Print the serialized form document. bpatel@766: * bpatel@766: * @param serializedTree the content tree that will be printed bpatel@766: */ jjg@1364: public abstract void printDocument(Content serializedTree) throws IOException; duke@1: duke@1: /** duke@1: * Write the serialized form for a given field. duke@1: */ duke@1: public interface SerialFieldWriter { duke@1: duke@1: /** bpatel@766: * Get the serializable field header. bpatel@766: * bpatel@766: * @return serialized fields header content tree bpatel@766: */ bpatel@766: public Content getSerializableFieldsHeader(); bpatel@766: bpatel@766: /** bpatel@766: * Get the field content header. bpatel@766: * bpatel@766: * @param isLastContent true if this is the last content to be documented bpatel@766: * @return fields header content tree bpatel@766: */ bpatel@766: public Content getFieldsContentHeader(boolean isLastContent); bpatel@766: bpatel@766: /** bpatel@766: * Get the fields content. duke@1: * duke@1: * @param heading the heading to write. bpatel@766: * @param contentTree content tree to which the heading will be added bpatel@766: * @return serializable fields content tree duke@1: */ bpatel@766: public Content getSerializableFields(String heading, Content contentTree); duke@1: duke@1: /** bpatel@766: * Adds the deprecated information for this member. duke@1: * duke@1: * @param field the field to document. bpatel@766: * @param contentTree content tree to which the deprecated information will be added duke@1: */ bpatel@766: public void addMemberDeprecatedInfo(FieldDoc field, Content contentTree); duke@1: duke@1: /** bpatel@766: * Adds the description text for this member. duke@1: * duke@1: * @param field the field to document. bpatel@766: * @param contentTree content tree to which the member description will be added duke@1: */ bpatel@766: public void addMemberDescription(FieldDoc field, Content contentTree); duke@1: duke@1: /** bpatel@766: * Adds the description text for this member represented by the tag. duke@1: * duke@1: * @param serialFieldTag the field to document (represented by tag). bpatel@766: * @param contentTree content tree to which the member description will be added duke@1: */ bpatel@766: public void addMemberDescription(SerialFieldTag serialFieldTag, Content contentTree); duke@1: duke@1: /** bpatel@766: * Adds the tag information for this member. duke@1: * duke@1: * @param field the field to document. bpatel@766: * @param contentTree content tree to which the member tags will be added duke@1: */ bpatel@766: public void addMemberTags(FieldDoc field, Content contentTree); duke@1: duke@1: /** bpatel@766: * Adds the member header. duke@1: * duke@1: * @param fieldType the type of the field. duke@1: * @param fieldTypeStr the type of the field in string format. We will duke@1: * print this out if we can't link to the type. duke@1: * @param fieldDimensions the dimensions of the field. duke@1: * @param fieldName the name of the field. bpatel@766: * @param contentTree content tree to which the member header will be added duke@1: */ bpatel@766: public void addMemberHeader(ClassDoc fieldType, String fieldTypeStr, bpatel@766: String fieldDimensions, String fieldName, Content contentTree); bpatel@233: bpatel@233: /** bpatel@233: * Check to see if overview details should be printed. If bpatel@233: * nocomment option set or if there is no text to be printed bpatel@233: * for deprecation info, inline comment or tags, bpatel@233: * 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@233: */ bpatel@233: public boolean shouldPrintOverview(FieldDoc field); duke@1: } duke@1: duke@1: /** duke@1: * Write the serialized form for a given field. duke@1: */ duke@1: public interface SerialMethodWriter { duke@1: duke@1: /** bpatel@766: * Get the serializable method header. bpatel@766: * bpatel@766: * @return serializable methods content tree bpatel@766: */ bpatel@766: public Content getSerializableMethodsHeader(); bpatel@766: bpatel@766: /** bpatel@766: * Get the method content header. bpatel@766: * bpatel@766: * @param isLastContent true if this is the last content to be documented bpatel@766: * @return methods content tree bpatel@766: */ bpatel@766: public Content getMethodsContentHeader(boolean isLastContent); bpatel@766: bpatel@766: /** duke@1: * Write the given heading. duke@1: * bpatel@766: * @param heading the heading to write bpatel@766: * @param serializableMethodTree content tree which will be added bpatel@766: * @return serializable methods content tree duke@1: */ bpatel@766: public Content getSerializableMethods(String heading, Content serializableMethodTree); duke@1: duke@1: /** duke@1: * Write a warning that no serializable methods exist. duke@1: * bpatel@766: * @param msg the warning to print bpatel@766: * @return no customization message tree duke@1: */ bpatel@766: public Content getNoCustomizationMsg(String msg); duke@1: duke@1: /** bpatel@766: * Adds the header. duke@1: * bpatel@766: * @param member the member to write the header for bpatel@766: * @param methodsContentTree content tree to which the header will be added duke@1: */ bpatel@766: public void addMemberHeader(MethodDoc member, Content methodsContentTree); duke@1: duke@1: /** bpatel@766: * Adds the deprecated information for this member. bpatel@766: * bpatel@766: * @param member the member to write the deprecated information for bpatel@766: * @param methodsContentTree content tree to which the deprecated bpatel@766: * information will be added duke@1: */ bpatel@766: public void addDeprecatedMemberInfo(MethodDoc member, Content methodsContentTree); duke@1: duke@1: /** bpatel@766: * Adds the description for this member. bpatel@766: * bpatel@766: * @param member the member to write the information for bpatel@766: * @param methodsContentTree content tree to which the member bpatel@766: * information will be added duke@1: */ bpatel@766: public void addMemberDescription(MethodDoc member, Content methodsContentTree); duke@1: duke@1: /** bpatel@766: * Adds the tag information for this member. bpatel@766: * bpatel@766: * @param member the member to write the tags information for bpatel@766: * @param methodsContentTree content tree to which the tags bpatel@766: * information will be added duke@1: */ bpatel@766: public void addMemberTags(MethodDoc member, Content methodsContentTree); duke@1: } duke@1: }