diff java/src/uk/ac/qmul/eecs/ccmi/gui/DiagramModelUpdater.java @ 3:9e67171477bc

PHANTOM Omni Heptic device release

--- a/java/src/uk/ac/qmul/eecs/ccmi/gui/DiagramModelUpdater.java	Mon Feb 06 12:54:06 2012 +0000
+++ b/java/src/uk/ac/qmul/eecs/ccmi/gui/DiagramModelUpdater.java	Wed Apr 25 17:09:09 2012 +0100
@@ -22,8 +22,11 @@
 import java.util.Set;
 
 import uk.ac.qmul.eecs.ccmi.diagrammodel.DiagramElement;
-import uk.ac.qmul.eecs.ccmi.diagrammodel.DiagramModelTreeNode;
+import uk.ac.qmul.eecs.ccmi.diagrammodel.DiagramTreeNode;
 import uk.ac.qmul.eecs.ccmi.diagrammodel.NodeProperties;
+import uk.ac.qmul.eecs.ccmi.network.AwarenessMessage;
+import uk.ac.qmul.eecs.ccmi.network.DiagramEventActionSource;
+import uk.ac.qmul.eecs.ccmi.network.NetDiagram;
 
 /**
  * 
@@ -38,43 +41,220 @@
  */
 public interface DiagramModelUpdater {
 	
-	public boolean getLock(DiagramModelTreeNode treeNode, Lock lock);
+	/**
+	 * Issues a lock request to the server for the specified tree node.
+	 * 
+	 * @param treeNode the tree node the lock is being requested for
+	 * @param lock the type of lock being requested
+	 * @param actionSource The {@code DiagramEventActionSource} that's going to be piggybacked 
+	 *  on the lock message, for awareness purposes 
+	 * @return {@code true} if the lock is successfully granted by the server
+	 */
+	public boolean getLock(DiagramTreeNode treeNode, Lock lock, DiagramEventActionSource actionSource);
 	
-	public void yieldLock(DiagramModelTreeNode treeNode, Lock lock);
+	/**
+	 * Releases a lock previously acquired by this client. 
+	 *  
+	 * @param treeNode the tree node the lock is being released for
+	 * @param lock the type of lock being released
+	 * @param actionSource The {@code DiagramEventActionSource} that's going to be piggybacked 
+	 *  on the lock message, for awareness purposes.
+	 *  
+	 * @see uk.ac.qmul.eecs.ccmi.network.AwarenessMessage
+	 */
+	public void yieldLock(DiagramTreeNode treeNode, Lock lock ,DiagramEventActionSource actionSource);
 	
-	public void insertInCollection(DiagramElement element);
+	/**
+	 * Sends an awareness message to the server. 
+	 * 
+	 * @param awMsgName the type of awareness message being sent 
+	 * @param source the source of the action. Represents informations to be carried on this message.
+	 * 
+	 * @see uk.ac.qmul.eecs.ccmi.network.AwarenessMessage 
+	 */
+	public void sendAwarenessMessage(AwarenessMessage.Name awMsgName, Object source);
 	
+	/**
+	 * Inserts a {@code DiagramElement} in the {@code CollectionModel} of the {@code Diagram} holding this 
+	 * model updater. 
+	 * 
+	 * @param element the element to insert 
+	 * @param source the source of the insertion action. it can be used by collection listeners.   
+	 */
+	public void insertInCollection(DiagramElement element,DiagramEventSource source);
+	
+	/**
+	 * Inserts a {@code DiagramElement} in the {@code TreeModel} of the {@code Diagram} holding this 
+	 * model updater.
+	 * 
+	 * @param element the element to insert 
+	 */
 	public void insertInTree(DiagramElement element);
 	
-	public void takeOutFromCollection(DiagramElement element);
+	/**
+	 * Removes an element from the {@code CollectionModel} of the {@code Diagram} holding this 
+	 * model updater. 
+	 * 
+	 * @param element the element to remove 
+	 * @param source the source of the insertion action. it can be used by collection listeners.   
+	 */
+	public void takeOutFromCollection(DiagramElement element,DiagramEventSource source);
 	
+	/**
+	 * Removes an element from the {@code TreeModel} of the {@code Diagram} holding this 
+	 * model updater. 
+	 * 
+	 * @param element the element to remove 
+	 */
 	public void takeOutFromTree(DiagramElement element);
-		
-	public void setName(DiagramElement element, String name);
 	
-	public void setProperty(Node node, String type, int index, String value);
+	/**
+	 * Sets a new name for the element of the {@code Diagram} holding this 
+	 * model updater. 
+	 * 
+	 * @param element the element being renamed
+	 * @param name the new name 
+	 * @param source the source of the removal action. it can be used by collection listeners.
+	 */
+	public void setName(DiagramElement element, String name,DiagramEventSource source);
 	
-	public void setProperties(Node node, NodeProperties properties);
+	/**
+	 * Sets to a new value a property of a node of the {@code Diagram} holding this 
+	 * model updater. 
+	 * 
+	 * @param node the node being set a new property 
+	 * @param type the type of the new property 
+	 * @param index the index of the property being set a new value  
+	 * @param value the new value for the property 
+	 * @param source source the source of the {@code setName} action. it can be used by collection listeners.
+	 */
+	public void setProperty(Node node, String type, int index, String value,DiagramEventSource source);
 	
-	public void clearProperties(Node node);
+	/**
+	 * Replace the whole {@code NodeProperties} object of a node of the {@code Diagram} holding this 
+	 * model updater with a new one. 
+	 * 
+	 * @param node the node being set a new {@code NodeProperties} instance
+	 * @param properties the new {@code NodeProperties} instance 
+	 * @param source source the source of the {@code setProperty} action. it can be used by collection listeners.
+	 */
+	public void setProperties(Node node, NodeProperties properties,DiagramEventSource source);
 	
-	public void setNotes(DiagramModelTreeNode treeNode, String notes);
+	/**
+	 * Clears the properties of a node of the {@code Diagram} holding this 
+	 * model updater. 
+	 * 
+	 * @param node the node whose properties are being cleared 
+	 * @param source the source of the {@code setProperties} action. it can be used by collection listeners.
+	 * 
+	 * @see uk.ac.qmul.eecs.ccmi.diagrammodel.NodeProperties#clear()
+	 */
+	public void clearProperties(Node node,DiagramEventSource source);
+
+	/**
+	 * Set the notes for a tree node of the {@code Diagram} holding this 
+	 * model updater. 
+	 * 
+	 * @param treeNode the tree node whose notes are being set 
+	 * @param notes the new notes 
+	 * @param source the source of the {@code setNotes} action. it can be used by collection listeners.
+	 */
+	public void setNotes(DiagramTreeNode treeNode, String notes,DiagramEventSource source);
 	
-	public void addProperty(Node node, String type, String value);
+	/**
+	 * Add a new property to a node's properties of the {@code Diagram} holding this 
+	 * model updater. 
+	 * 
+	 * @param node the node whose properties are being added to 
+	 * @param type the type of the new property being added 
+	 * @param value the value of the new property being added 
+	 * @param source the source of the {@code setProperty} action. it can be used by collection listeners.
+	 */
+	public void addProperty(Node node, String type, String value,DiagramEventSource source);
 	
-	public void removeProperty(Node node, String type, int index);
+	/**
+	 * Removes a property from a node's properties of the {@code Diagram} holding this 
+	 * model updater.  
+	 * 
+	 * @param node the node whose properties are being removed from
+	 * @param type the type of the new property being removed
+	 * @param index the index of the property being removed 
+	 * @param source the source of the {@code removeProperty} action. it can be used by collection listeners.
+	 */
+	public void removeProperty(Node node, String type, int index,DiagramEventSource source);
 	
-	public void setModifiers(Node node, String type, int index, Set<Integer> modifiers);
+	/**
+	 * Set the modifiers for a property of a node in of the {@code Diagram} holding this 
+	 * model updater. 
+	 * 
+	 * @param node the node whose properties whose modifiers are being 
+	 * @param type the type of the property whose modifiers are being set
+	 * @param index the index of the property whose modifiers are being set
+	 * @param modifiers the new modifiers indexes. the indexes refer to the modifiers type array. 
+	 * @param source the source of the {@code setModifiers} action. it can be used by collection listeners.
+	 */ 
+	public void setModifiers(Node node, String type, int index, Set<Integer> modifiers,DiagramEventSource source);
 	
-	public void setEndLabel(Edge edge, Node node, String label);
+	/**
+	 * Set the end label for an edge of the {@code Diagram} holding this 
+	 * model updater. 
+	 * 
+	 * @param edge the edge whose label is being set 
+	 * @param node the node at the edge end where the label is being set 
+	 * @param label the new label 
+	 * @param source the source of the {@code setLabel} action. it can be used by collection listeners.
+	 */
+	public void setEndLabel(Edge edge, Node node, String label,DiagramEventSource source);
 	
-	public void setEndDescription(Edge edge, Node node, int i);// String description);
+	/**
+	 * Set the end description for an edge of the {@code Diagram} holding this 
+	 * model updater. 
+	 * 
+	 * @param edge the edge whose end description is being set 
+	 * @param node the node at the edge end where the end description is being set 
+	 * @param index the index of the new end description in the end description array of {@code edge}
+	 * @param source the source of the {@code setEndDescription} action. it can be used by collection listeners.
+	 */
+	public void setEndDescription(Edge edge, Node node, int index, DiagramEventSource source);
 	
-	public void translate(GraphElement ge, Point2D p, double x, double y);
+	/**
+	 * Translates a graph element of the {@code Diagram} holding this 
+	 * model updater. 
+	 * 
+	 * @param ge the graph element being translated 
+	 * @param p the starting point of the translation 
+	 * @param x the distance to translate along the x-axis
+	 * @param y the distance to translate along the y-axis
+	 * @param source the source of the {@code translate} action. it can be used by collection listeners.
+	 */
+	public void translate(GraphElement ge, Point2D p, double x, double y,DiagramEventSource source);
 	
-	public void startMove(GraphElement ge, Point2D p);
+	/**
+	 * Starts the move for a graph element of the {@code Diagram} holding this 
+	 * model updater. The move can be either a translation or a bend (if {@code ge} is an Edge). 
+	 * This method must be called before such motion methods are called in turn.  
+	 * 
+	 * @param ge the graph element being translated 
+	 * @param p the starting point of the motion 
+	 * @param source the source of the {@code startMove} action. it can be used by collection listeners.
+	 */
+	public void startMove(GraphElement ge, Point2D p, DiagramEventSource source);
 	
-	public void bend(Edge edge, Point2D p);
+	/**
+	 * Bends an edge of the {@code Diagram} holding this  model updater.
+	 * 
+	 * @param edge the edge being bended 
+	 * @param p the starting point of the motion 
+	 * @param source the source of the {@code bend} action. it can be used by collection listeners.
+	 */
+	public void bend(Edge edge, Point2D p,DiagramEventSource source);
 	
-	public void stopMove(GraphElement ge);
+	/**
+	 * Finishes off the motion of a graph element of the {@code Diagram} holding this 
+	 * model updater. 
+	 *  
+	 * @param ge the graph element being moved
+	 * @param sourcethe source of the {@code stopMove} action. it can be used by collection listeners.
+	 */
+	public void stopMove(GraphElement ge,DiagramEventSource source);
 }