APIHandler


1   package jdiff;
2   
3   import java.io.*;
4   import java.util.*;
5   
6   /* For SAX parsing in APIHandler */
7   import org.xml.sax.Attributes  ;
8   import org.xml.sax.SAXException  ;
9   import org.xml.sax.SAXParseException  ;
10  import org.xml.sax.XMLReader  ;
11  import org.xml.sax.helpers.DefaultHandler  ;
12  
13  /**
14   * Handle the parsing of an XML file and the generation of an API object.
15   *
16   * See the file LICENSE.txt for copyright details.
17   * @author Matthew Doar, doar@pobox.com
18   */
19  class APIHandler extends DefaultHandler   {
20  
21      /** The API object which is populated from the XML file. */
22      public API api_;
23  
24      /** Default constructor. */
25      public APIHandler(API api, boolean createGlobalComments) {
26          api_ = api;
27          createGlobalComments_ = createGlobalComments;
28          tagStack = new LinkedList();
29      }   
30  
31      /** If set, then check that each comment is a sentence. */
32      public static boolean checkIsSentence = false;
33  
34      /** 
35       * Contains the name of the current package element type
36       * where documentation is being added. Also used as the level
37       * at which to add documentation into an element, i.e. class-level
38       * or package-level.
39       */
40      private String   currentElement = null;
41  
42      /** If set, then create the global list of comments. */
43      private boolean createGlobalComments_ = false;
44  
45      /** Set if inside a doc element. */
46      private boolean inDoc = false;
47  
48      /** The current comment text being assembled. */
49      private String   currentText = null;
50  
51      /** The current text from deprecation, null if empty. */
52      private String   currentDepText = null;
53  
54      /** 
55       * The stack of SingleComment objects awaiting the comment text 
56       * currently being assembled. 
57       */
58      private LinkedList tagStack = null;
59  
60      /** Called at the start of the document. */
61      public void startDocument() {
62      }
63      
64      /** Called when the end of the document is reached. */
65      public void endDocument() {
66          if (trace)
67              api_.dump();
68          System.out.println(" finished");
69      }
70  
71      /** Called when a new element is started. */
72      public void startElement(java.lang.String   uri, java.lang.String   localName,
73                               java.lang.String   qName, Attributes   attributes) {
74       // The change to JAXP compliance produced this change.
75      if (localName.equals(""))
76          localName = qName;
77          if (localName.compareTo("api") == 0) {
78              String   apiName = attributes.getValue("name");
79              String   version = attributes.getValue("jdversion"); // Not used yet
80              XMLToAPI.nameAPI(apiName);
81          } else if (localName.compareTo("package") == 0) {
82              currentElement = localName;
83              String   pkgName = attributes.getValue("name");
84              XMLToAPI.addPackage(pkgName);
85          } else if (localName.compareTo("class") == 0) {
86              currentElement = localName;
87              String   className = attributes.getValue("name");
88              String   parentName = attributes.getValue("extends");
89              boolean isAbstract = false;
90              if (attributes.getValue("abstract").compareTo("true") == 0)
91                  isAbstract = true;
92              XMLToAPI.addClass(className, parentName, isAbstract, getModifiers(attributes));
93          } else if (localName.compareTo("interface") == 0) {
94              currentElement = localName;
95              String   className = attributes.getValue("name");
96              String   parentName = attributes.getValue("extends");
97              boolean isAbstract = false;
98              if (attributes.getValue("abstract").compareTo("true") == 0)
99                  isAbstract = true;
100             XMLToAPI.addInterface(className, parentName, isAbstract, getModifiers(attributes));
101         } else if (localName.compareTo("implements") == 0) {
102             String   interfaceName = attributes.getValue("name");
103             XMLToAPI.addImplements(interfaceName);
104         } else if (localName.compareTo("constructor") == 0) {
105             currentElement = localName;
106             String   ctorType = attributes.getValue("type");
107             XMLToAPI.addCtor(ctorType, getModifiers(attributes));
108         } else if (localName.compareTo("method") == 0) {
109             currentElement = localName;
110             String   methodName = attributes.getValue("name");
111             String   returnType = attributes.getValue("return");
112             boolean isAbstract = false;
113             if (attributes.getValue("abstract").compareTo("true") == 0)
114                 isAbstract = true;
115             boolean isNative = false;
116             if (attributes.getValue("native").compareTo("true") == 0)
117                 isNative = true;
118             boolean isSynchronized = false;
119             if (attributes.getValue("synchronized").compareTo("true") == 0)
120                 isSynchronized = true;
121             XMLToAPI.addMethod(methodName, returnType, isAbstract, isNative, 
122                                isSynchronized, getModifiers(attributes));
123         } else if (localName.compareTo("field") == 0) {
124             currentElement = localName;
125             String   fieldName = attributes.getValue("name");
126             String   fieldType = attributes.getValue("type");
127             boolean isTransient = false;
128             if (attributes.getValue("transient").compareTo("true") == 0)
129                 isTransient = true;
130             boolean isVolatile = false;
131             if (attributes.getValue("volatile").compareTo("true") == 0)
132                 isVolatile = true;
133             String   value = attributes.getValue("value");
134             XMLToAPI.addField(fieldName, fieldType, isTransient, isVolatile, 
135                               value, getModifiers(attributes));
136         } else if (localName.compareTo("param") == 0) {
137             String   paramName = attributes.getValue("name");
138             String   paramType = attributes.getValue("type");
139             XMLToAPI.addParam(paramName, paramType);
140         } else if (localName.compareTo("exception") == 0) {
141             String   paramName = attributes.getValue("name");
142             String   paramType = attributes.getValue("type");
143             XMLToAPI.addException(paramName, paramType, currentElement);
144         } else if (localName.compareTo("doc") == 0) {
145             inDoc = true;
146             currentText = null;
147         } else {
148             if (inDoc) {
149                 // Start of an element, probably an HTML element
150                 addStartTagToText(localName, attributes);
151             } else {
152                 System.out.println("Error: unknown element type: " + localName);
153                 System.exit(-1);
154             }
155         }
156     }
157     
158     /** Called when the end of an element is reached. */
159     public void endElement(java.lang.String   uri, java.lang.String   localName, 
160                            java.lang.String   qName) {
161     if (localName.equals(""))
162         localName = qName;
163         // Deal with the end of doc blocks
164         if (localName.compareTo("doc") == 0) {
165             inDoc = false;
166             // Add the assembled comment text to the appropriate current
167             // program element, as determined by currentElement.
168             addTextToComments();
169         } else if (inDoc) {
170             // An element was found inside the HTML text
171             addEndTagToText(localName);
172         } else if (currentElement.compareTo("constructor") == 0 && 
173                    localName.compareTo("constructor") == 0) {
174             currentElement = "class";
175         } else if (currentElement.compareTo("method") == 0 && 
176                    localName.compareTo("method") == 0) {
177             currentElement = "class";
178         } else if (currentElement.compareTo("field") == 0 && 
179                    localName.compareTo("field") == 0) {
180             currentElement = "class";
181         } else if (currentElement.compareTo("class") == 0 ||
182                    currentElement.compareTo("interface") == 0) {
183             // Feature request 510307 and bug 517383: duplicate comment ids.
184             // The end of a member element leaves the currentElement at the 
185             // "class" level, but the next class may in fact be an interface
186             // and so the currentElement here will be "interface".
187             if (localName.compareTo("class") == 0 || 
188                 localName.compareTo("interface") == 0) {
189                 currentElement = "package";
190             }
191         }
192     }
193 
194     /** Called to process text. */
195     public void characters(char[] ch, int start, int length) {
196          if (inDoc) {
197             String   chunk = new String  (ch, start, length);
198             if (currentText == null)
199                 currentText = chunk;
200             else
201                 currentText += chunk;
202          }
203     }
204 
205     /** 
206      * Trim the current text, check it is a sentence and add it to the
207      * current program element. 
208      */
209     public void addTextToComments() {
210         // Eliminate any whitespace at each end of the text.
211         currentText = currentText.trim();        
212         // Convert any @link tags to HTML links.
213         if (convertAtLinks) {
214             currentText = Comments.convertAtLinks(currentText, currentElement, 
215                                                   api_.currPkg_, api_.currClass_);
216         }
217         // Check that it is a sentence
218         if (checkIsSentence && !currentText.endsWith(".") && 
219             currentText.compareTo(Comments.placeHolderText) != 0) {
220             System.out.println("Warning: text of comment does not end in a period: " + currentText);
221         }
222         // The construction of the commentID assumes that the 
223         // documentation is the final element to be parsed. The format matches
224         // the format used in the report generator to look up comments in the
225         // the existingComments object.
226         String   commentID = null;
227         // Add this comment to the current API element.
228         if (currentElement.compareTo("package") == 0) {
229             api_.currPkg_.doc_ = currentText;
230             commentID = api_.currPkg_.name_;
231         } else if (currentElement.compareTo("class") == 0 ||
232                    currentElement.compareTo("interface") == 0) {
233             api_.currClass_.doc_ = currentText;
234             commentID = api_.currPkg_.name_ + "." + api_.currClass_.name_;
235         } else if (currentElement.compareTo("constructor") == 0) {
236             api_.currCtor_.doc_ = currentText;
237             commentID = api_.currPkg_.name_ + "." + api_.currClass_.name_ +
238                 ".ctor_changed(";
239             if (api_.currCtor_.type_.compareTo("void") == 0)
240                 commentID = commentID + ")";
241             else
242                 commentID = commentID + api_.currCtor_.type_ + ")";
243         } else if (currentElement.compareTo("method") == 0) {
244             api_.currMethod_.doc_ = currentText;
245             commentID = api_.currPkg_.name_ + "." + api_.currClass_.name_ +
246                 "." + api_.currMethod_.name_ + "_changed(" + 
247                 api_.currMethod_.getSignature() + ")";
248         } else if (currentElement.compareTo("field") == 0) {
249             api_.currField_.doc_ = currentText;
250             commentID = api_.currPkg_.name_ + "." + api_.currClass_.name_ +
251                 "." + api_.currField_.name_;
252         }            
253         // Add to the list of possible comments for use when an
254         // element has changed (not removed or added).
255         if (createGlobalComments_ && commentID != null) {
256             String   ct = currentText;
257             // Use any deprecation text as the possible comment, ignoring 
258             // any other comment text.
259             if (currentDepText != null) {
260                 ct = currentDepText;
261                 currentDepText = null; // Never reuse it. Bug 469794
262             }
263             String   ctOld = (String  )(Comments.allPossibleComments.put(commentID, ct));
264             if (ctOld != null) {
265                 System.out.println("Error: duplicate comment id: " + commentID);
266                 System.exit(5);
267             }
268         }
269     }
270 
271     /** 
272      * Add the start tag to the current comment text. 
273      */
274     public void addStartTagToText(String   localName, Attributes   attributes) {
275         // Need to insert the HTML tag into the current text
276         String   currentHTMLTag = localName;
277         // Save the tag in a stack
278         tagStack.add(currentHTMLTag);
279         String   tag = "<" + currentHTMLTag;
280         // Now add all the attributes into the current text
281         int len = attributes.getLength();
282         for (int i = 0; i < len; i++) {
283             String   name = attributes.getLocalName(i);
284             String   value = attributes.getValue(i);
285             tag += " " + name + "=\"" + value+ "\"";
286         }
287 
288         // End the tag
289         if (Comments.isMinimizedTag(currentHTMLTag)) {
290             tag += "/>";
291         } else {
292             tag += ">";
293         }
294         // Now insert the HTML tag into the current text
295         if (currentText == null)
296             currentText = tag;
297         else
298             currentText += tag;
299     }
300 
301     /** 
302      * Add the end tag to the current comment text. 
303      */
304     public void addEndTagToText(String   localName) {
305         // Close the current HTML tag
306         String   currentHTMLTag = (String  )(tagStack.removeLast());
307         if (!Comments.isMinimizedTag(currentHTMLTag))
308             currentText += "</" + currentHTMLTag + ">";
309     }
310 
311     /** Extra modifiers which are common to all program elements. */
312     public Modifiers getModifiers(Attributes   attributes) {
313         Modifiers modifiers = new Modifiers();
314         modifiers.isStatic = false;
315         if (attributes.getValue("static").compareTo("true") == 0)
316             modifiers.isStatic = true;
317         modifiers.isFinal = false;
318         if (attributes.getValue("final").compareTo("true") == 0)
319             modifiers.isFinal = true;
320         modifiers.isDeprecated = false;
321         String   cdt = attributes.getValue("deprecated");
322         if (cdt.compareTo("not deprecated") == 0) {
323             modifiers.isDeprecated = false;
324             currentDepText = null;
325         } else if (cdt.compareTo("deprecated, no comment") == 0) {
326             modifiers.isDeprecated = true;
327             currentDepText = null;
328         } else {
329             modifiers.isDeprecated = true;
330             currentDepText = API.showHTMLTags(cdt);
331         }
332         modifiers.visibility = attributes.getValue("visibility");
333         return modifiers;
334     }
335 
336     public void warning(SAXParseException   e) {
337         System.out.println("Warning (" + e.getLineNumber() + "): parsing XML API file:" + e);
338         e.printStackTrace();
339     }
340 
341     public void error(SAXParseException   e) {
342         System.out.println("Error (" + e.getLineNumber() + "): parsing XML API file:" + e);
343         e.printStackTrace();
344         System.exit(1);
345     }
346     
347     public void fatalError(SAXParseException   e) {
348         System.out.println("Fatal Error (" + e.getLineNumber() + "): parsing XML API file:" + e);
349         e.printStackTrace();
350         System.exit(1);
351     }    
352 
353     /** 
354      * If set, then attempt to convert @link tags to HTML links. 
355      * A few of the HTML links may be broken links.
356      */
357     private static boolean convertAtLinks = true;
358 
359     /** Set to enable increased logging verbosity for debugging. */
360     private static boolean trace = false;
361 
362 }
363
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags