View Javadoc
1   /*
2    * Copyright (c) 2003, 2013, 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.javac.jvm.Profile;
30  import com.sun.tools.doclets.internal.toolkit.util.*;
31  
32  /**
33   * The interface for a factory creates writers.
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.4
42   */
43  
44  public interface WriterFactory {
45  
46      /**
47       * Return the writer for the constant summary.
48       *
49       * @return the writer for the constant summary.  Return null if this
50       * writer is not supported by the doclet.
51       */
52      public abstract ConstantsSummaryWriter getConstantsSummaryWriter()
53          throws Exception;
54  
55      /**
56       * Return the writer for the package summary.
57       *
58       * @param packageDoc the package being documented.
59       * @param prevPkg the previous package that was documented.
60       * @param nextPkg the next package being documented.
61       * @return the writer for the package summary.  Return null if this
62       * writer is not supported by the doclet.
63       */
64      public abstract PackageSummaryWriter getPackageSummaryWriter(PackageDoc
65          packageDoc, PackageDoc prevPkg, PackageDoc nextPkg)
66      throws Exception;
67  
68      /**
69       * Return the writer for the profile summary.
70       *
71       * @param profile the profile being documented.
72       * @param prevProfile the previous profile that was documented.
73       * @param nextProfile the next profile being documented.
74       * @return the writer for the profile summary.  Return null if this
75       * writer is not supported by the doclet.
76       */
77      public abstract ProfileSummaryWriter getProfileSummaryWriter(Profile
78          profile, Profile prevProfile, Profile nextProfile)
79      throws Exception;
80  
81      /**
82       * Return the writer for the profile package summary.
83       *
84       * @param packageDoc the profile package being documented.
85       * @param prevPkg the previous profile package that was documented.
86       * @param nextPkg the next profile package being documented.
87       * @param profile the profile being documented.
88       * @return the writer for the profile package summary.  Return null if this
89       * writer is not supported by the doclet.
90       */
91      public abstract ProfilePackageSummaryWriter getProfilePackageSummaryWriter(
92              PackageDoc packageDoc, PackageDoc prevPkg, PackageDoc nextPkg,
93              Profile profile) throws Exception;
94  
95      /**
96       * Return the writer for a class.
97       *
98       * @param classDoc the class being documented.
99       * @param prevClass the previous class that was documented.
100      * @param nextClass the next class being documented.
101      * @param classTree the class tree.
102      * @return the writer for the class.  Return null if this
103      * writer is not supported by the doclet.
104      */
105     public abstract ClassWriter getClassWriter(ClassDoc classDoc,
106         ClassDoc prevClass, ClassDoc nextClass, ClassTree classTree)
107             throws Exception;
108 
109     /**
110      * Return the writer for an annotation type.
111      *
112      * @param annotationType the type being documented.
113      * @param prevType the previous type that was documented.
114      * @param nextType the next type being documented.
115      * @return the writer for the annotation type.  Return null if this
116      * writer is not supported by the doclet.
117      */
118     public abstract AnnotationTypeWriter getAnnotationTypeWriter(
119         AnnotationTypeDoc annotationType, Type prevType, Type nextType)
120             throws Exception;
121 
122     /**
123      * Return the method writer for a given class.
124      *
125      * @param classWriter the writer for the class being documented.
126      * @return the method writer for the give class.  Return null if this
127      * writer is not supported by the doclet.
128      */
129     public abstract MethodWriter getMethodWriter(ClassWriter classWriter)
130             throws Exception;
131 
132     /**
133      * Return the annotation type field writer for a given annotation type.
134      *
135      * @param annotationTypeWriter the writer for the annotation type
136      *        being documented.
137      * @return the member writer for the given annotation type.  Return null if
138      *         this writer is not supported by the doclet.
139      */
140     public abstract AnnotationTypeFieldWriter
141             getAnnotationTypeFieldWriter(
142         AnnotationTypeWriter annotationTypeWriter) throws Exception;
143 
144     /**
145      * Return the annotation type optional member writer for a given annotation
146      * type.
147      *
148      * @param annotationTypeWriter the writer for the annotation type
149      *        being documented.
150      * @return the member writer for the given annotation type.  Return null if
151      *         this writer is not supported by the doclet.
152      */
153     public abstract AnnotationTypeOptionalMemberWriter
154             getAnnotationTypeOptionalMemberWriter(
155         AnnotationTypeWriter annotationTypeWriter) throws Exception;
156 
157     /**
158      * Return the annotation type required member writer for a given annotation type.
159      *
160      * @param annotationTypeWriter the writer for the annotation type
161      *        being documented.
162      * @return the member writer for the given annotation type.  Return null if
163      *         this writer is not supported by the doclet.
164      */
165     public abstract AnnotationTypeRequiredMemberWriter
166             getAnnotationTypeRequiredMemberWriter(
167         AnnotationTypeWriter annotationTypeWriter) throws Exception;
168 
169     /**
170      * Return the enum constant writer for a given class.
171      *
172      * @param classWriter the writer for the class being documented.
173      * @return the enum constant writer for the give class.  Return null if this
174      * writer is not supported by the doclet.
175      */
176     public abstract EnumConstantWriter getEnumConstantWriter(
177         ClassWriter classWriter) throws Exception;
178 
179     /**
180      * Return the field writer for a given class.
181      *
182      * @param classWriter the writer for the class being documented.
183      * @return the field writer for the give class.  Return null if this
184      * writer is not supported by the doclet.
185      */
186     public abstract FieldWriter getFieldWriter(ClassWriter classWriter)
187             throws Exception;
188 
189     /**
190      * Return the property writer for a given class.
191      *
192      * @param classWriter the writer for the class being documented.
193      * @return the property writer for the give class.  Return null if this
194      * writer is not supported by the doclet.
195      */
196     public abstract PropertyWriter getPropertyWriter(ClassWriter classWriter)
197             throws Exception;
198 
199     /**
200      * Return the constructor writer for a given class.
201      *
202      * @param classWriter the writer for the class being documented.
203      * @return the method writer for the give class.  Return null if this
204      * writer is not supported by the doclet.
205      */
206     public abstract ConstructorWriter getConstructorWriter(
207         ClassWriter classWriter)
208     throws Exception;
209 
210     /**
211      * Return the specified member summary writer for a given class.
212      *
213      * @param classWriter the writer for the class being documented.
214      * @param memberType  the {@link VisibleMemberMap} member type indicating
215      *                    the type of member summary that should be returned.
216      * @return the summary writer for the give class.  Return null if this
217      * writer is not supported by the doclet.
218      *
219      * @see VisibleMemberMap
220      * @throws IllegalArgumentException if memberType is unknown.
221      */
222     public abstract MemberSummaryWriter getMemberSummaryWriter(
223         ClassWriter classWriter, int memberType)
224     throws Exception;
225 
226     /**
227      * Return the specified member summary writer for a given annotation type.
228      *
229      * @param annotationTypeWriter the writer for the annotation type being
230      *                             documented.
231      * @param memberType  the {@link VisibleMemberMap} member type indicating
232      *                    the type of member summary that should be returned.
233      * @return the summary writer for the give class.  Return null if this
234      * writer is not supported by the doclet.
235      *
236      * @see VisibleMemberMap
237      * @throws IllegalArgumentException if memberType is unknown.
238      */
239     public abstract MemberSummaryWriter getMemberSummaryWriter(
240         AnnotationTypeWriter annotationTypeWriter, int memberType)
241     throws Exception;
242 
243     /**
244      * Return the writer for the serialized form.
245      *
246      * @return the writer for the serialized form.
247      */
248     public SerializedFormWriter getSerializedFormWriter() throws Exception;
249 }