Ignore:
Timestamp:
09/20/12 09:40:26 (12 years ago)
Author:
sherbold
Message:
  • code documentation and clean-up
File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r655 r831  
     1 
    12package de.ugoe.cs.quest.eventcore.guimodel; 
    23 
    … …  
    67 
    78/** 
    8  * TODO comment 
     9 * <p> 
     10 * Skeletal implementation for GUI elements. 
     11 * </p> 
    912 *  
    10  * @version $Revision: $ $Date: $ 
    11  * @author 2011, last modified by $Author: $ 
     13 * @version 1.0 
     14 * @author Patrick Harms 
    1215 */ 
    1316public abstract class AbstractDefaultGUIElement implements IGUIElement { 
    14      
    15     /**  */ 
     17 
     18    /** 
     19     * <p> 
     20     * Id for object serialization. 
     21     * </p> 
     22     */ 
    1623    public static final long serialVersionUID = 1L; 
    1724 
    18     /** the reference to equal GUI element manager (needed to preserve singleton behavior) */ 
     25    /** 
     26     * <p> 
     27     * The reference to equal GUI element manager (needed to preserve singleton behavior, even 
     28     * though the objects are not singleton). 
     29     * </p> 
     30     */ 
    1931    private static final EqualGUIElementManager equalGUIElementManager = 
    2032        new EqualGUIElementManager(); 
    2133 
    22     /** the specification of the GUI element */ 
    23     private IGUIElementSpec specification; 
    24  
    25     /** the reference to the parent element */ 
    26     private IGUIElement parent; 
    27  
    28     /** 
    29      * <p> 
    30      * TODO: comment 
    31      * </p> 
    32      * 
     34    /** 
     35     * <p> 
     36     * Specification of the GUI element 
     37     * </p> 
     38     */ 
     39    private final IGUIElementSpec specification; 
     40 
     41    /** 
     42     * <p> 
     43     * Reference to the parent element 
     44     * </p> 
     45     */ 
     46    private final IGUIElement parent; 
     47 
     48    /** 
     49     * <p> 
     50     * Constructor. Creates a new AbstractDefaultGUIElement. 
     51     * </p> 
     52     *  
    3353     * @param specification 
     54     *            specification of the created GUI element 
     55     * @param parent 
     56     *            parent of the created GUI element; null means the element is a top-level window 
    3457     */ 
    3558    public AbstractDefaultGUIElement(IGUIElementSpec specification, IGUIElement parent) { 
    … …  
    4871    } 
    4972 
    50     /* (non-Javadoc) 
     73    /* 
     74     * (non-Javadoc) 
     75     *  
    5176     * @see de.ugoe.cs.quest.eventcore.guimodel.IGUIElement#getParent() 
    5277     */ 
    … …  
    5681    } 
    5782 
    58     /* (non-Javadoc) 
     83    /* 
     84     * (non-Javadoc) 
     85     *  
    5986     * @see de.ugoe.cs.quest.eventcore.guimodel.IGUIElement#addEqualGUIElement(IGUIElement) 
    6087     */ 
    6188    @Override 
    62     public void addEqualGUIElement(IGUIElement equalElement) 
    63     { 
     89    public void addEqualGUIElement(IGUIElement equalElement) { 
    6490        equalGUIElementManager.addEqualGUIElements(this, equalElement); 
    6591    } 
    … …  
    76102    } 
    77103 
    78     /* (non-Javadoc) 
     104    /* 
     105     * (non-Javadoc) 
     106     *  
    79107     * @see java.lang.Object#hashCode() 
    80108     */ 
    … …  
    90118    /** 
    91119     * <p> 
    92      * TODO comment 
    93      * </p> 
    94      *  
    95      * @version $Revision: $ $Date: 24.08.2012$ 
    96      * @author 2012, last modified by $Author: pharms$ 
     120     * This internal helper class manages equal GUI elements. This is necessary, as we often first 
     121     * identify many GUI elements as different and later use a heuristic to determine that they are 
     122     * the same. This class provides the means to preserve the singleton behavior of the GUI 
     123     * elements after we merge two GUI elements. 
     124     * </p> 
     125     *  
     126     * @version 1.0 
     127     * @author Patrick Harms 
    97128     */ 
    98129    private static class EqualGUIElementManager { 
    … …  
    100131        /** 
    101132         * <p> 
    102          * the internal map of GUI elements mapping each registered element to its equal variants. 
     133         * The internal map of GUI elements mapping each registered element to its equal variants. 
    103134         * We use the {@link IdentityHashMap} as a normal hash map would not work because of the 
    104135         * changing of the hash code of GUI elements at runtime. 
    … …  
    107138        private IdentityHashMap<IGUIElement, List<IGUIElement>> identityHashMap = 
    108139            new IdentityHashMap<IGUIElement, List<IGUIElement>>(); 
    109          
    110         /** 
    111          * <p> 
    112          * TODO: comment 
    113          * </p> 
    114          * 
    115          * @param abstractDefaultGUIElement 
    116          * @param equalElement 
     140 
     141        /** 
     142         * <p> 
     143         * Adds a new equals relationship between two {@link IGUIElement}s to the equality manager. 
     144         * </p> 
     145         *  
     146         * @param guiElement1 
     147         *            first equal GUI element 
     148         * @param guiElement2 
     149         *            second equal GUI element 
    117150         */ 
    118151        private synchronized void addEqualGUIElements(IGUIElement guiElement1, 
    … …  
    121154            List<IGUIElement> list1 = identityHashMap.get(guiElement1); 
    122155            List<IGUIElement> list2 = identityHashMap.get(guiElement2); 
    123              
     156 
    124157            if (list1 == null) { 
    125158                if (list2 == null) { 
    … …  
    145178                } 
    146179                // else 
    147                 //     in this case, both GUI elements should already be registered with the same 
    148                 //     lists. 
    149             } 
    150         } 
    151  
    152         /** 
    153          * <p> 
    154          * TODO: comment 
    155          * </p> 
    156          * 
    157          * @param abstractDefaultGUIElement 
    158          * @return 
     180                // in this case, both GUI elements should already be registered with the same 
     181                // lists. 
     182            } 
     183        } 
     184 
     185        /** 
     186         * <p> 
     187         * Returns the object hash of a {@link IGUIElement}. 
     188         * </p> 
     189         *  
     190         * @param guiElement 
     191         *            gui element whose object hash is determined 
     192         * @return the object hash 
    159193         */ 
    160194        private synchronized int hashCode(IGUIElement guiElement) { 
    … …  
    164198        /** 
    165199         * <p> 
    166          * TODO: comment 
    167          * </p> 
    168          * 
    169          * @param abstractDefaultGUIElement 
     200         * Determines the equality of two {@link IGUIElement}s based on the information of the 
     201         * identify manager. Two elements are equal, if they have been added as equal using 
     202         * {@link #addEqualGUIElements(IGUIElement, IGUIElement)}. 
     203         * </p> 
     204         *  
     205         * @param guiElement 
     206         *            GUI element to which the object is compared 
    170207         * @param other 
     208         *            object that is compared to the GUI element 
    171209         * @return 
    172210         */ 
    … …  
    179217                } 
    180218            } 
    181              
     219 
    182220            return false; 
    183221        } 
    … …  
    185223        /** 
    186224         * <p> 
    187          * TODO: comment 
    188          * </p> 
    189          * 
    190          * @param guiElement 
    191          * @return 
     225         * Returns the equal {@link IGUIElement} of a given {@link IGUIElement}. 
     226         * </p> 
     227         *  
     228         * @param guiElement 
     229         *            GUI element of which the equal elements are returned 
     230         * @return the equal GUI elements 
    192231         */ 
    193232        private List<IGUIElement> getEqualElementsList(IGUIElement guiElement) { 
    194233            List<IGUIElement> returnValue = identityHashMap.get(guiElement); 
    195              
     234 
    196235            if (returnValue == null) { 
    197236                returnValue = new LinkedList<IGUIElement>(); 
    … …  
    199238                identityHashMap.put(guiElement, returnValue); 
    200239            } 
    201              
     240 
    202241            return returnValue; 
    203242        } 
    … …  
    205244        /** 
    206245         * <p> 
    207          * TODO: comment 
    208          * </p> 
    209          * 
    210          * @param resultingList 
    211          * @param guiElement1 
     246         * Adds {@link IGUIElement} as equal to a list of {@link IGUIElement} if and only if it is 
     247         * not already contained. 
     248         * </p> 
     249         *  
     250         * @param equalElementsList 
     251         *            list of {@link IGUIElement} to which the GUI element is added 
     252         * @param guiElement 
     253         *            GUI element to be added 
    212254         */ 
    213255        private void addIfNotContained(List<IGUIElement> equalElementsList, IGUIElement guiElement) 
    … …  
    218260                } 
    219261            } 
    220              
     262 
    221263            equalElementsList.add(guiElement); 
    222264        } 
Note: See TracChangeset for help on using the changeset viewer.