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