Changeset 1856 for trunk

Timestamp:

01/07/15 14:04:59 (10 years ago)

Author:

dmay

Message:

a big wave of refactorings/documentation

File:

• trunk/autoquest-plugin-jfc/src/main/java/de/ugoe/cs/autoquest/plugin/jfc/commands/CMDgenerateJacaretoReplay.java (modified) (9 diffs)

trunk/autoquest-plugin-jfc/src/main/java/de/ugoe/cs/autoquest/plugin/jfc/commands/CMDgenerateJacaretoReplay.java

@@ -50 +50 @@
 import de.ugoe.cs.util.console.GlobalDataContainer;
 
-// helper class for the tree like structure part within a Jacareto file
-class StructureNode {
-    public static int nextRef = 0;
-
-    public String content;
-    public ArrayList<StructureNode> children;
-
-    public StructureNode(String type) {
-        setContent(type);
-        children = new ArrayList<StructureNode>();
-    }
-
-    public StructureNode() {
-        content = "<Recordable ref=\"" + (nextRef++) + "\" />";
-        children = new ArrayList<StructureNode>();
-    }
-
-    public void setContent(String type) {
-        content = "<StructureElement class=\"jacareto.struct." + type + "\">";
-    }
-
-    public StructureNode add(String type) {
-        StructureNode node = new StructureNode(type);
-        children.add(node);
-        return node;
-    }
-
-    public void addRecordable() {
-        children.add(new StructureNode());
-    }
-
-    @Override
-    public String toString() {
-        String separator = System.getProperty("line.separator");
-        String result = content + separator;
-
-        for (StructureNode child : children) {
-            result += child.toString();
-        }
-
-        if (content.endsWith("/>")) {
-            return result;
-        }
-        return result + "</StructureElement>" + separator;
-    }
-}
-
 /**
  * <p>
@@ -106 +59 @@
  */
 public class CMDgenerateJacaretoReplay implements Command {
+
+    /**
+     * <p>
+     * Helper class for the tree like structure part within a Jacareto file.
+     * </p>
+     */
+    private static class StructureNode {
+
+        /**
+         * <p>
+         * Keeps track of the next structure node id.
+         * </p>
+         */
+        public static int nextRef = 0;
+
+        /**
+         * <p>
+         * The node's type packaged into an XML string.
+         * </p>
+         */
+        public String content;
+
+        /**
+         * <p>
+         * This node's children.
+         * </p>
+         */
+        public ArrayList<StructureNode> children;
+
+        /**
+         * <p>
+         * Constructor. Creates a new StructureNode of a specified type and builds its Jacareto XML
+         * representation.
+         * </p>
+         * 
+         * @param type
+         *            the type of this StructureNode, for example: 'MouseDownEvent'
+         */
+        public StructureNode(String type) {
+            setContent(type);
+            children = new ArrayList<StructureNode>();
+        }
+
+        /**
+         * <p>
+         * Constructor. Creates a StructureNode of type 'Recordable' with a valid id and builds its
+         * Jacareto XML representation.
+         * </p>
+         */
+        public StructureNode() {
+            content = "<Recordable ref=\"" + (nextRef++) + "\" />";
+            children = new ArrayList<StructureNode>();
+        }
+
+        /**
+         * <p>
+         * Builds the XML representation of a Jacareto structure type.
+         * </p>
+         * 
+         * @param type
+         *            the type of this StructureNode, for example: 'MouseDownEvent'
+         */
+        public void setContent(String type) {
+            content = "<StructureElement class=\"jacareto.struct." + type + "\">";
+        }
+
+        /**
+         * <p>
+         * Adds a new StructureNode as a child of this node.
+         * </p>
+         * 
+         * @param type
+         *            the type of the child node, for example: 'MouseDownEvent'
+         */
+        public StructureNode add(String type) {
+            StructureNode node = new StructureNode(type);
+            children.add(node);
+            return node;
+        }
+
+        /**
+         * <p>
+         * Builds the XML representation of a Jacareto structure type.
+         * </p>
+         * 
+         * @param type
+         *            the type of this StructureNode, for example: 'MouseDownEvent'
+         */
+        public void addRecordable() {
+            children.add(new StructureNode());
+        }
+
+        /**
+         * <p>
+         * Returns a Jacareto XML representation of this StructureNode, includin all its children.
+         * </p>
+         */
+        @Override
+        public String toString() {
+            String separator = System.getProperty("line.separator");
+            String result = content + separator;
+
+            for (StructureNode child : children) {
+                result += child.toString();
+            }
+
+            if (content.endsWith("/>")) {
+                return result;
+            }
+            return result + "</StructureElement>" + separator;
+        }
+    }
+
+    /**
+     * <p>
+     * The time it takes for Jacareto to replay an event in ms.
+     * </p>
+     */
     private static final int EVENT_DURATION = 150;
+
+    /**
+     * <p>
+     * The time it takes for Jacareto to replay each part of a double click event in ms.
+     * </p>
+     */
     private static final int DOUBLE_CLICK_DURATION = 50;
+
+    /**
+     * <p>
+     * Application startup time in ms. The application needs to be fully initialized before Jacareto
+     * can start replaying.
+     * </p>
+     */
     private static final int STARTUP_DELAY = 10000;
 
+    /**
+     * <p>
+     * The GUI element which is currently focused.
+     * </p>
+     */
     private JFCGUIElement currentFocus;
+
+    /**
+     * <p>
+     * A tree of StructureNodes which represents the structure part inside a Jacareto XML file.
+     * </p>
+     */
     private StructureNode structure;
 
+    /**
+     * <p>
+     * XML structure for key events modeled as StructureNodes.
+     * </p>
+     */
     private StructureNode lastKeySequenceEvent;
+
+    /**
+     * <p>
+     * XML structure for key events modeled as StructureNodes.
+     * </p>
+     */
     private StructureNode lastKeyTypedEvent;
+
+    /**
+     * <p>
+     * Bitmask which represents currently used key modifiers (such as shift etc).
+     * </p>
+     */
     private int currentKeyModifiers;
 
+    /**
+     * <p>
+     * Maps VirtualKey objects for modifier keys back to AWT Event codes.
+     * </p>
+     */
     private HashMap<VirtualKey, Integer> modifiers;
 
+    /**
+     * <p>
+     * XML structure for mouse events modeled as StructureNodes.
+     * </p>
+     */
     private StructureNode lastMouseClickEvent;
+
+    /**
+     * <p>
+     * XML structure for focus events modeled as StructureNodes.
+     * </p>
+     */
     private StructureNode lastFocusChangeEvent;
+
+    /**
+     * <p>
+     * XML structure for item and action events modeled as StructureNodes.
+     * </p>
+     */
     private StructureNode lastItemActionEvent;
+
+    /**
+     * <p>
+     * The target of the last mouseDownEvent. It is necessary to save this because mouse down and up
+     * targets can differ.
+     * </p>
+     */
     private IEventTarget lastMouseDownTarget;
+
+    /**
+     * <p>
+     * Associates the name of a menu element with its corresponding JFCGUIElement.
+     * </p>
+     */
     private HashMap<String, JFCGUIElement> menuElements;
+
+    /**
+     * <p>
+     * The menu hierarchy.
+     * </p>
+     */
     private List<String> menuList;
 
@@ -184 +337 @@
 
         sequences = (Collection<List<Event>>) dataObject;
-
         menuElements = new HashMap<>();
-
-        // map which maps VirtualKeys back to awt key modifier codes
-        modifiers = new HashMap<>();
-        modifiers.put(VirtualKey.SHIFT, 1);
-        modifiers.put(VirtualKey.CONTROL, 2);
-        modifiers.put(VirtualKey.ALT, 8);
-        modifiers.put(VirtualKey.ALT_GRAPH, 32);
+        modifiers = createModifierMap();
         currentKeyModifiers = 0;
-
         StructureNode.nextRef = 0;
 
@@ -200 +345 @@
     }
 
+    /**
+     * <p>
+     * Associates keyboard modifier keys with their AWT event codes.
+     * </p>
+     */
+    private HashMap<VirtualKey, Integer> createModifierMap() {
+        HashMap<VirtualKey, Integer> result = new HashMap<>();
+
+        result.put(VirtualKey.SHIFT, 1);
+        result.put(VirtualKey.CONTROL, 2);
+        result.put(VirtualKey.ALT, 8);
+        result.put(VirtualKey.ALT_GRAPH, 32);
+
+        return result;
+    }
+
+    /**
+     * <p>
+     * Writes a line and creates a new line.
+     * </p>
+     * 
+     * @param writer
+     *            the BufferedWriter which writes the XML
+     * @param line
+     *            the line to write
+     * 
+     */
     private void writeLine(BufferedWriter writer, String line) throws IOException {
         writer.write(line);
@@ -205 +377 @@
     }
 
+    /**
+     * <p>
+     * Writes the Jacareto XML head part. This mainly contains information about the state of the
+     * system when the replay was captured.
+     * 
+     * @param writer
+     *            the BufferedWriter which writes the XML
+     * @param classname
+     *            name of the main class of the program that will be replayed
+     * @param basepath
+     *            a basepath that is prepended to all paths specified in classpathext
+     * @param classpathext
+     *            additional required resources (e.g. jar files)
+     * 
+     *            </p>
+     */
     private void writeJacaretoHead(BufferedWriter writer,
                                    String classname,
@@ -251 +439 @@
     }
 
+    /**
+     * <p>
+     * Writes Jacareto XML code for all events within the Autoquest sequences.
+     * </p>
+     * 
+     * @param writer
+     *            the BufferedWriter which writes the XML
+     * @param sequences
+     *            the Autoquest sequences
+     * 
+     */
     private void writeJacaretoEvents(BufferedWriter writer, Collection<List<Event>> sequences)
         throws IOException
@@ -267 +466 @@
 
                 if (event.getType() instanceof MouseButtonDown) {
-                    handleMouseDown(writer, event, "MouseClick");
+                    handleMouseButtonDown(writer, event);
                 }
                 else if (event.getType() instanceof MouseButtonUp) {
-                    handleMouseUp(writer, event);
+                    handleMouseButtonUp(writer, event);
                 }
                 else if (event.getType() instanceof MouseDoubleClick) {
-                    StructureNode multiClick = structure.add("MultipleMouseClick");
-
-                    // first click
-                    lastMouseClickEvent = multiClick.add("MouseClick");
-                    writeMouseClickEvent(writer, event, (JFCGUIElement) event.getTarget(),
-                                         DOUBLE_CLICK_DURATION, 501);
-                    writeMouseClickEvent(writer, event, (JFCGUIElement) event.getTarget(),
-                                         DOUBLE_CLICK_DURATION, 502);
-                    writeMouseClickEvent(writer, event, (JFCGUIElement) event.getTarget(),
-                                         DOUBLE_CLICK_DURATION, 500);
-                    // second click
-                    lastMouseClickEvent = multiClick.add("MouseClick");
-                    writeMouseClickEvent(writer, event, (JFCGUIElement) event.getTarget(),
-                                         DOUBLE_CLICK_DURATION, 501);
-                    writeMouseClickEvent(writer, event, (JFCGUIElement) event.getTarget(),
-                                         DOUBLE_CLICK_DURATION, 502);
-                    writeMouseClickEvent(writer, event, (JFCGUIElement) event.getTarget(),
-                                         DOUBLE_CLICK_DURATION, 500);
-
-                    lastMouseClickEvent = null;
+                    handleMouseDoubleClick(writer, event);
                 }
                 else if (event.getType() instanceof MouseClick) {
@@ -315 +495 @@
                     }
 
-                    lastKeySequenceEvent = null;
-
-                    if (lastMouseClickEvent != null) {
-                        if (lastMouseDownTarget == event.getTarget()) {
-                            // this is the standard case:
-                            // mouseDown, mouseUp and mouseClick sequence
-                            // was triggered on this target
-
-                            writeMouseClickEvent(writer, event, (JFCGUIElement) event.getTarget(),
-                                                 EVENT_DURATION, 500);
-                            writeItemActionEvent(writer, event);
-
-                            if (lastFocusChangeEvent == null) {
-                                // write structure sequentially
-                                structure.children.add(lastMouseClickEvent);
-                                structure.children.add(lastItemActionEvent);
-                            }
-                            else {
-                                // with nested structure
-                                structure.children.add(lastItemActionEvent);
-                                lastItemActionEvent.children.add(0, lastFocusChangeEvent);
-                                lastFocusChangeEvent.children.add(0, lastMouseClickEvent);
-
-                                lastFocusChangeEvent = null;
-                                lastMouseClickEvent = null;
-                            }
-                        }
-                        else {
-                            // target of mouseDown and mouseClick are different
-                            // -> this is, for example, a click on a menu item
-                            // within a condensed sequence
-                            commitFocusEvent();
-
-                            // finish the last click on the old target
-                            writeMouseClickEvent(writer, event, (JFCGUIElement) event.getTarget(),
-                                                 EVENT_DURATION, 500);
-                            structure.children.add(lastMouseClickEvent);
-
-                            // and generate a new one
-                            generateFullClick(writer, event, (JFCGUIElement) event.getTarget());
-                        }
-                    }
-                    else {
-                        // a target was clicked repeatedly:
-                        // the condensed sequence contains no mouseDowns or
-                        // mouseUps anymore
-                        // -> just generate another full click
-                        generateFullClick(writer, event, (JFCGUIElement) event.getTarget());
-                    }
+                    handleMouseClick(writer, event);
                 }
                 else if (event.getType() instanceof KeyboardFocusChange) {
-                    lastKeySequenceEvent = null;
-
-                    writeFocusChangeEvent(writer, event);
+                    handleKeyboardFocusChange(writer, event);
                 }
                 else if (event.getType() instanceof MouseDragAndDrop) {
@@ -390 +520 @@
     }
 
-    private void handleMouseDown(BufferedWriter writer, Event event, String structureName)
-        throws IOException
-    {
+    // EVENT HANDLERS
+
+    private void handleMouseClick(BufferedWriter writer, Event event) throws IOException {
+        lastKeySequenceEvent = null;
+
+        if (lastMouseClickEvent != null) {
+            if (lastMouseDownTarget == event.getTarget()) {
+                // this is the standard case:
+                // mouseDown, mouseUp and mouseClick sequence
+                // was triggered on this target
+
+                writeMouseClickEvent(writer, event, (JFCGUIElement) event.getTarget(),
+                                     EVENT_DURATION, 500);
+                writeItemActionEvent(writer, event);
+
+                if (lastFocusChangeEvent == null) {
+                    // write structure sequentially
+                    structure.children.add(lastMouseClickEvent);
+                    structure.children.add(lastItemActionEvent);
+                }
+                else {
+                    // with nested structure
+                    structure.children.add(lastItemActionEvent);
+                    lastItemActionEvent.children.add(0, lastFocusChangeEvent);
+                    lastFocusChangeEvent.children.add(0, lastMouseClickEvent);
+
+                    lastFocusChangeEvent = null;
+                    lastMouseClickEvent = null;
+                }
+            }
+            else {
+                // target of mouseDown and mouseClick are different
+                // -> this is, for example, a click on a menu item
+                // within a condensed sequence
+                commitFocusEvent();
+
+                // finish the last click on the old target
+                writeMouseClickEvent(writer, event, (JFCGUIElement) event.getTarget(),
+                                     EVENT_DURATION, 500);
+                structure.children.add(lastMouseClickEvent);
+
+                // and generate a new one
+                generateFullClick(writer, event, (JFCGUIElement) event.getTarget());
+            }
+        }
+        else {
+            // a target was clicked repeatedly:
+            // the condensed sequence contains no mouseDowns or
+            // mouseUps anymore
+            // -> just generate another full click
+            generateFullClick(writer, event, (JFCGUIElement) event.getTarget());
+        }
+
+    }
+
+    private void handleMouseDoubleClick(BufferedWriter writer, Event event) throws IOException {
+        StructureNode multiClick = structure.add("MultipleMouseClick");
+
+        // first click
+        lastMouseClickEvent = multiClick.add("MouseClick");
+        writeMouseClickEvent(writer, event, (JFCGUIElement) event.getTarget(),
+                             DOUBLE_CLICK_DURATION, 501);
+        writeMouseClickEvent(writer, event, (JFCGUIElement) event.getTarget(),
+                             DOUBLE_CLICK_DURATION, 502);
+        writeMouseClickEvent(writer, event, (JFCGUIElement) event.getTarget(),
+                             DOUBLE_CLICK_DURATION, 500);
+        // second click
+        lastMouseClickEvent = multiClick.add("MouseClick");
+        writeMouseClickEvent(writer, event, (JFCGUIElement) event.getTarget(),
+                             DOUBLE_CLICK_DURATION, 501);
+        writeMouseClickEvent(writer, event, (JFCGUIElement) event.getTarget(),
+                             DOUBLE_CLICK_DURATION, 502);
+        writeMouseClickEvent(writer, event, (JFCGUIElement) event.getTarget(),
+                             DOUBLE_CLICK_DURATION, 500);
+
+        lastMouseClickEvent = null;
+
+    }
+
+    private void handleKeyboardFocusChange(BufferedWriter writer, Event event) throws IOException {
+        lastKeySequenceEvent = null;
+        writeFocusChangeEvent(writer, event);
+    }
+
+    private void handleMouseButtonDown(BufferedWriter writer, Event event) throws IOException {
         commitFocusEvent();
         lastKeySequenceEvent = null;
 
-        lastMouseClickEvent = new StructureNode(structureName);
+        lastMouseClickEvent = new StructureNode("MouseClick");
         lastMouseDownTarget = event.getTarget();
         writeMouseClickEvent(writer, event, (JFCGUIElement) event.getTarget(), EVENT_DURATION, 501);
     }
 
-    private void handleMouseUp(BufferedWriter writer, Event event) throws IOException {
+    private void handleMouseButtonUp(BufferedWriter writer, Event event) throws IOException {
         lastKeySequenceEvent = null;