1 /* 2 * Copyright (c) 2003, 2015, 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 com.sun.tools.doclets.internal.toolkit; 27 28 import java.io.*; 29 30 import com.sun.javadoc.*; 31 32 /** 33 * The interface for writing serialized form output. 34 * 35 * <p><b>This is NOT part of any supported API. 36 * If you write code that depends on this, you do so at your own risk. 37 * This code and its internal interfaces are subject to change or 38 * deletion without notice.</b> 39 * 40 * @author Jamie Ho 41 * @since 1.5 42 */ 43 44 public interface SerializedFormWriter { 45 46 /** 47 * Get the header. 48 * 49 * @param header the header to write. 50 * @return the header content tree 51 */ 52 public Content getHeader(String header); 53 54 /** 55 * Get the serialized form summaries header. 56 * 57 * @return the serialized form summary header tree 58 */ 59 public Content getSerializedSummariesHeader(); 60 61 /** 62 * Get the package serialized form header. 63 * 64 * @return the package serialized form header tree 65 */ 66 public Content getPackageSerializedHeader(); 67 68 /** 69 * Add the serialized tree per package to the serialized summaries tree. 70 * 71 * @param serializedSummariesTree the serialized tree to which the package serialized tree will be added 72 * @param packageSerializedTree the serialized tree per package that needs to be added 73 */ 74 public void addPackageSerializedTree(Content serializedSummariesTree, Content packageSerializedTree); 75 76 /** 77 * Get the given package header. 78 * 79 * @param packageName the package header to write 80 * @return a content tree for the package header 81 */ 82 public Content getPackageHeader(String packageName); 83 84 /** 85 * Get the serialized class header. 86 * 87 * @return a content tree for the serialized class header 88 */ 89 public Content getClassSerializedHeader(); 90 91 /** 92 * Get the heading for the serializable class. 93 * 94 * @param classDoc the class being processed 95 * @return a content tree for the class heading 96 */ 97 public Content getClassHeader(ClassDoc classDoc); 98 99 /** 100 * Get the serial UID info header. 101 * 102 * @return a content tree for the serial uid info header 103 */ 104 public Content getSerialUIDInfoHeader(); 105 106 /** 107 * Adds the serial UID info. 108 * 109 * @param header the header that will show up before the UID. 110 * @param serialUID the serial UID to print. 111 * @param serialUidTree the serial UID tree to which the content will be added. 112 */ 113 public void addSerialUIDInfo(String header, String serialUID, 114 Content serialUidTree); 115 116 /** 117 * Get the class serialize content header. 118 * 119 * @return a content tree for the class serialize content header 120 */ 121 public Content getClassContentHeader(); 122 123 /** 124 * Return an instance of a SerialFieldWriter. 125 * 126 * @return an instance of a SerialFieldWriter. 127 */ 128 public SerialFieldWriter getSerialFieldWriter(ClassDoc classDoc); 129 130 /** 131 * Return an instance of a SerialMethodWriter. 132 * 133 * @return an instance of a SerialMethodWriter. 134 */ 135 public SerialMethodWriter getSerialMethodWriter(ClassDoc classDoc); 136 137 /** 138 * Close the writer. 139 */ 140 public abstract void close() throws IOException; 141 142 /** 143 * Get the serialized content. 144 * 145 * @param serializedTreeContent content for serialized data 146 * @return a content tree for serialized information 147 */ 148 public Content getSerializedContent(Content serializedTreeContent); 149 150 /** 151 * Add the footer. 152 * 153 * @param serializedTree the serialized tree to be added 154 */ 155 public void addFooter(Content serializedTree); 156 157 /** 158 * Print the serialized form document. 159 * 160 * @param serializedTree the content tree that will be printed 161 */ 162 public abstract void printDocument(Content serializedTree) throws IOException; 163 164 /** 165 * Write the serialized form for a given field. 166 */ 167 public interface SerialFieldWriter { 168 169 /** 170 * Get the serializable field header. 171 * 172 * @return serialized fields header content tree 173 */ 174 public Content getSerializableFieldsHeader(); 175 176 /** 177 * Get the field content header. 178 * 179 * @param isLastContent true if this is the last content to be documented 180 * @return fields header content tree 181 */ 182 public Content getFieldsContentHeader(boolean isLastContent); 183 184 /** 185 * Get the fields content. 186 * 187 * @param heading the heading to write. 188 * @param contentTree content tree to which the heading will be added 189 * @return serializable fields content tree 190 */ 191 public Content getSerializableFields(String heading, Content contentTree); 192 193 /** 194 * Adds the deprecated information for this member. 195 * 196 * @param field the field to document. 197 * @param contentTree content tree to which the deprecated information will be added 198 */ 199 public void addMemberDeprecatedInfo(FieldDoc field, Content contentTree); 200 201 /** 202 * Adds the description text for this member. 203 * 204 * @param field the field to document. 205 * @param contentTree content tree to which the member description will be added 206 */ 207 public void addMemberDescription(FieldDoc field, Content contentTree); 208 209 /** 210 * Adds the description text for this member represented by the tag. 211 * 212 * @param serialFieldTag the field to document (represented by tag). 213 * @param contentTree content tree to which the member description will be added 214 */ 215 public void addMemberDescription(SerialFieldTag serialFieldTag, Content contentTree); 216 217 /** 218 * Adds the tag information for this member. 219 * 220 * @param field the field to document. 221 * @param contentTree content tree to which the member tags will be added 222 */ 223 public void addMemberTags(FieldDoc field, Content contentTree); 224 225 /** 226 * Adds the member header. 227 * 228 * @param fieldType the type of the field. 229 * @param fieldTypeStr the type of the field in string format. We will 230 * print this out if we can't link to the type. 231 * @param fieldDimensions the dimensions of the field. 232 * @param fieldName the name of the field. 233 * @param contentTree content tree to which the member header will be added 234 */ 235 public void addMemberHeader(ClassDoc fieldType, String fieldTypeStr, 236 String fieldDimensions, String fieldName, Content contentTree); 237 238 /** 239 * Check to see if overview details should be printed. If 240 * nocomment option set or if there is no text to be printed 241 * for deprecation info, inline comment or tags, 242 * do not print overview details. 243 * 244 * @param field the field to check overview details for. 245 * @return true if overview details need to be printed 246 */ 247 public boolean shouldPrintOverview(FieldDoc field); 248 } 249 250 /** 251 * Write the serialized form for a given field. 252 */ 253 public interface SerialMethodWriter { 254 255 /** 256 * Get the serializable method header. 257 * 258 * @return serializable methods content tree 259 */ 260 public Content getSerializableMethodsHeader(); 261 262 /** 263 * Get the method content header. 264 * 265 * @param isLastContent true if this is the last content to be documented 266 * @return methods content tree 267 */ 268 public Content getMethodsContentHeader(boolean isLastContent); 269 270 /** 271 * Write the given heading. 272 * 273 * @param heading the heading to write 274 * @param serializableMethodTree content tree which will be added 275 * @return serializable methods content tree 276 */ 277 public Content getSerializableMethods(String heading, Content serializableMethodTree); 278 279 /** 280 * Write a warning that no serializable methods exist. 281 * 282 * @param msg the warning to print 283 * @return no customization message tree 284 */ 285 public Content getNoCustomizationMsg(String msg); 286 287 /** 288 * Adds the header. 289 * 290 * @param member the member to write the header for 291 * @param methodsContentTree content tree to which the header will be added 292 */ 293 public void addMemberHeader(MethodDoc member, Content methodsContentTree); 294 295 /** 296 * Adds the deprecated information for this member. 297 * 298 * @param member the member to write the deprecated information for 299 * @param methodsContentTree content tree to which the deprecated 300 * information will be added 301 */ 302 public void addDeprecatedMemberInfo(MethodDoc member, Content methodsContentTree); 303 304 /** 305 * Adds the description for this member. 306 * 307 * @param member the member to write the information for 308 * @param methodsContentTree content tree to which the member 309 * information will be added 310 */ 311 public void addMemberDescription(MethodDoc member, Content methodsContentTree); 312 313 /** 314 * Adds the tag information for this member. 315 * 316 * @param member the member to write the tags information for 317 * @param methodsContentTree content tree to which the tags 318 * information will be added 319 */ 320 public void addMemberTags(MethodDoc member, Content methodsContentTree); 321 } 322 }