DemoProtocol communication

This document summarizes the interaction between the ConnectionManager(client) and ProcessManager(server) that sit upon the Communicator to begin the demos.

Files affected: (Main files with *)
/class/java/ConnectionManager/
* ConnectionManager.java
DemoEventProcessable.java
DemoEventProcessor.java
DemoNetworkEvent.java
DemoNetworkHandler.java
DemoNetworkListener.java
/class/java/DemoProtocol/
DemoPlayer.java
DemoProtocol.java
/util/demo/isip_comm_server_process_manager
* ProcessManager.java
* DemoClientHandler.java
/util/demo/isip_comm_client_SERVER_NAME (where SERVER_NAME are the four demos)
SERVERNAME_UIFrame.java

Problem:
The Communicator is the communication architecture used to communicate between servers during execution of each demo. This architecture does not have capability to control starting the demo. The current demo has four unique demos thus there must be a method to select the demo and then start the required ISIP-Communicator servers.

Definitions:
Client - Any part of the program on the client side. Upon execution of the client program, the "demo selector" is presented. This "demo selector" performs no server interaction and is a Window to create and execute each of the client Galaxy-Servers. Once any of the demos on the "demo selector" have been selected, the "demo selector" is hidden and the separate threads composing the Galaxy-Servers take over. These separate threads including the GalaxyServer, UIFrame, SpeechDisplay GUI, and others.
Server - Any part of the program on the server side. The ProcessManager is the receiving part of the program and it's only function is to accept the client's socket and pass the socket to a DemoClientHandler. There is one DemoClientHandler per client, so actions performed within each DemoClientHandler do not interact.
To understand the interaction between the server and client, a typical demo initialization interaction between the server and client is described below.
First, assume there is a ProcessManager on server side waiting for clients. Second, assume the client program is on the "demo selector" menu waiting for one of the four demos to be selected. This is a safe assumption since the "demo selector" has no server communication.
Upon selection of any of the 4 demos, a GalaxyMainServer is created and takes control of the client. The GalaxyMainServer creates two main components, the UI and the respective GalaxyServer, in the following order.
1) The UI
a) Creates the GUI window
b) Creates a ConnectionManager which immediately connects to the server and follows the flow of data below.
2) GalaxyServer
a) Connects to the hub that is listening on a hub port.
b) Continues to the the method of data communication to the other servers [Note: Nothing about this Part 2 section is covered here as it is not part of the DemoProtocol at all. It is here for completeness of the GalaxyMainServer.]
The following is the flow of data throughout the interaction in (1b).
1) [CM] ConnectionManager(CM) connects to ProcessManager(PM). No data is sent, just the connection is opened.
2) [PM] Accepts connection using a DemoClientHandler and creates a "DemoPlayer" to represent this connection. Two messages are independently sent to the client.
a) The message with "MSG_INIT_PLAYER|#" is sent to the CM where MSG_INIT_PLAYER is the static number and # is the DemoPlayer's unique ID number.
b) The message with "MSG_SET_HUB_PORT|#" is sent to the CM where MSG_SET_HUB_PORT is the static number and # is the hub port number assigned to this demo by the ProcessManager.
3) [CM] Accepts the MSG_INIT_PLAYER message and creates a parallel DemoPlayer that has the same ID number. The following network messages are independently sent.
a) A message containing the type of demo is "DEMO|bool" where DEMO is the static number associated with {DEMO_SPEECH_ANALYSIS, DEMO_SPEECH_RECOGNITION, DEMO_DIALOG_NAVIGATION, DEMO_SPEAKER_VERIFICATION} and "bool" is either the text "true" or "false" to associate between whether the client will be a client or a server, respectively.
[More Detail: If the client is going to be a client (eg, true), then the client will manually connect to the hub on a specified port. Otherwise, (eg, false) the client will listen on a port for the hub to connect to it. When the laptop is running on wireless, the demo must be run such that the client will connect to the server because it is using a 192.168.x.x DHCP address and the hub cannot connect to this IP].
b) A message containing the Client's IP address is sent using "MSG_CLIENT_IP_ADDRESS|#" where MSG_CLIENT_IP_ADDRESS is the static number and # is the IP of the client in aaa.bbb.ccc.ddd form. This IP is also given to the client copy of the DemoPlayer to store it. [More Detail: This is only used when the client is going to be a server, so typically it will not be used]
c) A message containing the Client's port address is sent using "MSG_CLIENT_PORT|#" where MSG_CLIENT_PORT is the static number and # is the port of the client it would be listening on. This port is also given to the client copy of the DemoPlayer to store it. [More Detail: This is only used when the client is going to be a server, so typically it will not be used]
d) A message containing "MSG_START_DEMO|bool" is sent where MSG_START_DEMO is the static number for this message and bool is the same value as in part (a).
4) [CM] Accepts the MSG_SET_HUB_PORT message and sets a data member to the value. This value is the port which the server's ISIP-Communicator hub is waiting for a connection.
[Note: The hub has no problems accepting more than one client on a hub. This causes the input of the second client to work correctly, but the output is sent to the first client. Therefore for this reason, the client is not permitted to specify the port, but it is server assigned.]
Since there were four messages sent from the client to the server and they will be handled independently, each message will be handled in its own number.
5) [PM] Upon receiving the message sent in (3a), the demo_type will be stored along with a String containing the demo_name.
6) [PM] Upon receiving the message sent in (3b), the DemoPlayer on the server side will be set with the client IP information.
7) [PM] Upon receiving the message sent in (3c), the DemoPlayer on the server side will be set with the client port information.

Background:
The names and locations of the respective server shell-csh-scripts and hub-pgm-scripts are hard-coded into the DemoClientHandler.java. Each of these files are templates because there is information that needs to be replaced such as the unique port numbers for each server. (See PID Info for more information)
8) [PM] Upon receiving the message sent in (3d), the following actions will be performed by the DemoClientHandler.
a) The respective demo's template csh and pgm are opened and the keywords are replaced as the file is written to a temporary file in $ISIP_TMPDIR.
c) The GroupRunner object is utilized and the servers are started. [More Detail: There are more details in the PID Info file]
There is no more interaction between the ProcessManager and ConnectionManager until the end of the demo.
If the client wants to end the demo, a DemoNetworkEvent.NETWORK_DISCONNECTED message is sent to the server. The client then exits and disconnects the open socket. The server cleans up by killing all servers using the GroupRunner object.
If the server has a problem and needs to end the demo, the server sends a "MSG_SERVER_FAILURE|error" message to the client where MSG_SERVER_FAILURE is the static number for it and error is the reason for the server failing. The server verifies the client receives the message and then closes the socket.