KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > go > beandoc > BeanDoc


1 /* ====================================================================
2  * BeanDoc - Copyright (c) 1997-2000 GO.com
3  * ====================================================================
4  * The Tea Software License, Version 1.0
5  *
6  * Copyright (c) 2000 GO.com. All rights reserved.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * 1. Redistributions of source code must retain the above copyright
13  * notice, this list of conditions and the following disclaimer.
14  *
15  * 2. Redistributions in binary form must reproduce the above copyright
16  * notice, this list of conditions and the following disclaimer in
17  * the documentation and/or other materials provided with the
18  * distribution.
19  *
20  * 3. The end-user documentation included with the redistribution,
21  * if any, must include the following acknowledgment:
22  * "This product includes software developed by GO.com
23  * (http://opensource.go.com/)."
24  * Alternately, this acknowledgment may appear in the software itself,
25  * if and wherever such third-party acknowledgments normally appear.
26  *
27  * 4. The names "Tea", "TeaServlet", "Kettle", "Trove", BeanDoc and "GO.com"
28  * must not be used to endorse or promote products derived from this
29  * software without prior written permission. For written
30  * permission, please contact opensource@go.com.
31  *
32  * 5. Products derived from this software may not be called "Tea",
33  * "TeaServlet", "Kettle", "Trove" or BeanDoc, nor may "Tea", "TeaServlet",
34  * "Kettle", "Trove" or BeanDoc appear in their name, without prior written
35  * permission of GO.com.
36  *
37  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
38  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
39  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
40  * DISCLAIMED. IN NO EVENT SHALL GO.COM OR ITS CONTRIBUTORS BE LIABLE
41  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
42  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
43  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
44  * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
45  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
46  * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
47  * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
48  * ====================================================================
49  *
50  * For more information about Tea, please see http://opensource.go.com/.
51  */
52
53 package com.go.beandoc;
54
55 import com.go.beandoc.teadoc.*;
56
57 import java.io.*;
58
59 import com.go.tea.runtime.TemplateLoader;
60
61 /******************************************************************************
62  * The BeanDoc doclet generates "BeanInfo.java" files for each of the
63  * classes and interfaces to be documented. The Java file is created using
64  * an accompanying Tea template.
65  * <p>
66  * BeanDoc makes use of the teadoc sub-package in order to wrap the classes
67  * of the doclet API to provide a Tea-friendly JavaBean interface for each
68  * class.
69  *
70  * @author Mark Masse
71  * @version
72  * <!--$$Revision:--> 8 <!-- $-->, <!--$$JustDate:--> 8/23/00 <!-- $-->
73  */
74 public class BeanDoc extends com.sun.javadoc.Doclet {
75
76     /** The class name of the Tea template */
77     private static final String JavaDoc DEFAULT_TEMPLATE_CLASS_NAME =
78         "com.go.beandoc.template.BeanInfo";
79
80     //
81 // static methods
82 //
83
84     /**
85      * Starts the BeanDoc doclet. Called by the javadoc tool.
86      */
87     public static boolean start(com.sun.javadoc.RootDoc root) {
88         try {
89             BeanDoc doclet = new BeanDoc(root);
90             doclet.start();
91         }
92         catch (Exception JavaDoc e) {
93             e.printStackTrace();
94             return false;
95         }
96
97         return true;
98     }
99
100     
101     public static int optionLength(String JavaDoc option) {
102         if (option.equals("-d")) {
103             return 2;
104         }
105         else {
106             return 0;
107         }
108     }
109
110     //
111 // Instance fields
112 //
113
114     private RootDoc mRootDoc;
115     private File mDest;
116     private String JavaDoc mTemplateClassName;
117     private TemplateLoader.Template mTemplate;
118
119     //
120 // Instance methods
121 //
122
123     /**
124      * Creates a new BeanDoc with the specified RootDoc object.
125      */
126     public BeanDoc(com.sun.javadoc.RootDoc root) throws Exception JavaDoc {
127
128         String JavaDoc[][] options = root.options();
129         String JavaDoc dest = ".";
130
131         for (int i = 0; i < options.length; i++) {
132             String JavaDoc[] values = options[i];
133             String JavaDoc key = values[0];
134
135             if (key.equals("-d") && values.length > 1) {
136                 dest = values[1];
137             }
138         }
139
140         // TODO: Allow template class name to be specified as a param?
141 init(root, dest, DEFAULT_TEMPLATE_CLASS_NAME);
142     }
143
144     /**
145      * Generates BeanInfo.java files for each of the ClassDocs in the
146      * RootDoc.
147      */
148     public void start() {
149
150         ClassDoc[] classDocs = mRootDoc.getClasses();
151
152         for (int i = 0; i < classDocs.length; i++) {
153
154             ClassDoc classDoc = classDocs[i];
155             if (!accept(classDoc)) {
156                 continue;
157             }
158             
159             try {
160                 generateBeanInfo(classDoc);
161             }
162             catch (RuntimeException JavaDoc e) {
163                 throw e;
164             }
165             catch (Exception JavaDoc e) {
166                 e.printStackTrace();
167                 throw new RuntimeException JavaDoc(e.toString());
168             }
169         }
170     }
171
172     /**
173      * Returns the RootDoc object
174      */
175     public RootDoc getRootDoc() {
176         return mRootDoc;
177     }
178
179     
180     /**
181      * Prints an error message
182      */
183     public void printError(String JavaDoc msg) {
184         mRootDoc.printError(msg);
185     }
186
187     /**
188      * Prints an warning message
189      */
190     public void printWarning(String JavaDoc msg) {
191         mRootDoc.printWarning(msg);
192     }
193
194     /**
195      * Prints an notice message
196      */
197     public void printNotice(String JavaDoc msg) {
198         mRootDoc.printNotice(msg);
199     }
200
201     //
202 // Non-public methods
203 //
204
205
206     /**
207      * Initializes the BeanDoc instance.
208      */
209     protected void init(com.sun.javadoc.RootDoc root,
210                       String JavaDoc dest,
211                       String JavaDoc templateClassName) throws Exception JavaDoc {
212         
213         mRootDoc = new RootDoc(root);
214
215         mDest = new File(dest);
216         mDest.mkdirs();
217
218         mTemplateClassName = templateClassName;
219         if (mTemplateClassName == null) {
220             printWarning("No template name");
221             return;
222         }
223
224         String JavaDoc[] templatePath = ClassDoc.parseClassName(mTemplateClassName);
225         
226         //
227 // Load the specified template class
228 //
229
230         TemplateLoader loader =
231             new TemplateLoader(getClass().getClassLoader(),
232                                templatePath[0]);
233
234         mTemplate = loader.getTemplate(templatePath[1]);
235
236         Class JavaDoc[] params = mTemplate.getParameterTypes();
237         if (params.length != 1 || params[0] != ClassDoc.class) {
238             printError("Template has incorrect param signature");
239         }
240     }
241
242     /**
243      * Returns true if the ClassDoc should be documented
244      */
245     protected boolean accept(ClassDoc classDoc) {
246         return (classDoc.isPublic() &&
247                 !classDoc.getTypeName().endsWith("BeanInfo"));
248     }
249
250
251     /**
252      * Using a Tea template, generates a "BeanInfo.java" file for the
253      * specified ClassDoc.
254      */
255     private void generateBeanInfo(ClassDoc classDoc) throws Exception JavaDoc {
256
257         String JavaDoc beanInfoJavaFileName =
258             classDoc.getTypeNameForFile() + "BeanInfo.java";
259
260         String JavaDoc beanInfoJavaFilePath = beanInfoJavaFileName;
261         
262         String JavaDoc packageName = classDoc.getPackageName();
263         
264         if (packageName != null) {
265             // Create the file path using the package
266 beanInfoJavaFilePath =
267                 packageName.replace('.', '/') + "/" + beanInfoJavaFileName;
268         }
269
270         File dest = null;
271         
272         if (mDest != null) {
273             dest = new File(mDest, beanInfoJavaFilePath);
274         }
275         else {
276             dest = new File(beanInfoJavaFilePath);
277         }
278
279         if (dest.exists()) {
280             if (dest.canWrite()) {
281                 printWarning("File exists: " + beanInfoJavaFileName);
282             }
283             else {
284                 printWarning("File exists and cannot be written: " +
285                              beanInfoJavaFileName);
286                 return;
287             }
288         }
289
290         BeanDocContext context = null;
291         try {
292
293             context = new BeanDocContext(this, dest);
294
295             if (mTemplate != null) {
296                 printNotice("Creating BeanInfo: " + beanInfoJavaFilePath);
297                 mTemplate.execute(context, new Object JavaDoc[] { classDoc });
298             }
299             else {
300                 printWarning("No template");
301             }
302         }
303         finally {
304             if (context != null) {
305                 context.close();
306             }
307         }
308     }
309
310 }
311
312
Popular Tags