Changeset 1232 for trunk/autoquest-plugin-html/src/main/java/de/ugoe/cs/autoquest/plugin/html/AbstractDefaultLogParser.java

Timestamp:

06/27/13 09:16:35 (11 years ago)

Author:

pharms

Message:

• added some documentation
• corrected handling of unparseable file during compression

File:

• trunk/autoquest-plugin-html/src/main/java/de/ugoe/cs/autoquest/plugin/html/AbstractDefaultLogParser.java (modified) (14 diffs)

trunk/autoquest-plugin-html/src/main/java/de/ugoe/cs/autoquest/plugin/html/AbstractDefaultLogParser.java

@@ -33 +33 @@
 import org.xml.sax.Attributes;
 import org.xml.sax.InputSource;
+import org.xml.sax.Locator;
 import org.xml.sax.SAXException;
 import org.xml.sax.SAXParseException;
@@ -116 +117 @@
     /**
      * <p>
+     * the handle to the locator for correctly throwing exceptions with location information
+     * </p>
+     */
+    private Locator locator;
+
+    /**
+     * <p>
      * Constructor. Creates a new logParser.
      * </p>
@@ -134 +142 @@
      * @param filename
      *            name and path of the log file
-     */
-    public void parseFile(String filename) {
+     *
+     * @throws SAXException in the case, the file could not be parsed
+     */
+    public void parseFile(String filename) throws SAXException {
         if (filename == null) {
             throw new IllegalArgumentException("filename must not be null");
@@ -150 +160 @@
      * @param file
      *            file to be parsed
-     */
-    public void parseFile(File file) {
+     *
+     * @throws SAXException in the case, the file could not be parsed
+     */
+    public void parseFile(File file) throws SAXException {
         if (file == null) {
             throw new IllegalArgumentException("file must not be null");
@@ -167 +179 @@
             Console.printerrln("Error parsing file " + file.getName());
             Console.logException(e);
-            return;
+            throw new SAXParseException("Error parsing file " + file.getName(), locator, e);
         }
         catch (ParserConfigurationException e) {
             Console.printerrln("Error parsing file " + file.getName());
             Console.logException(e);
-            return;
-        }
-        catch (SAXException e) {
-            Console.printerrln("Error parsing file " + file.getName());
-            Console.logException(e);
+            throw new SAXParseException("Error parsing file " + file.getName(), locator, e);
         }
         catch (FileNotFoundException e) {
             Console.printerrln("Error parsing file " + file.getName());
             Console.logException(e);
-        }
+            throw new SAXParseException("Error parsing file " + file.getName(), locator, e);
+        }
+        
         if (inputSource != null) {
             inputSource.setSystemId("file://" + file.getAbsolutePath());
@@ -190 +200 @@
                 saxParser.parse(inputSource, this);
             }
-            catch (SAXParseException e) {
-                Console.printerrln("Failure parsing file in line " + e.getLineNumber() +
-                    ", column " + e.getColumnNumber() + ".");
-                Console.logException(e);
-            }
-            catch (SAXException e) {
-                Console.printerrln("Error parsing file " + file.getName());
-                Console.logException(e);
-                return;
-            }
             catch (IOException e) {
                 Console.printerrln("Error parsing file " + file.getName());
                 Console.logException(e);
-                return;
+                throw new SAXParseException("Error parsing file " + file.getName(), locator, e);
             }
         }
@@ -228 +228 @@
     public GUIModel getGuiModel() {
         return guiElementTree.getGUIModel();
+    }
+
+    /* (non-Javadoc)
+     * @see org.xml.sax.helpers.DefaultHandler#setDocumentLocator(org.xml.sax.Locator)
+     */
+    @Override
+    public void setDocumentLocator(Locator locator) {
+        this.locator = locator;
     }
 
@@ -298 +306 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     *
-     * @param id
-     * @param parameters
-     * @return
+     * called to handle parsed GUI elements
+     * </p>
+     *
+     * @param id         the id of the parsed GUI element
+     * @param parameters all parameters parsed for the GUI element
+     * 
+     * @return true, if the GUI element could be handled. In this case this method is not called
+     *         again for the same GUI element. Otherwise the method is called later again. This
+     *         may be required, if a child GUI element is parsed before the parent GUI element
      */
     protected abstract boolean handleGUIElement(String id, Map<String, String> parameters) 
@@ -310 +321 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     *
-     * @param id
-     * @param parameters
-     * @return
+     * called to handle parsed events
+     * </p>
+     *
+     * @param type       the type of the parsed event
+     * @param parameters the parameters of the parsed event
+     * 
+     * @return true, if the event could be handled. In this case this method is not called
+     *         again for the same event. Otherwise the method is called later again. This
+     *         may be required, if e.g. the target of the event, i.e. the GUI element, is not yet
+     *         parsed
      */
     protected abstract boolean handleEvent(String type, Map<String, String> parameters)
@@ -322 +337 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     *
-     * @return
+     * returns the tree of parsed GUI elements, which consists of the ids of the GUI elements
+     * </p>
+     *
+     * @return as described
      */
     protected GUIElementTree<String> getGUIElementTree() {
@@ -333 +348 @@
     /**
      * <p>
-     * TODO: comment
+     * adds an event to the currently parsed sequence of events
      * </p>
      *
@@ -344 +359 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     *
+     * this method internally processes GUI elements, that have been parsed but not processed yet.
+     * I.e., for such GUI elements, either the method {@link #handleGUIElement(String, Map)} has
+     * not been called yet, or it returned false for the previous calls. In this case, the method
+     * is called (again). Furthermore, the processing of events is initiated by a call to
+     * {@link #processEvents()}.
+     * </p>
      */
     private void processGUIElements() throws SAXException {
@@ -374 +392 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     *
+     * this method internally processes events, that have been parsed but not processed yet.
+     * I.e., for such events, either the method {@link #handleEvent(String, Map)} has
+     * not been called yet, or it returned false for the previous calls. In this case, the method
+     * is called (again).
+     * </p>
      */
     private void processEvents() throws SAXException {
@@ -410 +430 @@
     /**
      * <p>
-     * TODO document
+     * This class is used internally for storing events and GUI elements in lists.
      * </p>
      */