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 */
25
26 package com.sun.tools.doclets.internal.toolkit;
27
28 import com.sun.javadoc.*;
29 import com.sun.tools.doclets.internal.toolkit.util.*;
30
31 /**
32 * The interface for a factory creates writers.
33 *
34 * <p><b>This is NOT part of any supported API.
35 * If you write code that depends on this, you do so at your own risk.
36 * This code and its internal interfaces are subject to change or
37 * deletion without notice.</b>
38 *
39 * @author Jamie Ho
40 * @since 1.4
41 */
42
43 public interface WriterFactory {
44
45 /**
46 * Return the writer for the constant summary.
47 *
48 * @return the writer for the constant summary. Return null if this
49 * writer is not supported by the doclet.
50 */
51 public abstract ConstantsSummaryWriter getConstantsSummaryWriter()
52 throws Exception;
53
54 /**
55 * Return the writer for the package summary.
56 *
57 * @param packageDoc the package being documented.
58 * @param prevPkg the previous package that was documented.
59 * @param nextPkg the next package being documented.
60 * @return the writer for the package summary. Return null if this
61 * writer is not supported by the doclet.
62 */
63 public abstract PackageSummaryWriter getPackageSummaryWriter(PackageDoc
64 packageDoc, PackageDoc prevPkg, PackageDoc nextPkg)
65 throws Exception;
66
67 /**
68 * Return the writer for a class.
69 *
70 * @param classDoc the class being documented.
71 * @param prevClass the previous class that was documented.
72 * @param nextClass the next class being documented.
73 * @param classTree the class tree.
74 * @return the writer for the class. Return null if this
75 * writer is not supported by the doclet.
76 */
77 public abstract ClassWriter getClassWriter(ClassDoc classDoc,
78 ClassDoc prevClass, ClassDoc nextClass, ClassTree classTree)
79 throws Exception;
80
81 /**
82 * Return the writer for an annotation type.
83 *
84 * @param annotationType the type being documented.
85 * @param prevType the previous type that was documented.
86 * @param nextType the next type being documented.
87 * @return the writer for the annotation type. Return null if this
88 * writer is not supported by the doclet.
89 */
90 public abstract AnnotationTypeWriter getAnnotationTypeWriter(
91 AnnotationTypeDoc annotationType, Type prevType, Type nextType)
92 throws Exception;
93
94 /**
95 * Return the method writer for a given class.
96 *
97 * @param classWriter the writer for the class being documented.
98 * @return the method writer for the give class. Return null if this
99 * writer is not supported by the doclet.
100 */
101 public abstract MethodWriter getMethodWriter(ClassWriter classWriter)
102 throws Exception;
103
104 /**
105 * Return the annotation type optional member writer for a given annotation
106 * type.
107 *
108 * @param annotationTypeWriter the writer for the annotation type
109 * being documented.
110 * @return the member writer for the given annotation type. Return null if
111 * this writer is not supported by the doclet.
112 */
113 public abstract AnnotationTypeOptionalMemberWriter
114 getAnnotationTypeOptionalMemberWriter(
115 AnnotationTypeWriter annotationTypeWriter) throws Exception;
116
117 /**
118 * Return the annotation type required member writer for a given annotation type.
119 *
120 * @param annotationTypeWriter the writer for the annotation type
121 * being documented.
122 * @return the member writer for the given annotation type. Return null if
123 * this writer is not supported by the doclet.
124 */
125 public abstract AnnotationTypeRequiredMemberWriter
126 getAnnotationTypeRequiredMemberWriter(
127 AnnotationTypeWriter annotationTypeWriter) throws Exception;
128
129 /**
130 * Return the enum constant writer for a given class.
131 *
132 * @param classWriter the writer for the class being documented.
133 * @return the enum constant writer for the give class. Return null if this
134 * writer is not supported by the doclet.
135 */
136 public abstract EnumConstantWriter getEnumConstantWriter(
137 ClassWriter classWriter) throws Exception;
138
139 /**
140 * Return the field writer for a given class.
141 *
142 * @param classWriter the writer for the class being documented.
143 * @return the field writer for the give class. Return null if this
144 * writer is not supported by the doclet.
145 */
146 public abstract FieldWriter getFieldWriter(ClassWriter classWriter)
147 throws Exception;
148
149 /**
150 * Return the constructor writer for a given class.
151 *
152 * @param classWriter the writer for the class being documented.
153 * @return the method writer for the give class. Return null if this
154 * writer is not supported by the doclet.
155 */
156 public abstract ConstructorWriter getConstructorWriter(
157 ClassWriter classWriter)
158 throws Exception;
159
160 /**
161 * Return the specified member summary writer for a given class.
162 *
163 * @param classWriter the writer for the class being documented.
164 * @param memberType the {@link VisibleMemberMap} member type indicating
165 * the type of member summary that should be returned.
166 * @return the summary writer for the give class. Return null if this
167 * writer is not supported by the doclet.
168 *
169 * @see VisibleMemberMap
170 * @throws IllegalArgumentException if memberType is unknown.
171 */
172 public abstract MemberSummaryWriter getMemberSummaryWriter(
173 ClassWriter classWriter, int memberType)
174 throws Exception;
175
176 /**
177 * Return the specified member summary writer for a given annotation type.
178 *
179 * @param annotationTypeWriter the writer for the annotation type being
180 * documented.
181 * @param memberType the {@link VisibleMemberMap} member type indicating
182 * the type of member summary that should be returned.
183 * @return the summary writer for the give class. Return null if this
184 * writer is not supported by the doclet.
185 *
186 * @see VisibleMemberMap
187 * @throws IllegalArgumentException if memberType is unknown.
188 */
189 public abstract MemberSummaryWriter getMemberSummaryWriter(
190 AnnotationTypeWriter annotationTypeWriter, int memberType)
191 throws Exception;
192
193 /**
194 * Return the writer for the serialized form.
195 *
196 * @return the writer for the serialized form.
197 */
198 public SerializedFormWriter getSerializedFormWriter() throws Exception;
199 }