[ Return to Technical Manual Index ]
The GUI/Model communication could have been implemented in two different manners. In the first implementation, Java's NMI would have been used to invoke methods within the model, which would have been developed as C++ Library. The following is a diagram of the basic structure of such an implementation:
In the second implementation, the one that is used, communication is accompolished via the standard output and standard error streams, after the model is started via an exec call within the Java code. The following diagram illustrates this structure:
Data Flow Overview
To begin execution of the model, the start button at the bottom of the file tab is clicked. Once the start button is clicked, a flow of data is begun which results in the execution of the model.
When the start button is clicked, a CommandObj, a java data object which maintains all of the necessary attributes needed to invoke the model, is built, and its fields are set. Another object, ModelTalker, is then instantiated, and, since it is implemented as a Java thread, it is started with the CommandObj passed as one of its parameters.
The ModelTalker then begins execution within its own thread. Here it uses the CommandObj to start the Model, passing in the proper command line arguements to the C++ program. Once the model is started, the ModelTalker gets the standard output and standard error streams from the C++. It then instantiates and starts two thread objects, StderrTalker, and StdoutTalker, passing them as parameters the CommandObj. More importantly, it passes StderrTalker the standard error stream taken from the C++ model, and it passes to StdoutTalker the standard output stream taken from the model.
The two thread objects then begin their own separate execution. StderrTalker creates an instance of JOuputWindow, stderrWin, makes it visible, and begins passing the text received via the standard input stream to the stderrWin, where it can be displayed in the scrolling text window. The basic function of StderrTalker is to redirect the verbose output of the model to a Java window.
StdoutTalker, is similar to StderrTalker, except its purpose is to setup the visualization windows for the model, parse the visualization information generated by the model, and direct the visualization info to the proper JGraphicWindow where it can be displayed. The model generates visualization information, and writes it to standard out using our own specialized protocol. To learn about this protocol, click here.
The JOutputWindow is a simple window with a single scrollable text field which receives lines of text and appends that text to the end of the text field.
The JGraphicWindow contains a JChart which uses a line graph in order to display the values of a particular variable over time.
Java Implementation Details ( Class by Class ) Link to Java Class Descriptions
This class maintains all of the necessary attributes needed to construct a command line, which is used to start the model. Before ModelTalker is started, the data members of this class are set based on the values of the GUI. Additionally, it holds the user specified visualization options which will be used later by StdoutTalker.
This class extends the Thread class so that it can execute independently from the GUI itself. The main GUI class, HydroGUI, creates an instance of this object, passes the CommandObj, and calls the start() method in order to start the threads execution.
The real work of the class is done in the run() method. Here, ModelTalker extracts the command to start the model, and also extracts the command line arguements. It then uses the exec command of Java's Runtime class to start the C++ code. After it starts the model, it uses the getErrorStream() method to acquire the standard error stream from the C++ code, and uses the getInputStream() method to acquire the standard output stream from the c++ code. StderrTalker is then instantiated with the error stream passed as a parameter in the constructor, and StdoutTalker is instantiated with the output stream passed as a parameter to it. The method finishes by invoking the start() methods of StdoutTalker and StderrTalker.
This class also extends the Thread class so that it can execute independently from the StdoutTalker and ModelTalker. This method instantiates a JOutputWindow, stderrWin, and registers it as an OutputEventListener. Then, within the run() method, the class continually reads from the error stream. Each line read from the error stream is then fired as an OutputEvent to all the registered listeners of the class. This is accompolished via the fireOutputEvent method.
This class is very similar in structure to the StdoutTalker. The class extends Thread so that it can execute independently. It also reads each individual line from a stream, namely the output stream of the C++ model. However, the class has much more functionality. The class extracts from the command object, which was passed to it in its constructor, the various graphic options specified by the user in the HydroGUI. This info includes the variables that the user wants graphed, the start and end dates during which the variables will be outputted, and the time interval at which these variables will be produced by the C++ Model. StdoutTalker then uses the information to instantiate several JGraphicWindows, where the variable visualization will occur. The output sent over the standard output stream by the model is intended to be used to visualize various variables of the model. The output is sent using a attribute value protocol. The output is received by the StdoutTalker class, parsed according to the protocol, and then sent to the appropriate JGraphicWindow via the firing of a GraphicOuputEvent.
This class is simply used to pass the information received by StderrTalker to the JOutputWindows listening for OutputEvents. An OutputEvent simply carries a String that is to be displayed in the JOutputWindow.
This interface contains only one method, addOutput. It is implemented by JOutputWindow so that it can receive OutputEvents.
This class extends JFrame. It is a simple Window, with a single scrollable JTextArea, that displays the output of the model. It receives this output by implementing the OutputEventListener interface, which allows it to receive OutputEvents from StderrTalker.
This class extends JFrame, and contains a JChart. It is responsible for using the info received from GraphicOutputEvents inorder to display the C++ model variables in a line graph. It implements the GraphicOutputEventListener, which includes the method receiveGraphicEvent -- the method primarily responsible for displaying the information passed to the window via the event. Since the JChart uses a StringTableModel as its data model type, a data point is added to the chart by adding the new value of the variable received via the event to a new row of the StringTableModel. This automatically causes the JChart to be updated, and the range of the JChart y-axis is reconfigured.
This class is similar to class OutputEvent. It simply allows StdoutTalker to be direct the visualization information to the appropriate JGraphicWindow. It carries most of the information via a hastable which contains the variable name, value of the variable, and the time at which the output was produced by the model.
The Visualization Protocol ( These are suggestions for implementation)
The variables that are to be graphed must be specified by the user in some manner within the GUI. These specifications must then be stored in the CommandObj, so that these options can be eventually passed to the StdoutTalker object. There has to be some restrictions on the number of variables that can be graphed at any one time.
Within StdoutTalker the information garnered from the CommandObj must be used to instantiate the various JGraphicWindows, associate each JGraphicWindow with the variable(s) that it will graph, and register the JGraphicWindows as GraphicOutputEvent listeners.
The stream protocol produced by the model over the standard output stream should follow a attribute-value format. It should pass streams in the following format :
vname=<variable name>&value=<variable value>&time=<time>
This stream can then be easily parsed by StdoutTalker. Once parsed, StdoutTalker would build a GraphicOutputEvent using the values parsed, and the, using the variable name, it would determine the appropriate JGraphicWindow to fire the GraphicOutputEvent to.
Suggestions for Implementing this as an Applet
Implementing this program using an Applet that can run the C++ model from any browser will require quite a bit of changes, primarily due to the overhead required by the distributed nature of an Applet.
As seen in the diagram above, a Java servlet will have to be created in order to communicate with the GUI. This servlet will be the class which will need to take over responsibilty for starting the model, and for writing the standard out, and standard error streams back to the client side classes.
Changes will need to be made in order to account for the communication across the network.
Also, due to the security restrictions imposed on Applets, the filechooser will not work.
Originating Author: Skip Walker, first draft 4/6/99
- 4/8/99 - added link to class descriptions
- 4/13/99 - added diagrams
- 4/21/99 - revised visualization information to include newly implemented function