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