Changes between Version 4 and Version 5 of Java Client Tutorial

Timestamp:

Oct 23, 2011 1:41:01 PM (13 years ago)

Author:

jherwitz

Comment:

--

Java Client Tutorial

@@ -155 +155 @@
 This section describes back-end Quagents development
 
-==== Modifying internal structures =====
+==== Modifying internal structures ====
+
+Much of the client-server interaction and multithreading control is handled internally by the Java client. Any modification to these controllers (mostly located in Command, ProtocolZero, and ReaderThread) must ensure that the server will accept/recognize the changes will equivalent functionality.
+
+'''Commands'''
+
+The developer may desire to create a new Command. There are two types of commands, ProtocolZero commands, which carry a one-to-one correspondence with the preexisting [[ProtocolZero]] commands within the server. Any modification to these must, in most cases, also include server modification, as all currently recognized server actions are spanned by the current set of client P0 commands. Most uses will be for ProtocolOne commands, which abstract away from the server and can provide arbitrary complexity.
+To implement a new Command, the developer must extend either ProtocolZero or ProtocolOne.
+
+For P0 commands, the user must define four things:
+ * A set of constructors which will be used to instantiate the command, specifically the parameters sent to the server.
+ * A ''setOP'' function which will create the protocol message to send to the server. NOTE: This '''must''' be consistent with server protocol exceptions, defined in [[ProtocolZero]].
+ * A set of functions used by external sources to access data or exit codes returned by the server.
+ * A ''setData'' function, used by the socket reader to send server return data. This is only valid for functions which have an associated data response. For example, for the Facing command we have:
+
+{{{
+public void setData(String params) {
+                datastring = params;
+                paramscan = new Scanner(params);
+                viewangle[YAW] = paramscan.nextDouble();
+                viewangle[PITCH] = paramscan.nextDouble();
+                viewangle[ROLL] = paramscan.nextDouble();
+        }
+}}}
+
+ProtocolOne comamnds are slightly different in their implementation. By design, these commands have no direct server interaction, handling all interaction through nested ProtocolZero commands. Only three components need to be implemented for this class of command:
+ * A set of constructors which initialize the command and any subcommands. 
+ * An ''addChildren'' function, which adds all nested P0 commands to the children list. This is necessary for internal client verification and execution. An example function looks like:
+
+{{{
+protected void addChildren(){
+                children.add(lookforward);  //rangefinder
+                children.add(lookbackward); //rangefinder
+                children.add(turnright);    //rotate
+                children.add(turnleft);     //rotate
+        }
+}}}
+
+
+
+For more information, see the CartesianSensor2D source, as well as its implementation in the CaveExplorer class.
 
 ==== Implementing a new Entity ====