Mercurial > jdk8-mips64-public > langtools / file revision
src/share/classes/com/sun/tools/doclets/internal/toolkit/SerializedFormWriter.java@25e14ad23cef
src/share/classes/com/sun/tools/doclets/internal/toolkit/SerializedFormWriter.java
Wed, 10 Oct 2012 16:48:21 -0700
- author
- jjg
- date
- Wed, 10 Oct 2012 16:48:21 -0700
- changeset 1359
- 25e14ad23cef
- parent 798
- 4868a36f6fd8
- child 1364
- 8db45b13526e
- permissions
- -rw-r--r--
8000665: fix "internal API" comments on javadoc files
Reviewed-by: darcy
1 /*
2 * Copyright (c) 2003, 2012, 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 */
26 package com.sun.tools.doclets.internal.toolkit;
28 import java.io.*;
30 import com.sun.javadoc.*;
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 */
44 public interface SerializedFormWriter {
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);
54 /**
55 * Get the serialized form summaries header.
56 *
57 * @return the serialized form summary header tree
58 */
59 public Content getSerializedSummariesHeader();
61 /**
62 * Get the package serialized form header.
63 *
64 * @return the package serialized form header tree
65 */
66 public Content getPackageSerializedHeader();
68 /**
69 * Get the given package header.
70 *
71 * @param packageName the package header to write
72 * @return a content tree for the package header
73 */
74 public Content getPackageHeader(String packageName);
76 /**
77 * Get the serialized class header.
78 *
79 * @return a content tree for the serialized class header
80 */
81 public Content getClassSerializedHeader();
83 /**
84 * Get the heading for the serializable class.
85 *
86 * @param classDoc the class being processed
87 * @return a content tree for the class heading
88 */
89 public Content getClassHeader(ClassDoc classDoc);
91 /**
92 * Get the serial UID info header.
93 *
94 * @return a content tree for the serial uid info header
95 */
96 public Content getSerialUIDInfoHeader();
98 /**
99 * Adds the serial UID info.
100 *
101 * @param header the header that will show up before the UID.
102 * @param serialUID the serial UID to print.
103 * @param serialUidTree the serial UID tree to which the content will be added.
104 */
105 public void addSerialUIDInfo(String header, String serialUID,
106 Content serialUidTree);
108 /**
109 * Get the class serialize content header.
110 *
111 * @return a content tree for the class serialize content header
112 */
113 public Content getClassContentHeader();
115 /**
116 * Return an instance of a SerialFieldWriter.
117 *
118 * @return an instance of a SerialFieldWriter.
119 */
120 public SerialFieldWriter getSerialFieldWriter(ClassDoc classDoc);
122 /**
123 * Return an instance of a SerialMethodWriter.
124 *
125 * @return an instance of a SerialMethodWriter.
126 */
127 public SerialMethodWriter getSerialMethodWriter(ClassDoc classDoc);
129 /**
130 * Close the writer.
131 */
132 public abstract void close() throws IOException;
134 /**
135 * Get the serialized content.
136 *
137 * @param serializedTreeContent content for serialized data
138 * @return a content tree for serialized information
139 */
140 public Content getSerializedContent(Content serializedTreeContent);
142 /**
143 * Add the footer.
144 *
145 * @param serializedTree the serialized tree to be added
146 */
147 public void addFooter(Content serializedTree);
149 /**
150 * Print the serialized form document.
151 *
152 * @param serializedTree the content tree that will be printed
153 */
154 public abstract void printDocument(Content serializedTree);
156 /**
157 * Write the serialized form for a given field.
158 */
159 public interface SerialFieldWriter {
161 /**
162 * Get the serializable field header.
163 *
164 * @return serialized fields header content tree
165 */
166 public Content getSerializableFieldsHeader();
168 /**
169 * Get the field content header.
170 *
171 * @param isLastContent true if this is the last content to be documented
172 * @return fields header content tree
173 */
174 public Content getFieldsContentHeader(boolean isLastContent);
176 /**
177 * Get the fields content.
178 *
179 * @param heading the heading to write.
180 * @param contentTree content tree to which the heading will be added
181 * @return serializable fields content tree
182 */
183 public Content getSerializableFields(String heading, Content contentTree);
185 /**
186 * Adds the deprecated information for this member.
187 *
188 * @param field the field to document.
189 * @param contentTree content tree to which the deprecated information will be added
190 */
191 public void addMemberDeprecatedInfo(FieldDoc field, Content contentTree);
193 /**
194 * Adds the description text for this member.
195 *
196 * @param field the field to document.
197 * @param contentTree content tree to which the member description will be added
198 */
199 public void addMemberDescription(FieldDoc field, Content contentTree);
201 /**
202 * Adds the description text for this member represented by the tag.
203 *
204 * @param serialFieldTag the field to document (represented by tag).
205 * @param contentTree content tree to which the member description will be added
206 */
207 public void addMemberDescription(SerialFieldTag serialFieldTag, Content contentTree);
209 /**
210 * Adds the tag information for this member.
211 *
212 * @param field the field to document.
213 * @param contentTree content tree to which the member tags will be added
214 */
215 public void addMemberTags(FieldDoc field, Content contentTree);
217 /**
218 * Adds the member header.
219 *
220 * @param fieldType the type of the field.
221 * @param fieldTypeStr the type of the field in string format. We will
222 * print this out if we can't link to the type.
223 * @param fieldDimensions the dimensions of the field.
224 * @param fieldName the name of the field.
225 * @param contentTree content tree to which the member header will be added
226 */
227 public void addMemberHeader(ClassDoc fieldType, String fieldTypeStr,
228 String fieldDimensions, String fieldName, Content contentTree);
230 /**
231 * Check to see if overview details should be printed. If
232 * nocomment option set or if there is no text to be printed
233 * for deprecation info, inline comment or tags,
234 * do not print overview details.
235 *
236 * @param field the field to check overview details for.
237 * @return true if overview details need to be printed
238 */
239 public boolean shouldPrintOverview(FieldDoc field);
240 }
242 /**
243 * Write the serialized form for a given field.
244 */
245 public interface SerialMethodWriter {
247 /**
248 * Get the serializable method header.
249 *
250 * @return serializable methods content tree
251 */
252 public Content getSerializableMethodsHeader();
254 /**
255 * Get the method content header.
256 *
257 * @param isLastContent true if this is the last content to be documented
258 * @return methods content tree
259 */
260 public Content getMethodsContentHeader(boolean isLastContent);
262 /**
263 * Write the given heading.
264 *
265 * @param heading the heading to write
266 * @param serializableMethodTree content tree which will be added
267 * @return serializable methods content tree
268 */
269 public Content getSerializableMethods(String heading, Content serializableMethodTree);
271 /**
272 * Write a warning that no serializable methods exist.
273 *
274 * @param msg the warning to print
275 * @return no customization message tree
276 */
277 public Content getNoCustomizationMsg(String msg);
279 /**
280 * Adds the header.
281 *
282 * @param member the member to write the header for
283 * @param methodsContentTree content tree to which the header will be added
284 */
285 public void addMemberHeader(MethodDoc member, Content methodsContentTree);
287 /**
288 * Adds the deprecated information for this member.
289 *
290 * @param member the member to write the deprecated information for
291 * @param methodsContentTree content tree to which the deprecated
292 * information will be added
293 */
294 public void addDeprecatedMemberInfo(MethodDoc member, Content methodsContentTree);
296 /**
297 * Adds the description for this member.
298 *
299 * @param member the member to write the information for
300 * @param methodsContentTree content tree to which the member
301 * information will be added
302 */
303 public void addMemberDescription(MethodDoc member, Content methodsContentTree);
305 /**
306 * Adds the tag information for this member.
307 *
308 * @param member the member to write the tags information for
309 * @param methodsContentTree content tree to which the tags
310 * information will be added
311 */
312 public void addMemberTags(MethodDoc member, Content methodsContentTree);
313 }
314 }
