Processor


1   /*
2    * Copyright (c) 2005, Rob Gordon.
3    */
4   package org.oddjob.doclet;
5   
6   import com.sun.javadoc.ClassDoc;
7   import com.sun.javadoc.Doc;
8   import com.sun.javadoc.FieldDoc;
9   import com.sun.javadoc.MethodDoc;
10  import com.sun.javadoc.SeeTag;
11  import com.sun.javadoc.Tag;
12  
13  /**
14   * A Processor is capable of processing a java ClassDoc object into
15   * a reference PageData object.
16   *   
17   * @author Rob Gordon.
18   */
19  public class Processor {
20  
21      private final ClassDoc classDoc;
22      private final String   rootDir;
23      private final JobsAndTypes jats;
24      
25      /**
26       * Create a processor.
27       *  
28       * @param jats The JobsAndTypes object to lookup up link names
29       * in.
30       * @param classDoc The classdoc the processor will process.
31       */
32      public Processor(JobsAndTypes jats, ClassDoc classDoc) {
33          this.jats = jats;
34          this.classDoc = classDoc;
35          String  [] packages = classDoc.containingPackage().name().split(("[.]"));
36          String   rootDir = "";
37          for (int i = 0; i < packages.length; ++i) {
38              rootDir = rootDir + (i == 0 ? "" : "/") + "..";
39          }
40          this.rootDir = rootDir;
41      }
42      
43      /**
44       * Process a single texgt tag from an array. This is for a property
45       * or element tag which is expected to be a single piece of text.
46       * Errors are produced if it's not. 
47       * 
48       * @param tags To process. There is expected to be either 0 or
49       * 1 tag. An error will be written to stderr if there is more.
50       * @param replacement The text to use if the tags are empty.
51       * 
52       * @return The text to use. Null if there was no tags.
53       */
54      String   processSingleTextTag(Tag[] tags, String   replacement) {
55          if (tags.length == 0) {
56              return null;
57          }
58          if (tags.length > 1) {
59              System.err.println("More than one tag for [" + replacement 
60                      + "]. Ignoring all others");
61          }
62          
63          String   text = tags[0].text();
64          
65          if (text == null || text.trim().equals("")) {
66              return replacement;
67          }
68  
69          return text;
70      }
71      
72      /**
73       * Process fields and methods
74       * 
75       * @param pageData The job page this method will populate.
76       * @param doc The field or method doc object.
77       */
78      void processFieldOrMethod(PageData pageData, Doc doc) {
79          Property prop = null;
80          Tag[] propertyTags = doc.tags("@oddjob.property");
81          Tag[] elementTags = doc.tags("@oddjob.element");
82  
83          String   propertyText = processSingleTextTag(
84                  propertyTags, doc.name());
85          String   elementText = processSingleTextTag(
86                  elementTags, doc.name());
87          
88          if (propertyText != null) {
89              prop = new Property(propertyText);
90              pageData.addAttribute(prop);
91          } 
92          else if (elementText != null) {
93              prop = new Property(elementText);
94              pageData.addElement(prop);
95          }
96          else {
97              // no property or element tag then ignore any
98              // other tags
99              return;
100         }
101         
102         Tag[] descriptionTags = doc.tags("@oddjob.description");
103         prop.setDescription(processMajorTags(descriptionTags));
104         
105         Tag[] rtags = doc.tags("@oddjob.required");
106         if (rtags.length != 0)  {
107             prop.setRequired(rtags[0].text());
108         }
109     }
110      
111     /**
112      * Process inline tags. Creates a link if appropriate.
113      * 
114      * @param inlines The inline tags.
115      * @return The processes text.
116      */
117     String   processInlineTags(Tag[] inlines) {
118         StringBuffer   buffer = new StringBuffer  ();
119         for (int i = 0; i < inlines.length; ++i) {
120             Tag  it = inlines[i];
121             if (it instanceof SeeTag) {
122                 SeeTag seeTag = (SeeTag) it;
123                 String   ref = seeTag.referencedClassName();
124                 String   otherName = jats.nameFor(ref);
125                 if (otherName == null) {
126                     otherName = ref;
127                 }
128                 buffer.append("<a HREF='" + rootDir + "/"
129                         + ref.replace('.', '/') +  ".html'>"
130                         + otherName + "</a>");
131             }
132             else {
133                 buffer.append(it.text());
134             }
135         }
136         
137         return buffer.toString();
138     }
139     
140     
141     /**
142      * Process an array of tags. This is for a tag such as description.
143      * 
144      * @param tags An array of tags
145      * @return The text equivalent.
146      */
147     String   processMajorTags(Tag[] tags) {
148         if (tags == null) {
149             return null;
150         }
151         StringBuffer   result = new StringBuffer  ();
152         for (int i = 0; i < tags.length; ++i) {
153             result.append(processInlineTags(
154                     tags[i].inlineTags()));
155         }
156         return result.toString();
157     }
158     
159     /**
160      * Process the first line from a collection of major
161      * tags such as description.
162      * 
163      * @param tags The major tags.
164      * @return The first line text.
165      */
166     String   processFirstLine(Tag[] tags) {
167         if (tags == null) {
168             return null;
169         }
170         if (tags.length == 0) {
171             return null;
172         }
173         return processInlineTags(tags[0].firstSentenceTags());
174     }
175     
176     /**
177      * Get the file name the page data should be created in.
178      * 
179      * @return The file name.
180      */
181     public String   getFileName() {
182         String   dir = classDoc.containingPackage().name().replace('.', '/');
183         return dir + "/" + classDoc.name() + ".html";
184         
185     }
186     
187     /**
188      * Process all member fields and methods including superclasses.
189      * 
190      * @param pageData
191      * @param classDoc
192      */
193     void processAllMembers(PageData pageData, ClassDoc classDoc) {
194         if (classDoc == null) {
195             return; 
196         }
197         processAllMembers(pageData, classDoc.superclass());
198         
199         FieldDoc[] fds = classDoc.fields();
200         for (int i = 0; i < fds.length; ++i) {
201             processFieldOrMethod(pageData, fds[i]);
202         }
203         MethodDoc[] mds = classDoc.methods();
204         for (int i = 0; i < mds.length; ++i) {
205             processFieldOrMethod(pageData, mds[i]);
206         }
207         
208     }
209     
210     /**
211      * Create page data for a given doclet.
212      * 
213      * @param name
214      * @param cd
215      */
216     public PageData process() {
217         String   name = jats.nameFor(fqcnFor(classDoc));
218         String   filename = getFileName();
219         System.out.println("Processing: " + name);
220         PageData pageData = new PageData(name, filename);
221         
222         Tag[] descriptionTags = classDoc.tags("@oddjob.description");
223         pageData.setFirstSentence(processFirstLine(descriptionTags));
224         pageData.setDescription(processMajorTags(descriptionTags));
225         
226         Tag[] exampleTags = classDoc.tags("@oddjob.example");
227         for (int i = 0; i < exampleTags.length; ++i) {
228             pageData.addExample(
229                     processInlineTags(exampleTags[i].inlineTags()));
230         }
231 
232         processAllMembers(pageData, classDoc);
233         return pageData;
234     }
235 
236     public static String   fqcnFor(ClassDoc classDoc) {
237         return classDoc.containingPackage().name() + "." + classDoc.name();
238     }
239     
240 }
241
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags