+ * Skeletal implementation for hierarchical event targets. + *
+ * + * @version 1.0 + * @author Patrick Harms + */ +public abstract class AbstractDefaultHierarchicalEventTarget + implements IHierarchicalEventTarget +{ + + /** + *+ * Id for object serialization. + *
+ */ + public static final long serialVersionUID = 1L; + + /** + *+ * Specification of the event target + *
+ */ + private final IEventTargetSpec specification; + + /** + *+ * Reference to the parent event target + *
+ */ + private IHierarchicalEventTarget parent; + + /** + *+ * List of other event targets being equal to this + *
+ */ + private List+ * the reference to the event target model to which this event target belongs. + *
+ */ + private HierarchicalEventTargetModel eventTargetModel; + + /** + *+ * the hash code of this object + *
+ */ + private int hashCode; + + /** + *+ * Constructor. Creates a new AbstractDefaultEventTarget. + *
+ * + * @param specification + * specification of the created event target + * @param parent + * parent of the created event target; null means the target is at top-level + */ + public AbstractDefaultHierarchicalEventTarget(IEventTargetSpec specification, + IHierarchicalEventTarget parent) + { + this.specification = specification; + setParent(parent); + + if (specification != null) { + this.hashCode = specification.hashCode(); + } + else { + this.hashCode = 0; + } + } + + /* (non-Javadoc) + * @see de.ugoe.cs.autoquest.eventcore.IHierarchicalEventTarget#getSpecification() + */ + @Override + public IEventTargetSpec getSpecification() { + return specification; + } + + /* (non-Javadoc) + * @see de.ugoe.cs.autoquest.eventcore.IHierarchicalEventTarget#getParent() + */ + @Override + public IHierarchicalEventTarget getParent() { + return parent; + } + + /* (non-Javadoc) + * @see de.ugoe.cs.autoquest.eventcore.IHierarchicalEventTarget#getEventTargetModel() + */ + @Override + public HierarchicalEventTargetModel getEventTargetModel() + { + return eventTargetModel; + } + + /* (non-Javadoc) + * @see de.ugoe.cs.autoquest.eventcore.IHierarchicalEventTarget#addEqualEventTarget(IHierarchicalEventTarget) + */ + @Override + public void addEqualEventTarget(IHierarchicalEventTarget equalElement) { + if (!(equalElement instanceof AbstractDefaultHierarchicalEventTarget)) { + throw new IllegalArgumentException + ("this implementation can only handle other AbstractDefaultHierarchicalEventTargets"); + } + + AbstractDefaultHierarchicalEventTarget other = + (AbstractDefaultHierarchicalEventTarget) equalElement; + + synchronized (AbstractDefaultHierarchicalEventTarget.class) { + if (this.equalEventTargets == null) { + if (other.equalEventTargets == null) { + this.equalEventTargets = new LinkedList+ * updates the parent node of this node if required due to model restructuring + *
+ */ + void setParent(IHierarchicalEventTarget newParent) + { + synchronized (AbstractDefaultHierarchicalEventTarget.class) { + // all equal event targets must have the same parent. Otherwise, they are not equal + // anymore and we would have discrepancies on the return value of getParent() on + // equal event targets. + this.parent = newParent; + if (equalEventTargets != null) { + for (AbstractDefaultHierarchicalEventTarget candidate : equalEventTargets) { + candidate.parent = newParent; + } + } + } + } + + /** + *+ * used to set the event target model to which this event target belongs. Will be set + * automatically, if used in combination with {@link HierarchicalEventTargetModel}; + *
+ * + * @param eventTargetModel + * + */ + void setEventTargetModel(HierarchicalEventTargetModel eventTargetModel) { + this.eventTargetModel = eventTargetModel; + } + + /** + *+ * Adds an {@link AbstractDefaultHierarchicalEventTarget} as equal to a list of + * {@link AbstractDefaultHierarchicalEventTarget}s if and only if it is not already contained. + *
+ * + * @param equalTargetsList + * list of {@link AbstractDefaultHierarchicalEventTarget} to which the event target + * is added + * @param eventTarget + * event target to be added + */ + private void addIfNotContained(List+ * Exception that is thrown if there is a failure during the creation of an + * {@link IHierarchicalEventTarget} by the {@link IEventTargetFactory}. + *
+ * + * @version 1.0 + * @author Patrick Harms + */ +public class EventTargetModelConfigurationException extends EventTargetModelException { + + /** + *+ * Id for object serialization. + *
+ */ + private static final long serialVersionUID = 1L; + + /** + *+ * Constructor. Creates a new EventTargetModelConfigurationException. + *
+ */ + public EventTargetModelConfigurationException() { + super(); + } + + /** + *+ * Constructor. Creates a new EventTargetModelConfigurationException. + *
+ * + * @param message + * message of the exception + */ + public EventTargetModelConfigurationException(String message) { + super(message); + } + + /** + *+ * Constructor. Creates a new EventTargetModelConfigurationException. + *
+ * + * @param cause + * cause of the exception + */ + public EventTargetModelConfigurationException(Throwable cause) { + super(cause); + } + + /** + *+ * Constructor. Creates a new EventTargetModelConfigurationException. + *
+ * + * @param message + * message of the exception + * @param cause + * cause of the exception + */ + public EventTargetModelConfigurationException(String message, Throwable cause) { + super(message, cause); + } + +} Index: trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/EventTargetModelException.java =================================================================== --- trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/EventTargetModelException.java (revision 2146) +++ trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/EventTargetModelException.java (revision 2146) @@ -0,0 +1,81 @@ +// Copyright 2012 Georg-August-Universität Göttingen, Germany +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package de.ugoe.cs.autoquest.eventcore; + +/** + *+ * Exception that is thrown if there are problems with the {@link IHierarchicalEventTargetModel}. + *
+ * + * @version 1.0 + * @author Patrick Harms + */ +public class EventTargetModelException extends Exception { + + /** + *+ * Id for object serialization. + *
+ */ + private static final long serialVersionUID = 1L; + + /** + *+ * Constructor. Creates a new EventTargetModelException. + *
+ */ + public EventTargetModelException() { + super(); + } + + /** + *+ * Constructor. Creates a new EventTargetModelException. + *
+ * + * @param message + * message of the exception + */ + public EventTargetModelException(String message) { + super(message); + } + + /** + *+ * Constructor. Creates a new EventTargetModelException. + *
+ * + * @param cause + * cause of the exception + */ + public EventTargetModelException(Throwable cause) { + super(cause); + } + + /** + *+ * Constructor. Creates a new EventTargetModelException. + *
+ * + * @param message + * message of the exception + * @param cause + * cause of the exception + */ + public EventTargetModelException(String message, Throwable cause) { + super(message, cause); + } + +} Index: trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/HierarchicalEventTargetGroup.java =================================================================== --- trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/HierarchicalEventTargetGroup.java (revision 2146) +++ trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/HierarchicalEventTargetGroup.java (revision 2146) @@ -0,0 +1,167 @@ +// Copyright 2012 Georg-August-Universität Göttingen, Germany +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package de.ugoe.cs.autoquest.eventcore; + +import java.util.Collections; +import java.util.LinkedList; +import java.util.List; + +/** + *+ * This class is a dummy hierarchical event target to represent groups of event targets. A group of + * event targets can be integrated in any hierarchical event target model using the method + * {@link HierarchicalEventTargetModel#groupEventTargets(List, String, IEventTargetFactory)}. A + * group has the same behavior as any other parent hierarchical event target. + *
+ * + * @author Patrick Harms + */ +public class HierarchicalEventTargetGroup extends AbstractDefaultHierarchicalEventTarget { + + /** + *+ * default serial version UID + *
+ */ + private static final long serialVersionUID = 1L; + + /** + * the list of grouped event targets + */ + private List+ * instantiates an event target group with a name and its optional parent event target + *
+ * + * @param groupName the name of the event target group + * @param parent the optional parent event target of the group + * @param eventTargetModel the event target model to which the group will belong + */ + public HierarchicalEventTargetGroup(String groupName, + IHierarchicalEventTarget parent, + HierarchicalEventTargetModel eventTargetModel) + { + super(new GroupSpecification(groupName), parent); + super.setEventTargetModel(eventTargetModel); + } + + /* (non-Javadoc) + * @see de.ugoe.cs.autoquest.eventcore.IEventTarget#getPlatform() + */ + @Override + public String getPlatform() { + return "none"; + } + + /* (non-Javadoc) + * @see de.ugoe.cs.autoquest.eventcore.IEventTarget#getStringIdentifier() + */ + @Override + public String getStringIdentifier() { + return ((GroupSpecification) super.getSpecification()).name; + } + + /* (non-Javadoc) + * @see java.lang.Object#toString() + */ + @Override + public String toString() { + return getStringIdentifier(); + } + + /* (non-Javadoc) + * @see IHierarchicalEventTarget#updateSpecification(IEventTargetSpec) + */ + @Override + public void updateSpecification(IEventTargetSpec furtherSpec) { + // do nothing + } + + /** + *+ * returns the list of event targets belonging to this group. + *
+ * + * @return the event targets belonging to this group + * + */ + public List+ * allows adding a new event target to the group + *
+ * + * @param eventTarget the new member of the group + */ + void addToGroup(IHierarchicalEventTarget eventTarget) { + this.groupedEventTargets.add(eventTarget); + } + + /** + *+ * internally required event target specification for an event target group. This is just a + * wrapper for a name of an event target group + *
+ * + * @author Patrick Harms + */ + private static class GroupSpecification implements IEventTargetSpec { + + /** + *+ * default serial version UID + *
+ */ + private static final long serialVersionUID = 1L; + + /** + *+ * the name of the event target group represented by this specification + *
+ */ + private String name; + + /** + *+ * instantiates the group specification with the given name. Two group specifications + * are only similar, if their names match. + *
+ * + * @param name the name of the group + */ + private GroupSpecification(String name) { + super(); + this.name = name; + } + + /* (non-Javadoc) + * @see IEventTargetSpec#getSimilarity(IEventTargetSpec) + */ + @Override + public boolean getSimilarity(IEventTargetSpec other) { + return + (other instanceof GroupSpecification) && + name.equals(((GroupSpecification) other).name); + } + + } + +} Index: trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/HierarchicalEventTargetModel.java =================================================================== --- trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/HierarchicalEventTargetModel.java (revision 2146) +++ trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/HierarchicalEventTargetModel.java (revision 2146) @@ -0,0 +1,995 @@ +// Copyright 2012 Georg-August-Universität Göttingen, Germany +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package de.ugoe.cs.autoquest.eventcore; + +import java.io.OutputStream; +import java.io.PrintStream; +import java.io.Serializable; +import java.io.UnsupportedEncodingException; +import java.util.ArrayList; +import java.util.HashMap; +import java.util.LinkedList; +import java.util.List; +import java.util.Map; +import java.util.Stack; +import java.util.logging.Level; + +import de.ugoe.cs.autoquest.eventcore.IHierarchicalEventTargetModel; +import de.ugoe.cs.util.console.Console; + +/** + *+ * A hierarchical event target model is a tree of {@link IHierarchicalEventTarget}s and represents + * a complete user interface, e.g. GUI of a software. It is platform independent. It may have + * several root nodes, as some user interfaces are made up of several frames (GUI) or scenes (VR) + * being independent from each other. The event target model is filled using the + * {@link #integratePath(List, IEventTargetFactory)} method. + *
+ * + * @version 1.0 + * @author Patrick Harms, Steffen Herbold + */ +public class HierarchicalEventTargetModel+ * The root node of the tree not provided externally. + *
+ */ + private TreeNode root = new TreeNode(); + + /** + *+ * A map with all nodes currently known + *
+ */ + private Map+ * true, if internal validation is switched on, false else + *
+ */ + private boolean validate = false; + + /** + *+ * Default constructor to create a event target model without internal validation + *
+ * + */ + public HierarchicalEventTargetModel() { + this(false); + } + + /** + *+ * creates an event target model, that internally validates itself by checking on access to + * nodes, if several event targets pretend to be equal or if several distinct event targets + * have the same child. + *
+ * + * @param validate + * true if internal validation shall be switched on (bad performance), false else + * + */ + public HierarchicalEventTargetModel(boolean validate) { + this.validate = validate; + } + + /** + *+ * Integrates a path of event targets into the event target model. The event target model + * itself is a tree and therefore a set of different paths through the tree that start with + * a root node and end with a leaf node. Such a path can be added to the tree. The method + * checks, if any of the event targets denoted by the path already exists. If so, it reuses it. + * It may therefore also return an existing event target being the leaf node of the provided + * path. If an event target of the path does not exist yet, it creates a new one using the + * provided event target factory. + *
+ *+ * If an event target specification describes an existing event target or not is determined + * through comparing the event target specifications of the existing event targets with the + * ones provided in the path. The comparison is done using the + * {@link IEventTargetSpec#getSimilarity(IEventTargetSpec)} method. The comparison is only done + * on the correct levels. I.e. the currently known root elements of the tree are only compared + * to the first element in the path. If the correct one is found or created, its children are + * compared only to the second specification in the path, and so on. + *
+ *+ * The returned event targets are singletons. I.e. it is tried to return always the identical + * object for the same denoted element. However, while creating the event target model, the + * similarity of event targets may change. Therefore, the method might determine, that two + * formerly different nodes are now similar. (This may happen, e.g. if event targets do not + * have initial names which are set afterwards. Therefore, first they are handled differently + * and later they can be identified as being the same.) In such a case, there are already + * several event target objects instantiated for the same event target. The singleton paradigm + * gets broken. Therefore, such event target objects are registered with each other, so that + * their equal method can determine equality again correctly, although the objects are no + * singletons anymore. + *
+ * + * @param eventTargetPath + * the path to integrate into the model + * @param eventTargetFactory + * the event target factory to be used for instantiating event target objects + * + * @return The event target object representing the event target denoted by the provided path + * + * @throws EventTargetModelException + * thrown in cases such as the event target object could not be instantiated + * @throws IllegalArgumentException + * if the provided path is invalid. + */ + public T integratePath(List eventTargetPath, + IEventTargetFactory eventTargetFactory) + throws EventTargetModelException, IllegalArgumentException + { + if ((eventTargetPath == null) || (eventTargetPath.size() <= 0)) { + throw new IllegalArgumentException("event target path must contain at least one element"); + } + + List+ * dumps the event target model to the provided stream. Each node is represented through its + * toString() method. If a node has children, those are dumped indented and surrounded by + * braces. + *
+ * + * @param out + * The stream to dump the textual representation of the model to + * @param encoding + * The encoding to be used while dumping + */ + public void dump(OutputStream out, String encoding) { + PrintStream stream; + + if (out instanceof PrintStream) { + stream = (PrintStream) out; + } + else { + String enc = encoding == null ? "UTF-8" : encoding; + try { + stream = new PrintStream(out, true, enc); + } + catch (UnsupportedEncodingException e) { + throw new IllegalArgumentException("encodind " + enc + " not supported"); + } + } + + for (TreeNode node : root.children) { + dumpeventTarget(stream, node, ""); + } + } + + /** + *+ * This method groups the provided event targets under a common parent event target. The current + * parent event target of the event targets to group must be the same. If the event targets to + * be grouped are the whole list of children of the same parent, nothing is changed. + *
+ * + * @param eventTargets the list of event targets to be grouped + * @param groupName the name of the event target group to be created + * @param eventTargetFactory the event target factory used for creating a group of the correct + * type (ensures, that all elements in the model can have T in their + * parent hierarchy) + * + * @return the event target representing the group, or null, if the provided list of event + * targets is empty + * + * @throws IllegalArgumentException + * if not all event targets to be merged share the same parent, if one of the + * parameters is null, or if one of the provided event targets does not belong to + * the model + */ + public T groupEventTargets(List+ * By calling this method, the event target model is traversed and similar nodes are merged. + *
+ * + */ + public void condenseModel() { + mergeSubTree(root); + } + + /** + *+ * Merges the tree nodes of two event targets. The event targets need to have the same parent. + * They are merged recursively, i.e. also their children are merged. + *
+ * + * @param eventTarget1 + * the first merge event target + * @param eventTarget2 + * the second merge event target + * + * @return the result of the merge + * + * @throws IllegalArgumentException + * thrown if the two event targets do not have the same parent + */ + public T mergeEventTargets(T eventTarget1, T eventTarget2) throws IllegalArgumentException + { + return mergeEventTargets(eventTarget1, eventTarget2, true); + } + + /** + *
+ * Merges the tree nodes of two event targets. The event targets need to have the same parent.
+ * If the recursively parameter is set to true, the children of the event targets
+ * are merged, as well, as long as they are similar. If the parameter is false, the children
+ * are not merged. In this case the resulting event target has all children of both merged
+ * event targets.
+ *
+ * internally integrates a path as the children of the provided parent node. This method is + * recursive and calls itself, for the child of the parent node, that matches the first element + * in the remaining path. + *
+ * + * @param parentNode + * the parent node to add children for + * @param eventTargetPath + * the path of children to be created starting with the parent node + * @param eventTargetFactory + * the event target factory to be used for instantiating event target objects + * + * @return The event target object representing the event target denoted by the provided path + * + * @throws EventTargetModelException + * thrown in cases such as the event target object could not be instantiated + */ + private T integratePath(TreeNode parentNode, + List+ * Searches the children of a tree node to see if the {@link IEventTargetSpec} equals the + * specification of the {@link TreeNode#eventTarget} of the child. If a match is found, the + * child is returned. + *
+ * + * @param parentNode + * parent node whose children are searched + * @param specToMatch + * specification that is searched for + * + * @return matching child node or null if no child matches + */ + private TreeNode findEqualChild(TreeNode parentNode, IEventTargetSpec specToMatch) { + if (parentNode.children != null) { + for (TreeNode child : parentNode.children) { + if (specToMatch.equals(child.eventTarget.getSpecification())) { + return child; + } + } + } + return null; + } + + /** + *+ * Merges all similar nodes in the sub-tree of the event target model defined by the + * subTreeRoot. + *
+ *+ * The merging order is a bottom-up. This means, that we first call mergeSubTree recursively for + * the grand children of the subTreeRoot, before we merge subTreeRoot. + *
+ *+ * The merging strategy is top-down. This means, that every time we merge two child nodes, we + * call mergeSubTree recursively for all children of the merged nodes in order to check if we + * can merge the children, too. + *
+ * + * @param subTreeRoot + * root node of the sub-tree that is merged + */ + private void mergeSubTree(TreeNode subTreeRoot) { + if (subTreeRoot.children == null || subTreeRoot.children.isEmpty()) { + return; + } + + // lets first merge the grand children of the parentNode + for (TreeNode child : subTreeRoot.children) { + mergeSubTree(child); + } + + boolean performedMerge; + + do { + performedMerge = false; + for (int i = 0; !performedMerge && i < subTreeRoot.children.size(); i++) { + IEventTargetSpec elemSpec1 = + subTreeRoot.children.get(i).eventTarget.getSpecification(); + for (int j = i + 1; !performedMerge && j < subTreeRoot.children.size(); j++) { + IEventTargetSpec elemSpec2 = + subTreeRoot.children.get(j).eventTarget.getSpecification(); + if (elemSpec1.getSimilarity(elemSpec2)) { + TreeNode replacement = mergeTreeNodes + (subTreeRoot.children.get(i), subTreeRoot.children.get(j), true); + + subTreeRoot.children.set(i, replacement); + subTreeRoot.children.remove(j); + performedMerge = true; + i--; + break; + } + } + } + } + while (performedMerge); + } + + /** + *+ * merges two nodes with each other. Merging means registering the event target objects with + * each other for equality checks. Further it adds all children of both nodes to a new + * replacing node. Afterwards, all similar nodes of the replacement node are merged as well as + * long the recursive parameter is set to true. + *
+ * + * @param treeNode1 + * the first of the two nodes to be merged + * @param treeNode2 + * the second of the two nodes to be merged + * @param recursively + * if true, the merging also merges child nodes + * + * @return a tree node being the merge of the two provided nodes. + */ + private TreeNode mergeTreeNodes(TreeNode treeNode1, TreeNode treeNode2, boolean recursively) { + // and now a replacement node that is the merge of treeNode1 and treeNode2 is created + TreeNode replacement = new TreeNode(); + replacement.eventTarget = treeNode1.eventTarget; + if (treeNode1.children != null) { + for (TreeNode child : treeNode1.children) { + replacement.addChildNode(child); + } + } + if (treeNode2.children != null) { + for (TreeNode child : treeNode2.children) { + replacement.addChildNode(child); + } + } + + if (recursively) { + mergeSubTree(replacement); + } + + replacement.eventTarget.updateSpecification(treeNode2.eventTarget.getSpecification()); + + // finally, update the known nodes list + // if you don't do this getChildren will return wrong things and very bad things happen! + allNodes.remove(treeNode1.eventTarget); + allNodes.remove(treeNode2.eventTarget); + + // the following two lines are needed to preserve the references to the existing event + // targets. If two elements are the same, one should be deleted to make the elements + // singletons again. However, there may exist references to both objects. To preserve + // these, we simply register the equal event targets with each other so that an equals + // check can return true. + treeNode1.eventTarget.addEqualEventTarget(treeNode2.eventTarget); + treeNode2.eventTarget.addEqualEventTarget(treeNode1.eventTarget); + + allNodes.put(replacement.eventTarget, replacement); + + return replacement; + } + + /** + *+ * dumps an event target to the stream. A dump contains the toString() representation of the + * event target as well as an indented list of its children surrounded by braces. Therefore, + * not the event target itself but its tree node is provided to have an efficient access to its + * children + *
+ * + * @param out + * {@link PrintStream} where the eventTarget is dumped to + * @param node + * the eventTarget's tree node of which the string representation is dumped + * @param indent + * indent string of the dumping + */ + private void dumpeventTarget(PrintStream out, TreeNode node, String indent) { + out.print(indent); + out.print(node.eventTarget); + + if ((node.children != null) && (node.children.size() > 0)) { + out.println(" {"); + + for (TreeNode child : node.children) { + dumpeventTarget(out, child, indent + " "); + } + + out.print(indent); + out.print("}"); + } + + out.println(); + } + + /** + *+ * Retrieves the TreeNode associated with an event target. Returns null if no such TreeNode is + * found. + *
+ * + * @param element + * the event target + * + * @return associated TreeNode; null if no such node exists + */ + private TreeNode findNode(IEventTarget element) { + if (element == null) { + return null; + } + + TreeNode result = null; + + if (!validate) { + result = allNodes.get(element); + } + else { + for (Map.Entry+ * Used externally for tree traversal without providing direct access to the tree nodes + *
+ * + * @version 1.0 + * @author Patrick Harms, Steffen Herbold + */ + private class Traverser implements IHierarchicalEventTargetModel.Traverser+ * the stack of nodes on which the traverser currently works + *
+ */ + private Stack+ * initializes the traverser by adding the root node of the event target model to the stack + *
+ */ + private Traverser() { + nodeStack.push(new StackEntry(root, 0)); + } + + /* (non-Javadoc) + * @see de.ugoe.cs.autoquest.eventcore.guimodel.Traverser#firstChild() + */ + @Override + public T firstChild() { + return pushChild(0); + } + + /* (non-Javadoc) + * @see de.ugoe.cs.autoquest.eventcore.guimodel.Traverser#hasFirstChild() + */ + @Override + public boolean hasFirstChild() { + return + (nodeStack.peek().treeNode.children != null) && + (nodeStack.peek().treeNode.children.size() > 0); + } + + /* (non-Javadoc) + * @see de.ugoe.cs.autoquest.eventcore.guimodel.Traverser#nextSibling() + */ + @Override + public T nextSibling() { + int lastIndex = nodeStack.pop().index; + + T retval = pushChild(lastIndex + 1); + if (retval == null) { + pushChild(lastIndex); + } + + return retval; + } + + /* (non-Javadoc) + * @see de.ugoe.cs.autoquest.eventcore.guimodel.Traverser#hasNextSibling() + */ + @Override + public boolean hasNextSibling() { + boolean result = false; + if (nodeStack.size() > 1) { + StackEntry entry = nodeStack.pop(); + result = nodeStack.peek().treeNode.children.size() > (entry.index + 1); + pushChild(entry.index); + } + + return result; + } + + /* (non-Javadoc) + * @see de.ugoe.cs.autoquest.eventcore.guimodel.Traverser#parent() + */ + @Override + public T parent() { + T retval = null; + + if (nodeStack.size() > 1) { + nodeStack.pop(); + retval = nodeStack.peek().treeNode.eventTarget; + } + + return retval; + } + + /** + *+ * internal method used for changing the state of the traverser. I.e. to switch to a + * specific child event target of the current one. + *
+ */ + private T pushChild(int index) { + T retVal = null; + + if ((nodeStack.peek().treeNode.children != null) && + (nodeStack.peek().treeNode.children.size() > index)) + { + nodeStack.push + (new StackEntry(nodeStack.peek().treeNode.children.get(index), index)); + retVal = nodeStack.peek().treeNode.eventTarget; + } + + return retVal; + } + + /** + *+ * navigates the traverser to the given node in the event target model + *
+ */ + private boolean navigateTo(TreeNode node) { + if (hasFirstChild()) { + T childElement = firstChild(); + + while (childElement != null) { + if (childElement.equals(node.eventTarget)) { + return true; + } + else if (navigateTo(node)) { + return true; + } + else { + childElement = nextSibling(); + } + } + + parent(); + } + + return false; + } + + /** + *+ * internal class needed to fill the stack with nodes of the event target models and their + * respective index in the children of the parent node. + *
+ */ + private class StackEntry { + + /** */ + private TreeNode treeNode; + + /** */ + private int index; + + /** + *+ * creates a new stack entry. + *
+ */ + private StackEntry(TreeNode treeNode, int index) { + this.treeNode = treeNode; + this.index = index; + } + } + } + + /** + *+ * Used internally for building up the tree of event targets. + *
+ * + * @version 1.0 + * @author Patrick Harms, Steffen Herbold + */ + private class TreeNode implements Serializable { + + /** */ + private static final long serialVersionUID = 1L; + + /** + *+ * event target associated with the TreeNode. + *
+ */ + private T eventTarget; + + /** + *+ * Children of the TreeNode. + *
+ */ + private List+ * Adds a child to the current node while keeping all lists of nodes up to date + *
+ * + * @param eventTarget + * event target that will be associated with the new child + * + * @return the added child + */ + private TreeNode addChild(T eventTarget) { + if (children == null) { + children = new ArrayList+ * Adds a TreeNode as child to the current node. This way, the whole sub-tree is added. + *
+ * + * @param node + * child node that is added + * + * @return node that has been added + */ + private TreeNode addChildNode(TreeNode node) { + if (children == null) { + children = new ArrayList* Common interface for event targets. An event target can, e.g., be an element of a GUI or Web - * server. A concrete event-driven software platform can define its event targets through the + * server or VR. A concrete event-driven software platform can define its event targets through the * implementation of this interface. *
@@ -47,3 +47,4 @@ */ public String getStringIdentifier(); + } Index: trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/IEventTargetFactory.java =================================================================== --- trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/IEventTargetFactory.java (revision 2146) +++ trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/IEventTargetFactory.java (revision 2146) @@ -0,0 +1,64 @@ +// Copyright 2012 Georg-August-Universität Göttingen, Germany +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package de.ugoe.cs.autoquest.eventcore; + +/** + *+ * Common interface for event target factories. They are used while constructing hierarchical + * event target models. + *
+ * + * @version 1.0 + * @author Patrick Harms + */ +public interface IEventTargetFactory { + + /** + *+ * Instantiates a new {@link IHierarchicalEventTarget} from a given specification. + *
+ * + * @param specification + * specification of the new event target + * @param parent + * parent of the new event target + * + * @return created event target + * + * @throws EventTargetModelConfigurationException + * thrown if there is a problem during the creation of the event target + */ + public+ * Instantiates a new {@link IHierarchicalEventTarget} that represents a group of event targets. + * The returned object is defined to implement the interface but it must also derive from + * {@link HierarchicalEventTargetGroup}. This is to ensure type consistency in an event target + * model but to also allow simple group creations. + *
+ * + * @param groupName the name of the group to be created + * @param parent the parent element of the group + * @param hierarchicalEventTargetModel the model to which the group will belong + * @return + */ + public+ * Common interface for event target specifications. + *
+ * + * @version 1.1 + * @author Patrick Harms, Steffen Herbold + */ +public interface IEventTargetSpec extends Serializable { + + /** + *+ * Evaluates if two event target specifications are similar. Similar means that a heuristic + * determines that the two event target specifications describe the same event target. + *
+ * + * @param other + * specification whose similarity to this is evaluated + * + * @return true if the specifications are similar; false otherwise + */ + public boolean getSimilarity(IEventTargetSpec other); + + /** + *+ * Defines that {@link IEventTargetSpec} implementations have to define equals. + *
+ * + * @see Object#equals(Object) + */ + @Override + public boolean equals(Object other); + + /** + *+ * Defines that {@link IEventTargetSpec} implementations have to define hashCode. + *
+ * + * @see Object#hashCode() + */ + @Override + public int hashCode(); +} Index: trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/IHierarchicalEventTarget.java =================================================================== --- trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/IHierarchicalEventTarget.java (revision 2146) +++ trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/IHierarchicalEventTarget.java (revision 2146) @@ -0,0 +1,80 @@ +// Copyright 2012 Georg-August-Universität Göttingen, Germany +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package de.ugoe.cs.autoquest.eventcore; + +import java.io.Serializable; + +/** + *+ * Common interface for event targets. An event target can, e.g., be an element of a GUI or Web + * server or a VR. A concrete event-driven software platform can define its event targets through + * the implementation of this interface. This type of event target differ from those of the parent + * type in that they can build tree structures such as a {@link IHierarchicalEventTargetModel} + *
+ * + * @version 1.0 + * @author Steffen Herbold + */ +public interface IHierarchicalEventTarget extends IEventTarget, Serializable { + + /** + *+ * Returns the parent of the event target. + *
+ * + * @return the parent + */ + public IHierarchicalEventTarget getParent(); + + /** + *+ * Returns the specification of the event target. + *
+ * + * @return the specification + */ + public IEventTargetSpec getSpecification(); + + /** + *+ * Updates the specification of a event target with another specification, e.g., to add further + * known names of the event target. + *
+ * + * @param furtherSpec + * additional specification + */ + public void updateSpecification(IEventTargetSpec furtherSpec); + + /** + *+ * returns the event target model to which this event target belongs (if any). + *
+ * + * @return as described + */ + public IHierarchicalEventTargetModel getEventTargetModel(); + + /** + *+ * The {@link IHierarchicalEventTarget} that is passed by this function is equal to the current + * event target and will hereafter be treated as such. + *
+ * + * @param equalTarget + * event target that is equal + */ + public void addEqualEventTarget(IHierarchicalEventTarget equalTarget); +} Index: trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/IHierarchicalEventTargetModel.java =================================================================== --- trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/IHierarchicalEventTargetModel.java (revision 2146) +++ trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/IHierarchicalEventTargetModel.java (revision 2146) @@ -0,0 +1,150 @@ +// Copyright 2015 Georg-August-Universität Göttingen, Germany +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package de.ugoe.cs.autoquest.eventcore; + +import java.util.List; + +/** + *+ * This interface can be used to wrap tree like event target structures. This allows rather + * flexible implementations of such structures and can either be rather concrete, e.g., for + * GUI models, or rather generic for any type of event target. The interface provides a way to + * traverse the target structure by retrieving a traverser. + *
+ * + * @author Patrick Harms + */ +public interface IHierarchicalEventTargetModel+ * Returns all children of the provided event target or null, if it does not have any or the + * node is unknown. + *
+ * + * @param eventTarget + * the event target of which the children shall be returned + * + * @return As described + */ + List+ * Returns the parent event target of the provided one or null, if it does not have a + * parent (i.e. if it is a root node) or if the node is unknown. + *
+ * + * @param eventTarget + * the event target of which the parent shall be returned + * + * @return As described + */ + T getParent(T eventTarget); + + /** + *+ * Returns all root event targets of the model or an empty list, if the model is empty + *
+ * + * @return As described + */ + List+ * This interface defines the methods to be provided by model traversers + *
+ * + * @author Patrick Harms + */ + public interface Traverser+ * returns the first child of the current event target. On the first call of this method on + * the traverser the first of the root event targets of the event target model is returned. + * If the current event target does not have children, the method returns null. If the + * event target model is empty, then a call to this method will return null. The returned + * event target is the next one the traverser points to. + *
+ * + * @return as described. + */ + T firstChild(); + + /** + *+ * returns true, if the current event target has a first child, i.e. if the next call to the + * method {@link #firstChild()} would return an event target or null. + *
+ * + * @return as described + */ + boolean hasFirstChild(); + + /** + *+ * returns the next sibling of the current event target. If there is no further sibling, + * null is returned. If the current event target is one of the root nodes, the next root + * node of the event target model is returned. The returned event target is the next one + * the traverser points to. + *
+ * + * @return as described + */ + T nextSibling(); + + /** + *+ * returns true, if the current event target has a further sibling, i.e. if a call to the + * method {@link #nextSibling()} will return an event target + *
+ * + * @return as described + */ + boolean hasNextSibling(); + + /** + *+ * returns the parent event target of the current event target. If the current event target + * is a root node, null is returned. If there is no current event target yet as the method + * {@link #firstChild()} was not called yet, null is returned. + *
+ * + * @return as described + */ + T parent(); + + } +} Index: trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/guimodel/AbstractDefaultGUIElement.java =================================================================== --- trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/guimodel/AbstractDefaultGUIElement.java (revision 2133) +++ trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/guimodel/AbstractDefaultGUIElement.java (revision 2146) @@ -15,6 +15,5 @@ package de.ugoe.cs.autoquest.eventcore.guimodel; -import java.util.LinkedList; -import java.util.List; +import de.ugoe.cs.autoquest.eventcore.AbstractDefaultHierarchicalEventTarget; /** @@ -26,5 +25,7 @@ * @author Patrick Harms */ -public abstract class AbstractDefaultGUIElement implements IGUIElement { +public abstract class AbstractDefaultGUIElement extends AbstractDefaultHierarchicalEventTarget + implements IGUIElement +{ /** @@ -34,25 +35,4 @@ */ public static final long serialVersionUID = 1L; - - /** - *- * Specification of the GUI element - *
- */ - private final IGUIElementSpec specification; - - /** - *- * Reference to the parent element - *
- */ - private IGUIElement parent; - - /** - *- * List of other GUI elements being equal to this - *
- */ - private List- * the reference to the GUI model to which this GUI element belongs. - *
- */ - private GUIModel guiModel; - - /** - *- * the hash code of this object - *
- */ - private int hashCode; /** @@ -88,34 +54,5 @@ */ public AbstractDefaultGUIElement(IGUIElementSpec specification, IGUIElement parent) { - this.specification = specification; - this.usageObserved = false; - setParent(parent); - - if (specification != null) { - this.hashCode = specification.hashCode(); - } - else { - this.hashCode = 0; - } - } - - /* - * (non-Javadoc) - * - * @see de.ugoe.cs.tasktree.guimodel.GUIElement#getSpecification() - */ - @Override - public IGUIElementSpec getSpecification() { - return specification; - } - - /* - * (non-Javadoc) - * - * @see de.ugoe.cs.autoquest.eventcore.guimodel.IGUIElement#getParent() - */ - @Override - public IGUIElement getParent() { - return parent; + super(specification, parent); } @@ -125,60 +62,29 @@ @Override public GUIModel getGUIModel() { - return guiModel; + return (GUIModel) super.getEventTargetModel(); } - /* - * (non-Javadoc) - * - * @see de.ugoe.cs.autoquest.eventcore.guimodel.IGUIElement#addEqualGUIElement(IGUIElement) + /* (non-Javadoc) + * @see de.ugoe.cs.autoquest.eventcore.AbstractDefaultHierarchicalEventTarget#getParent() */ @Override - public void addEqualGUIElement(IGUIElement equalElement) { - if (!(equalElement instanceof AbstractDefaultGUIElement)) { - throw new IllegalArgumentException - ("this implementation can only handle other AbstractDefaultGUIElements"); - } - - AbstractDefaultGUIElement other = (AbstractDefaultGUIElement) equalElement; - - synchronized (AbstractDefaultGUIElement.class) { - if (this.equalGUIElements == null) { - if (other.equalGUIElements == null) { - this.equalGUIElements = new LinkedList- * updates the parent node of this node if required due to model restructuring - *
- */ - void setParent(IGUIElement newParent) { - synchronized (AbstractDefaultGUIElement.class) { - // all equal GUI elements must have the same parent. Otherwise, they are not equal - // anymore and we would have discrepancies on the return value of getParent() on - // equal GUI elements. - this.parent = newParent; - if (equalGUIElements != null) { - for (AbstractDefaultGUIElement candidate : equalGUIElements) { - candidate.parent = newParent; - } - } - } - } - - /** - *- * used to set the GUI model to which this GUI element belongs. Will be set automatically, if - * used in combination with {@link GUIModel}; - *
- * - * @param guiModel - */ - void setGUIModel(GUIModel guiModel) { - this.guiModel = guiModel; - } - - /** - *- * Adds an {@link AbstractDefaultGUIElement} as equal to a list of - * {@link AbstractDefaultGUIElement}s if and only if it is not already contained. - *
- * - * @param equalElementsList - * list of {@link AbstractDefaultGUIElement} to which the GUI element is added - * @param guiElement - * GUI element to be added - */ - private void addIfNotContained(List- * A property mapping that defines to which Java class is created given the type of the GUI + * A property mapping that defines which Java class is created given the type of the GUI * element found in the specification. *
@@ -71,14 +76,31 @@ - /* - * (non-Javadoc) - * - * @see - * de.ugoe.cs.autoquest.eventcore.guimodel.IGUIElementFactory#instantiateGUIElement(de.ugoe.cs.autoquest - * .eventcore.guimodel.IGUIElementSpec, de.ugoe.cs.autoquest.eventcore.guimodel.IGUIElement) - */ + /* (non-Javadoc) + * @see IEventTargetFactory#instantiateEventTarget(IEventTargetSpec, IHierarchicalEventTarget) + */ + @SuppressWarnings("unchecked") @Override - public IGUIElement instantiateGUIElement(IGUIElementSpec specification, IGUIElement parent) - throws GUIModelConfigurationException + public- * This class is a dummy GUI element to represent groups of GUI elements. A group of GUI elements - * can be integrated in any GUI model using the method - * {@link GUIModel#groupGUIElements(java.util.List, String)}. A group has the same behavior as - * any other parent GUI element. + * implementation of event target groups for GUI elements *
* * @author Patrick Harms */ -public class GUIElementGroup extends AbstractDefaultGUIElement { +public class GUIElementGroup extends HierarchicalEventTargetGroup implements IGUIElement { - /** - *- * default serial version UID - *
- */ + /** */ private static final long serialVersionUID = 1L; - /** - * the list of grouped GUIElements - */ - private List- * returns the list of GUI elements belonging to this group. - *
- * - * @return the GUI elements belonging to this group - * - */ - public List- * allows adding a new GUI element to the group - *
- * - * @param guiElement the new member of the group - */ - void addToGroup(IGUIElement guiElement) { - this.groupedGUIElements.add(guiElement); } @@ -174,4 +163,14 @@ /* (non-Javadoc) + * @see de.ugoe.cs.autoquest.eventcore.IEventTargetSpec#getSimilarity(IEventTargetSpec) + */ + @Override + public boolean getSimilarity(IEventTargetSpec other) { + return + (other instanceof GroupSpecification) && + name.equals(((GroupSpecification) other).name); + } + + /* (non-Javadoc) * @see de.ugoe.cs.autoquest.eventcore.guimodel.IGUIElementSpec#getType() */ @@ -189,15 +188,4 @@ } - /* (non-Javadoc) - * @see de.ugoe.cs.autoquest.eventcore.guimodel.IGUIElementSpec#getSimilarity(IGUIElementSpec) - */ - @Override - public boolean getSimilarity(IGUIElementSpec other) { - return - (other instanceof GroupSpecification) && - name.equals(((GroupSpecification) other).name); - } - } - } Index: trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/guimodel/GUIElementTree.java =================================================================== --- trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/guimodel/GUIElementTree.java (revision 2133) +++ trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/guimodel/GUIElementTree.java (revision 2146) @@ -20,8 +20,8 @@ import java.util.Map; +import de.ugoe.cs.autoquest.eventcore.EventTargetModelException; +import de.ugoe.cs.autoquest.eventcore.IEventTargetFactory; import de.ugoe.cs.autoquest.eventcore.guimodel.GUIElementFactory; import de.ugoe.cs.autoquest.eventcore.guimodel.GUIModel; -import de.ugoe.cs.autoquest.eventcore.guimodel.GUIModelException; -import de.ugoe.cs.autoquest.eventcore.guimodel.IGUIElementFactory; /** @@ -30,7 +30,8 @@ * *- * The GUIElementTree represents the hierarchical structure of the GUI elements "as it is" currently during - * a session. It may change during the session due to creation and destruction of GUI elements. The parameter - * T represents the id type of the GUI elements that are handled internally. + * The GUIElementTree represents the hierarchical structure of the GUI elements "as it is" + * currently during a session. It may change during the session due to creation and destruction + * of GUI elements. The parameter T represents the id type of the GUI elements that are handled + * internally. *
* @@ -84,7 +85,5 @@ * */ - private IGUIElementFactory guiElementFactory = GUIElementFactory.getInstance(); - - + private IEventTargetFactory guiElementFactory = GUIElementFactory.getInstance(); /** @@ -127,10 +126,10 @@ * the GUI element specification * - * @throws GUIModelException if the GUI element can not be added to the underlying GUI model + * @throws EventTargetModelException if the GUI element can not be added to the underlying GUI model */ public void add(T guiElementID, T parentID, IGUIElementSpec guiElementSpec) - throws GUIModelException + throws EventTargetModelException { IGUIElement guiElement = guiElements.get(guiElementID); @@ -161,5 +160,5 @@ } - guiElement = guiModel.integratePath(guiElementPath, guiElementFactory); + guiElement = (IGUIElement) guiModel.integratePath(guiElementPath, guiElementFactory); guiElements.put(guiElementID, guiElement); } Index: trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/guimodel/GUIModel.java =================================================================== --- trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/guimodel/GUIModel.java (revision 2133) +++ trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/guimodel/GUIModel.java (revision 2146) @@ -15,17 +15,8 @@ package de.ugoe.cs.autoquest.eventcore.guimodel; -import java.io.OutputStream; -import java.io.PrintStream; import java.io.Serializable; -import java.io.UnsupportedEncodingException; -import java.util.ArrayList; -import java.util.HashMap; -import java.util.LinkedList; import java.util.List; -import java.util.Map; -import java.util.Stack; -import java.util.logging.Level; -import de.ugoe.cs.util.console.Console; +import de.ugoe.cs.autoquest.eventcore.HierarchicalEventTargetModel; /** @@ -34,5 +25,5 @@ * platform independent. It may have several root nodes, as some GUIs are made up of several Frames * being independent from each other. The GUI model is filled using the - * {@link #integratePath(List, IGUIElementFactory)} method. + * {@link #integratePath(List, de.ugoe.cs.autoquest.eventcore.IEventTargetFactory)} method. * * @@ -40,5 +31,7 @@ * @author Patrick Harms, Steffen Herbold */ -public class GUIModel implements Serializable { +public class GUIModel extends HierarchicalEventTargetModel- * The root node of the tree not provided externally. - *
- */ - private TreeNode root = new TreeNode(); - - /** - *- * A map with all nodes currently known - *
- */ - private Map- * true, if internal validation is switched on, false else - *
- */ - private boolean validate = false; - - /** - *- * Default constructor to create a GUI model without internal validation + * instantiate a default unvalidated model *
* */ public GUIModel() { - this(false); + super(); } /** *- * creates a GUI model, that internally validates itself by checking on access to nodes, - * if several GUI elements pretend to be equal or if several distinct GUI elements have the - * same child. + * instantiate a model that will validate itself internally if the provided parameters is set + * to true. This is typically rather slow. *
- * - * @param validate - * true if internal validation shall be switched on (bad performance), false else - * */ public GUIModel(boolean validate) { - this.validate = validate; + super(validate); } - /** - *- * Integrates a path of GUI elements into the GUI model. The GUI model itself is a tree and - * therefore a set of different paths through the tree that start with a root node and end with - * a leaf node. Such a path can be added to the tree. The method checks, if any of the GUI - * elements denoted by the path already exists. If so, it reuses it. It may therefore also - * return an existing GUI element being the leaf node of the provided path. If a GUI element of - * the path does not exist yet, it creates a new one using the provided GUI element factory. - *
- *- * If a GUI element specification describes an existing GUI element or not is determined through - * comparing the GUI element specifications of the existing GUI elements with the ones provided - * in the path. The comparison is done using the - * {@link IGUIElementSpec#getSimilarity(IGUIElementSpec)} method. The comparison is only done on - * the correct levels. I.e. the currently known root elements of the tree are only compared to - * the first element in the path. If the correct one is found or created, its children are - * compared only to the second specification in the path, and so on. - *
- *- * The returned GUI elements are singletons. I.e. it is tried to return always the identical - * object for the same denoted element. However, while creating the GUI model, the similarity of - * GUI elements may change. Therefore, the method might determine, that two formerly different - * nodes are now similar. (This may happen, e.g. if GUI elements do not have initial names which - * are set afterwards. Therefore, first they are handled differently and later they can be - * identified as being the same.) In such a case, there are already several GUI element objects - * instantiated for the same GUI element. The singleton paradigm gets broken. Therefore, such - * GUI element objects are registered with each other, so that their equal method can determine - * equality again correctly, although the objects are no singletons anymore. - *
- * - * @param guiElementPath - * the path to integrate into the model - * @param guiElementFactory - * the GUI element factory to be used for instantiating GUI element objects - * - * @return The GUI element object representing the GUI element denoted by the provided path - * - * @throws GUIModelException - * thrown in cases such as the GUI element object could not be instantiated - * @throws IllegalArgumentException - * if the provided path is invalid. - */ - public IGUIElement integratePath(List guiElementPath, - IGUIElementFactory guiElementFactory) - throws GUIModelException, IllegalArgumentException - { - if ((guiElementPath == null) || (guiElementPath.size() <= 0)) { - throw new IllegalArgumentException("GUI element path must contain at least one element"); - } - - List- * Returns all children of the provided GUI element or null, if it does not have any or the node - * is unknown. - *
- * - * @param guiElement - * the GUI element of which the children shall be returned - * - * @return As described - */ - public List- * Returns the parent GUI element of the provided GUI element or null, if it does not have a - * parent (i.e. if it is a root node) or if the node is unknown. - *
- * - * @param guiElement - * the GUI element of which the parent shall be returned - * - * @return As described - */ - public IGUIElement getParent(IGUIElement guiElement) { - IGUIElement parent = null; - - for (Map.Entry- * Returns all root GUI elements of the model or an empty list, if the model is empty - *
- * - * @return As described - */ - public List- * dumps the GUI model to the provided stream. Each node is represented through its toString() - * method. If a node has children, those are dumped indented and surrounded by braces. - *
- * - * @param out - * The stream to dump the textual representation of the model to - * @param encoding - * The encoding to be used while dumping - */ - public void dump(OutputStream out, String encoding) { - PrintStream stream; - - if (out instanceof PrintStream) { - stream = (PrintStream) out; - } - else { - String enc = encoding == null ? "UTF-8" : encoding; - try { - stream = new PrintStream(out, true, enc); - } - catch (UnsupportedEncodingException e) { - throw new IllegalArgumentException("encodind " + enc + " not supported"); - } - } - - for (TreeNode node : root.children) { - dumpGUIElement(stream, node, ""); - } - } - - /** - *- * This method groups the provided GUI elements under a common parent GUI element. The current - * parent GUI element of the GUI elements to group must be the same. If the GUI elements to - * be grouped are the whole list of children of the same parent, nothing is changed. - *
- * - * @param guiElements the list of GUI elements to be grouped - * @param groupName the name of the GUI element group to be created - * - * @return the GUI element representing the group, or null, if the provided list of GUI elements - * is empty - * - * @throws IllegalArgumentException - * if not all GUI elements to be merged share the same parent, if one of the - * parameters is null, or if one of the provided GUI elements does not belong to - * the model - */ - public IGUIElement groupGUIElements(List- * By calling this method, the GUIModel is traversed and similar nodes are merged. - *
- * - */ - public void condenseModel() { - mergeSubTree(root); - } - - /** - *- * Merges the tree nodes of two GUI elements. The GUI elements need to have the same parent. - * They are merged recursively, i.e. also their children are merged. - *
- * - * @param guiElement1 - * the first merge GUI element - * @param guiElement2 - * the second merge GUI element - * - * @return the result of the merge - * - * @throws IllegalArgumentException - * thrown if the two GUI elements do not have the same parent - */ - public IGUIElement mergeGUIElements(IGUIElement guiElement1, IGUIElement guiElement2) - throws IllegalArgumentException - { - return mergeGUIElements(guiElement1, guiElement2, true); - } - - /** - *
- * Merges the tree nodes of two GUI elements. The GUI elements need to have the same parent.
- * If the recursively parameter is set to true, the children of the GUI elements
- * are merged, as well, as long as they are similar. If the parameter is false, the children
- * are not merged. In this case the resulting GUI element has all children of both merged GUI
- * elements.
- *
- * internally integrates a path as the children of the provided parent node. This method is - * recursive and calls itself, for the child of the parent node, that matches the first element - * in the remaining path. - *
- * - * @param parentNode - * the parent node to add children for - * @param guiElementPath - * the path of children to be created starting with the parent node - * @param guiElementFactory - * the GUI element factory to be used for instantiating GUI element objects - * - * @return The GUI element object representing the GUI element denoted by the provided path - * - * @throws GUIModelException - * thrown in cases such as the GUI element object could not be instantiated - */ - private IGUIElement integratePath(TreeNode parentNode, - List remainingPath, - IGUIElementFactory guiElementFactory) - throws GUIModelException - { - IGUIElementSpec specToIntegrateElementFor = remainingPath.remove(0); - - TreeNode child = findEqualChild(parentNode, specToIntegrateElementFor); - if (child == null) { - IGUIElement newElement = - guiElementFactory.instantiateGUIElement(specToIntegrateElementFor, - parentNode.guiElement); - - if (newElement instanceof AbstractDefaultGUIElement) { - ((AbstractDefaultGUIElement) newElement).setGUIModel(this); - } - - child = parentNode.addChild(newElement); - allNodes.put(child.guiElement, child); - } - - if (remainingPath.size() > 0) { - return integratePath(child, remainingPath, guiElementFactory); - } - else { - return child.guiElement; - } - } - - /** - *- * Searches the children of a tree node to see if the {@link IGUIElementSpec} of equals the - * specification of the {@link TreeNode#guiElement} of the child. If a match is found, the child - * is returned. - *
- * - * @param parentNode - * parent node whose children are searched - * @param specToMatch - * specification that is searched for - * @return matching child node or null if no child matches - */ - private TreeNode findEqualChild(TreeNode parentNode, IGUIElementSpec specToMatch) { - if (parentNode.children != null) { - for (TreeNode child : parentNode.children) { - if (specToMatch.equals(child.guiElement.getSpecification())) { - return child; - } - } - } - return null; - } - - /** - *- * Merges all similar nodes in the sub-tree of the GUI model defined by the subTreeRoot. - *
- *- * The merging order is a bottom-up. This means, that we first call mergeSubTree recursively for - * the grand children of the subTreeRoot, before we merge subTreeRoot. - *
- *- * The merging strategy is top-down. This means, that every time we merge two child nodes, we - * call mergeSubTree recursively for all children of the merged nodes in order to check if we - * can merge the children, too. - *
- * - * @param subTreeRoot - * root node of the sub-tree that is merged - */ - private void mergeSubTree(TreeNode subTreeRoot) { - if (subTreeRoot.children == null || subTreeRoot.children.isEmpty()) { - return; - } - - // lets first merge the grand children of the parentNode - for (TreeNode child : subTreeRoot.children) { - mergeSubTree(child); - } - - boolean performedMerge; - - do { - performedMerge = false; - for (int i = 0; !performedMerge && i < subTreeRoot.children.size(); i++) { - IGUIElementSpec elemSpec1 = - subTreeRoot.children.get(i).guiElement.getSpecification(); - for (int j = i + 1; !performedMerge && j < subTreeRoot.children.size(); j++) { - IGUIElementSpec elemSpec2 = - subTreeRoot.children.get(j).guiElement.getSpecification(); - if (elemSpec1.getSimilarity(elemSpec2)) { - TreeNode replacement = mergeTreeNodes - (subTreeRoot.children.get(i), subTreeRoot.children.get(j), true); - - subTreeRoot.children.set(i, replacement); - subTreeRoot.children.remove(j); - performedMerge = true; - i--; - break; - } - } - } - } - while (performedMerge); - } - - /** - *- * merges two nodes with each other. Merging means registering the GUI element objects with each - * other for equality checks. Further it adds all children of both nodes to a new replacing - * node. Afterwards, all similar nodes of the replacement node are merged as well as long - * the recursive parameter is set to true. - *
- * - * @param treeNode1 - * the first of the two nodes to be merged - * @param treeNode2 - * the second of the two nodes to be merged - * @param recursively - * if true, the merging also merges child nodes - * - * @return a tree node being the merge of the two provided nodes. - */ - private TreeNode mergeTreeNodes(TreeNode treeNode1, TreeNode treeNode2, boolean recursively) { - // and now a replacement node that is the merge of treeNode1 and treeNode2 is created - TreeNode replacement = new TreeNode(); - replacement.guiElement = treeNode1.guiElement; - if (treeNode1.children != null) { - for (TreeNode child : treeNode1.children) { - replacement.addChildNode(child); - } - } - if (treeNode2.children != null) { - for (TreeNode child : treeNode2.children) { - replacement.addChildNode(child); - } - } - - if (recursively) { - mergeSubTree(replacement); - } - - replacement.guiElement.updateSpecification(treeNode2.guiElement.getSpecification()); - - // finally, update the known nodes list - // if you don't do this getChildren will return wrong things and very bad things happen! - allNodes.remove(treeNode1.guiElement); - allNodes.remove(treeNode2.guiElement); - - // the following two lines are needed to preserve the references to the existing GUI - // elements. If two elements are the same, one should be deleted to make the elements - // singletons again. However, there may exist references to both objects. To preserve - // these, we simply register the equal GUI elements with each other so that an equals - // check can return true. - treeNode1.guiElement.addEqualGUIElement(treeNode2.guiElement); - treeNode2.guiElement.addEqualGUIElement(treeNode1.guiElement); - - allNodes.put(replacement.guiElement, replacement); - - return replacement; - } - - /** - *- * dumps a GUI element to the stream. A dump contains the toString() representation of the GUI - * element as well as a indented list of its children surrounded by braces. Therefore, not the - * GUI element itself but its tree node is provided to have an efficient access to its children - *
- * - * @param out - * {@link PrintStream} where the guiElement is dumped to - * @param node - * the guiElement's tree node of which the string representation is dumped - * @param indent - * indent string of the dumping - */ - private void dumpGUIElement(PrintStream out, TreeNode node, String indent) { - out.print(indent); - out.print(node.guiElement); - - if ((node.children != null) && (node.children.size() > 0)) { - out.println(" {"); - - for (TreeNode child : node.children) { - dumpGUIElement(out, child, indent + " "); - } - - out.print(indent); - out.print("}"); - } - - out.println(); - } - - /** - *- * Retrieves the TreeNode associated with a GUI element. Returns null if no such TreeNode is - * found. - *
- * - * @param element - * the GUI element - * @return associated TreeNode; null if no such node exists - */ - private TreeNode findNode(IGUIElement element) { - if (element == null) { - return null; - } - - TreeNode result = null; - - if (!validate) { - result = allNodes.get(element); - } - else { - for (Map.Entry- * Used externally for tree traversal without providing direct access to the tree nodes - *
- * - * @version 1.0 - * @author Patrick Harms, Steffen Herbold - */ - public class Traverser { - - /** - *- * the stack of nodes on which the traverser currently works - *
- */ - private Stack- * initializes the traverser by adding the root node of the GUI model to the stack - *
- */ - private Traverser() { - nodeStack.push(new StackEntry(root, 0)); - } - - /** - *- * returns the first child of the current GUI element. On the first call of this method on - * the traverser the first of the root GUI elements of the GUI model is returned. If the - * current GUI element does not have children, the method returns null. If the GUI model - * is empty, then a call to this method will return null. The returned GUI element is the - * next one the traverser points to. - *
- * - * @return as described. - */ - public IGUIElement firstChild() { - return pushChild(0); - } - - /** - *- * returns true, if the current GUI element has a first child, i.e. if the next call to the - * method {@link #firstChild()} would return a GUI element or null. - *
- * - * @return as described - */ - public boolean hasFirstChild() { - return - (nodeStack.peek().treeNode.children != null) && - (nodeStack.peek().treeNode.children.size() > 0); - } - - /** - *- * returns the next sibling of the current GUI element. If there is no further sibling, - * null is returned. If the current GUI element is one of the root nodes, the next root - * node of the GUI model is returned. The returned GUI element is the next one the - * traverser points to. - *
- * - * @return as described - */ - public IGUIElement nextSibling() { - int lastIndex = nodeStack.pop().index; - - IGUIElement retval = pushChild(lastIndex + 1); - if (retval == null) { - pushChild(lastIndex); - } - - return retval; - } - - /** - *- * returns true, if the current GUI element has a further sibling, i.e. if a call to the - * method {@link #nextSibling()} will return a GUI element; - *
- * - * @return as described - */ - public boolean hasNextSibling() { - boolean result = false; - if (nodeStack.size() > 1) { - StackEntry entry = nodeStack.pop(); - result = nodeStack.peek().treeNode.children.size() > (entry.index + 1); - pushChild(entry.index); - } - - return result; - } - - /** - *- * returns the parent GUI element of the current GUI element. If the current GUI element - * is a root node, null is returned. If there is no current GUI element yet as the method - * {@link #firstChild()} was not called yet, null is returned. - *
- * - * @return as described - */ - public IGUIElement parent() { - IGUIElement retval = null; - - if (nodeStack.size() > 1) { - nodeStack.pop(); - retval = nodeStack.peek().treeNode.guiElement; - } - - return retval; - } - - /** - *- * internal method used for changing the state of the traverser. I.e. to switch to a - * specific child GUI element of the current one. - *
- */ - private IGUIElement pushChild(int index) { - IGUIElement retVal = null; - - if ((nodeStack.peek().treeNode.children != null) && - (nodeStack.peek().treeNode.children.size() > index)) - { - nodeStack.push - (new StackEntry(nodeStack.peek().treeNode.children.get(index), index)); - retVal = nodeStack.peek().treeNode.guiElement; - } - - return retVal; - } - - /** - *- * navigates the traverser to the given node in the GUI model - *
- */ - private boolean navigateTo(TreeNode node) { - if (hasFirstChild()) { - IGUIElement childElement = firstChild(); - - while (childElement != null) { - if (childElement.equals(node.guiElement)) { - return true; - } - else if (navigateTo(node)) { - return true; - } - else { - childElement = nextSibling(); - } - } - - parent(); - } - - return false; - } - - /** - *- * internal class needed to fill the stack with nodes of the GUI models and their - * respective index in the children of the parent node. - *
- */ - private class StackEntry { - - /** */ - private TreeNode treeNode; - - /** */ - private int index; - - /** - *- * creates a new stack entry. - *
- */ - private StackEntry(TreeNode treeNode, int index) { - this.treeNode = treeNode; - this.index = index; - } - } - } - - /** - *- * Used internally for building up the tree of GUI elements. - *
- * - * @version 1.0 - * @author Patrick Harms, Steffen Herbold - */ - private static class TreeNode implements Serializable { - - /** */ - private static final long serialVersionUID = 1L; - - /** - *- * GUI element associated with the TreeNode. - *
- */ - private IGUIElement guiElement; - - /** - *- * Children of the TreeNode. - *
- */ - private List- * Adds a child to the current node while keeping all lists of nodes up to date - *
- * - * @param guiElement - * GUI element that will be associated with the new child - * @return the added child - */ - private TreeNode addChild(IGUIElement guiElement) { - if (children == null) { - children = new ArrayList- * Adds a TreeNode as child to the current node. This way, the whole sub-tree is added. - *
- * - * @param node - * child node that is added - * @return node that has been added - */ - private TreeNode addChildNode(TreeNode node) { - if (children == null) { - children = new ArrayList- * Exception that is thrown if there is a failure during the creation of a {@link IGUIElement} by - * the {@link GUIElementFactory}. - *
- * - * @version 1.0 - * @author Patrick Harms - */ -public class GUIModelConfigurationException extends GUIModelException { - - /** - *- * Id for object serialization. - *
- */ - private static final long serialVersionUID = 1L; - - /** - *- * Constructor. Creates a new GUIModelConfigurationException. - *
- */ - public GUIModelConfigurationException() { - super(); - } - - /** - *- * Constructor. Creates a new GUIModelConfigurationException. - *
- * - * @param message - * message of the exception - */ - public GUIModelConfigurationException(String message) { - super(message); - } - - /** - *- * Constructor. Creates a new GUIModelConfigurationException. - *
- * - * @param cause - * cause of the exception - */ - public GUIModelConfigurationException(Throwable cause) { - super(cause); - } - - /** - *- * Constructor. Creates a new GUIModelConfigurationException. - *
- * - * @param message - * message of the exception - * @param cause - * cause of the exception - */ - public GUIModelConfigurationException(String message, Throwable cause) { - super(message, cause); - } - -} Index: trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/guimodel/GUIModelException.java =================================================================== --- trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/guimodel/GUIModelException.java (revision 2133) +++ (revision ) @@ -1,81 +1,0 @@ -// Copyright 2012 Georg-August-Universität Göttingen, Germany -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -package de.ugoe.cs.autoquest.eventcore.guimodel; - -/** - *- * Exception that is thrown if there are problems with the {@link GUIModel}. - *
- * - * @version 1.0 - * @author Patrick Harms - */ -public class GUIModelException extends Exception { - - /** - *- * Id for object serialization. - *
- */ - private static final long serialVersionUID = 1L; - - /** - *- * Constructor. Creates a new GUIModelException. - *
- */ - public GUIModelException() { - super(); - } - - /** - *- * Constructor. Creates a new GUIModelException. - *
- * - * @param message - * message of the exception - */ - public GUIModelException(String message) { - super(message); - } - - /** - *- * Constructor. Creates a new GUIModelException. - *
- * - * @param cause - * cause of the exception - */ - public GUIModelException(Throwable cause) { - super(cause); - } - - /** - *- * Constructor. Creates a new GUIModelException. - *
- * - * @param message - * message of the exception - * @param cause - * cause of the exception - */ - public GUIModelException(String message, Throwable cause) { - super(message, cause); - } - -} Index: trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/guimodel/IGUIElement.java =================================================================== --- trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/guimodel/IGUIElement.java (revision 2133) +++ trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/guimodel/IGUIElement.java (revision 2146) @@ -15,5 +15,5 @@ package de.ugoe.cs.autoquest.eventcore.guimodel; -import de.ugoe.cs.autoquest.eventcore.IEventTarget; +import de.ugoe.cs.autoquest.eventcore.IHierarchicalEventTarget; /** @@ -25,6 +25,6 @@ * @author Patrick Harms */ -public interface IGUIElement extends IEventTarget { - +public interface IGUIElement extends IHierarchicalEventTarget { + /** *@@ -99,26 +99,4 @@ /** *
- * Updates the specification of a GUI element with another specification, e.g., to add further - * known names of the GUI element. - *
- * - * @param furtherSpec - * additional specification - */ - public void updateSpecification(IGUIElementSpec furtherSpec); - - /** - *- * The {@link IGUIElement} that is passed by this function is equal to the current GUI element - * and will hereafter be treated as such. - *
- * - * @param guiElement - * GUI element that is equal - */ - public void addEqualGUIElement(IGUIElement equalElement); - - /** - ** Returns a measure for the distance of this {@link IGUIElement} to the provided one. Distance * means a measure for the distance in display of the rendered GUI. The returned values must be Index: trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/guimodel/IGUIElementFactory.java =================================================================== --- trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/guimodel/IGUIElementFactory.java (revision 2133) +++ (revision ) @@ -1,43 +1,0 @@ -// Copyright 2012 Georg-August-Universität Göttingen, Germany -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -package de.ugoe.cs.autoquest.eventcore.guimodel; - -/** - *
- * Common interface for GUI element factories. - *
- * - * @version 1.0 - * @author Patrick Harms - */ -public interface IGUIElementFactory { - - /** - *- * Instantiates a new {@link IGUIElement} from a given specification. - *
- * - * @param specification - * specification of the new GUI element - * @param parent - * parent of the new GUI element - * @return created GUI element - * @throws GUIModelConfigurationException - * thrown if there is a problem during the creation of the GUI element - */ - public IGUIElement instantiateGUIElement(IGUIElementSpec specification, IGUIElement parent) - throws GUIModelConfigurationException; - -} Index: trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/guimodel/IGUIElementSpec.java =================================================================== --- trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/guimodel/IGUIElementSpec.java (revision 2133) +++ trunk/autoquest-core-events/src/main/java/de/ugoe/cs/autoquest/eventcore/guimodel/IGUIElementSpec.java (revision 2146) @@ -17,4 +17,6 @@ import java.io.Serializable; +import de.ugoe.cs.autoquest.eventcore.IEventTargetSpec; + /** *@@ -25,5 +27,5 @@ * @author Patrick Harms, Steffen Herbold */ -public interface IGUIElementSpec extends Serializable { +public interface IGUIElementSpec extends Serializable, IEventTargetSpec { /** @@ -51,34 +53,3 @@ public String[] getTypeHierarchy(); - /** - *
- * Evaluates if two GUI specifications are similar. Similar means that a heuristic determines - * that the two GUI specifications describe the same GUI element. - *
- * - * @param other - * specification whose similarity to this is evaluated - * @return true if the specifications are similar; false otherwise - */ - public boolean getSimilarity(IGUIElementSpec other); - - /** - *- * Defines that {@link IGUIElement} implementations have to define equals. - *
- * - * @see Object#equals(Object) - */ - @Override - public boolean equals(Object other); - - /** - *- * Defines that {@link IGUIElement} implementations have to define hashCode. - *
- * - * @see Object#hashCode() - */ - @Override - public int hashCode(); }