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