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