Ignore:
Timestamp:
09/03/12 10:20:16 (12 years ago)
Author:
pharms
Message:
  • removed find bugs warning
  • added some java doc
File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/quest-core-events/src/main/java/de/ugoe/cs/quest/eventcore/guimodel/GUIModel.java

    r709 r746  
    33import java.io.OutputStream; 
    44import java.io.PrintStream; 
     5import java.io.UnsupportedEncodingException; 
    56import java.util.ArrayList; 
    67import java.util.LinkedList; 
    78import java.util.List; 
     9import java.util.logging.Level; 
     10 
     11import de.ugoe.cs.util.console.Console; 
    812 
    913/** 
    1014 * <p> 
    11  * The goal of a GUI model is to correctly l 
     15 * A GUI model is a tree of {@link IGUIElements} and represents a complete GUI of a software. It is 
     16 * platform independent. It may have several root nodes, as some GUIs are made up of several Frames 
     17 * being independent from each other. The GUI model is filled using the 
     18 * {@link #integratePath(List, IGUIElementFactory)} method.   
    1219 * </p> 
    1320 *  
    … …  
    1825     
    1926    /** 
    20      *  
     27     * <p> 
     28     * the root node of the tree not provided externally. 
     29     * </p> 
    2130     */ 
    2231    private TreeNode root = new TreeNode(); 
    2332     
    2433    /** 
     34     * <p> 
     35     * a list with all nodes currently known 
     36     * </p> 
     37     */ 
     38    private List<TreeNode> allNodes = new ArrayList<TreeNode>(); 
     39 
     40    /** 
     41     * <p> 
     42     * Integrates a path of GUI elements into the GUI model. The GUI model itself is a tree and 
     43     * therefore a set of different paths through the tree that start with a root node and end with 
     44     * a leaf node. Such a path can be added to the tree. The method checks, if any of the GUI 
     45     * elements denoted by the path already exists. If so, it reuses it. It may therefore also 
     46     * return an existing GUI element being the leaf node of the provided path. If a GUI element 
     47     * of the path does not exist yet, it creates a new one using the provided GUI element factory. 
     48     * </p> 
     49     * <p> 
     50     * If a GUI element specification describes an existing GUI element or not is determined 
     51     * through comparing the GUI element specifications of the existing GUI elements with the 
     52     * ones provided in the path. The comparison is done using the 
     53     * {@link IGUIElementSpec#getSimilarity(IGUIElementSpec)} method. The comparison is only done 
     54     * on the correct levels. I.e. the currently known root elements of the tree are only compared 
     55     * to the first element in the path. If the correct one is found or created, its children are 
     56     * compared only to the second specification in the path, and so on. 
     57     * </p> 
     58     * <p> 
     59     * The returned GUI elements are singletons. I.e. it is tried to return always the identical 
     60     * object for the same denoted element. However, while creating the GUI model, the similarity 
     61     * of GUI elements may change. Therefore, the method might determine, that two formerly 
     62     * different nodes are now similar. (This may happen, e.g. if GUI elements do not have initial 
     63     * names which are set afterwards. Therefore, first they are handled differently and later 
     64     * they can be identified as being the same.) In such a case, there are already several GUI 
     65     * element objects instantiated for the same GUI element. The singleton paradigm gets broken. 
     66     * Therefore, such GUI element objects are registered with each other, so that their equal 
     67     * method can determine equality again correctly, although the objects are no singletons 
     68     * anymore. 
     69     * </p> 
     70     * 
     71     * @param guiElementPath    the path to integrate into the model 
     72     * @param guiElementFactory the GUI element factory to be used for instantiating GUI element 
     73     *                          objects 
     74     *                           
     75     * @return The GUI element object representing the GUI element denoted by the provided path 
    2576     *  
    26      */ 
    27     private List<TreeNode> allNodes = new ArrayList<TreeNode>(); 
    28  
    29     /** 
    30      * TODO: comment 
    31      * 
    32      * @param currentGUIElementPath 
    33      * @return 
    34      * @throws GUIModelException  
     77     * @throws GUIModelException thrown in cases such as the GUI element object could not be 
     78     *                           instantiated 
     79     * @throws IllegalArgumentException if the provided path is invalid. 
    3580     */ 
    3681    public IGUIElement integratePath(List<? extends IGUIElementSpec> guiElementPath, 
    3782                                     IGUIElementFactory              guiElementFactory) 
    38         throws GUIModelException 
     83        throws GUIModelException, IllegalArgumentException 
    3984    { 
    4085        if ((guiElementPath == null) || (guiElementPath.size() <= 0)) { 
    … …  
    5499 
    55100    /** 
    56      * TODO: comment 
    57      * 
    58      * @param root 
    59      * @return 
     101     * <p> 
     102     * Returns all children of the provided GUI element or null, if it does not have any or the 
     103     * node is unknown. 
     104     * </p> 
     105     * 
     106     * @param guiElement the GUI element of which the children shall be returned 
     107     *  
     108     * @return As described 
    60109     */ 
    61110    public List<IGUIElement> getChildren(IGUIElement guiElement) { 
    … …  
    79128    /** 
    80129     * <p> 
    81      * TODO: comment 
    82      * </p> 
    83      * 
    84      * @param guiElement 
    85      * @return 
     130     * Returns the parent GUI element of the provided GUI element or null, if it does not have a 
     131     * parent (i.e. if it is a root node) or if the node is unknown. 
     132     * </p> 
     133     * 
     134     * @param guiElement the GUI element of which the parent shall be returned 
     135     *  
     136     * @return As described 
    86137     */ 
    87138    public IGUIElement getParent(IGUIElement guiElement) { 
    … …  
    98149 
    99150    /** 
    100      * TODO: comment 
    101      * 
    102      * @return 
     151     * <p> 
     152     * Returns all root GUI elements of the model or an empty list, if the model is empty 
     153     * </p> 
     154     * 
     155     * @return As described 
    103156     */ 
    104157    public List<IGUIElement> getRootElements() { 
    … …  
    115168 
    116169    /** 
    117      * TODO: comment 
    118      * 
    119      * @return 
    120      */ 
    121     public void dump(OutputStream out) { 
     170     * <p> 
     171     * dumps the GUI model to the provided stream. Each node is represented through its toString() 
     172     * method. If a node has children, those are dumped indented and surrounded by braces. 
     173     * </p> 
     174     *  
     175     * @param out      The stream to dump the textual representation of the model to 
     176     * @param encoding The encoding to be used while dumping 
     177     */ 
     178    public void dump(OutputStream out, String encoding) { 
    122179        PrintStream stream; 
    123180         
    … …  
    126183        } 
    127184        else { 
    128             stream = new PrintStream(out); 
     185            String enc = encoding == null ? "UTF-8" : encoding; 
     186            try { 
     187                stream = new PrintStream(out, true, enc); 
     188            } 
     189            catch (UnsupportedEncodingException e) { 
     190                stream = new PrintStream(out); 
     191            } 
    129192        } 
    130193         
    … …  
    136199    /** 
    137200     * <p> 
    138      * TODO: comment 
    139      * </p> 
    140      * 
    141      * @param root2 
    142      * @param guiElementPath 
    143      * @param guiElementFactory 
    144      * @return 
    145      * @throws GUIModelException  
     201     * internally integrates a path as the children of the provided parent node. This method 
     202     * is recursive and calls itself, for the child of the parent node, that matches the first 
     203     * element in the remaining path. 
     204     * </p> 
     205     * 
     206     * @param parentNode        the parent node to add children for  
     207     * @param guiElementPath    the path of children to be created starting with the parent node 
     208     * @param guiElementFactory the GUI element factory to be used for instantiating GUI element 
     209     *                          objects 
     210     *                           
     211     * @return The GUI element object representing the GUI element denoted by the provided path 
     212     *  
     213     * @throws GUIModelException thrown in cases such as the GUI element object could not be 
     214     *                           instantiated 
    146215     */ 
    147216    private IGUIElement integratePath(TreeNode                        parentNode, 
    … …  
    174243                // based on the children of the existing and new GUI elements. The one for which 
    175244                // the existing children match best is selected to be the right one. 
    176                 similarNodes = 
    177                     considerSubChildren(similarNodes, specToIntegrateElementFor, remainingPath); 
     245                similarNodes = considerSubChildren(similarNodes, remainingPath); 
    178246 
    179247                if (similarNodes.size() > 1) { 
    180                     System.out.println("TODO: implement handling to many similar children: " + 
    181                                       specToIntegrateElementFor); 
     248                    Console.traceln(Level.WARNING, "TODO: implement handling to many similar" + 
     249                                    "children: " + specToIntegrateElementFor); 
    182250                    for (TreeNode similarNode : similarNodes) { 
    183                         System.out.println("    " + similarNode.guiElement); 
     251                        Console.traceln(Level.WARNING, "    " + similarNode.guiElement); 
    184252                    } 
    185                     System.out.println(); 
     253                    Console.traceln(Level.WARNING, ""); 
    186254                } 
    187255            } 
    … …  
    208276    /** 
    209277     * <p> 
    210      * TODO: comment 
    211      * </p> 
    212      * 
    213      * @param parentNode 
    214      * @param specToIntegrateElementFor 
    215      * @return 
     278     * Determines all children of the provided node, which are similar to the provided 
     279     * specification. 
     280     * </p> 
    216281     */ 
    217282    private List<TreeNode> determineSimilarChildNodes(TreeNode        parentNode, 
    … …  
    233298    /** 
    234299     * <p> 
    235      * TODO: comment 
    236      * </p> 
    237      * 
    238      * @param similarChildren 
    239      * @param remove 
    240      * @return 
     300     * This method is called in the case, that several child nodes of a parent node are similar 
     301     * to a node to be integrated into the model. This method tries to determine the similar child 
     302     * nodes of which the sub children match best to the further path to be integrated. This method 
     303     * does nothing, if the similar children do not have children yet of if the remaining path 
     304     * does not denote further children.  
     305     * </p> 
     306     * 
     307     * @return a hopefully reduced list of similar nodes based on their children. 
    241308     */ 
    242309    private List<TreeNode> considerSubChildren(List<TreeNode>                  similarNodes, 
    243                                                IGUIElementSpec                 specToMatch, 
    244310                                               List<? extends IGUIElementSpec> remainingPath) 
    245311    { 
    … …  
    276342    /** 
    277343     * <p> 
    278      * TODO: comment 
    279      * </p> 
    280      * 
    281      * @param parentNode 
     344     * merges similar children of a parent node. The method compares all children of the parent 
     345     * node with each other. If two of them are similar, it merges them, registers them with each 
     346     * other for equality checks, and removes one of them from the list of children.  
     347     * </p> 
    282348     */ 
    283349    private void mergeSimilarChildren(TreeNode parentNode) { 
    … …  
    309375    /** 
    310376     * <p> 
    311      * TODO: comment 
    312      * </p> 
    313      * 
    314      * @param treeNode 
    315      * @param treeNode2 
    316      * @return 
     377     * merges two nodes with each other. Merging means registering the GUI element objects with 
     378     * each other for equality checks. Further it add all children of both nodes to a new 
     379     * replacing node. Afterwards, all similar nodes of the replacement node are merged as well. 
     380     * </p> 
     381     * 
     382     * @return a tree node being the merge of the two provided nodes. 
    317383     */ 
    318384    private TreeNode mergeTreeNodes(TreeNode treeNode1, TreeNode treeNode2) { 
    … …  
    349415 
    350416    /** 
    351      * TODO: comment 
    352      *  
    353      * @param root 
    354      * @param root2 
     417     * <p> 
     418     * dumps a GUI element to the stream. A dump contains the toString() representation of the 
     419     * GUI element as well as a indented list of its children surrounded by braces. 
     420     * </p> 
    355421     */ 
    356422    private void dumpGUIElement(PrintStream out, IGUIElement guiElement, String indent) { 
    … …  
    376442    /** 
    377443     * <p> 
    378      * TODO comment 
    379      * </p> 
    380      *  
    381      * @version $Revision: $ $Date: 17.08.2012$ 
    382      * @author 2012, last modified by $Author: pharms$ 
     444     * used internally for building up the tree of GUI elements. 
     445     * </p> 
    383446     */ 
    384447    private class TreeNode 
    … …  
    395458        /** 
    396459         * <p> 
    397          * TODO: comment 
     460         * adds a child to the current node while keeping all lists of nodes up to date 
    398461         * </p> 
    399          * 
    400          * @param guiElement 
    401          * @return 
    402462         */ 
    403463        private TreeNode addChild(IGUIElement guiElement) 
Note: See TracChangeset for help on using the changeset viewer.