The Client is a Java Applet whose primary purpose is to present a user with a graphical display of a software system in which is his one developer of many. It also provides a means of manipulating parts of the system.
The system ("Map") consists of Functional Requirements and Design Parameters (represented by Nodes and organized into Modules) and the Dependencies between them.
Not every module in the simulation needs to be assigned a Client; the simulation can run with a subset of clients connected. If a module does not have a client assigned to it, then it is assumed that no changes are proposed for that module during this execution.
The system can also run in Automatic Mode, in which case all Clients' changes are simulated rather than user-dictated. In that case, clients act as observers only.
See the requirements documentation for more details.
Our system is broken into modules and structured as in the diagram below. The vertical and horizontal bars represent interfaces.
USER <-- modular developer or FR manager
|
APPLET VIEWER <-- netscape, appletviewer, etc.
|
. . . . . . . . . . | . . . . . . . . . . . . . . . . . . . . . . . . . .
|
ClientApplet
|
ClientGUI
CLIENT |
(multiple) ClientEngine
|
ClientRMI
|
ClientRMIIface
|
. . . . . . . . . . | . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|
ServerRMIIface
[...]
This section describes the different modules in the Client. It focuses on their responsibilities and external interfaces.
During development, we changed the background colors for those methods which had been changed or added since the previous version. This "change bar" scheme helped us coordinate during times of intense changes. Despite the fact that our project is now stabilized again, I've left some of the background colors in to indicate how our specs looked during development.
We also have deprecated functions, indicated by a bright red background.
These are functions that are scheduled to be deleted (if no one is using
them) during the next iteration of our development cycle.
The ClientApplet is a Java Applet. It provides the interface between the appletviewer (e.g., the Netscape plugin) and the rest of the application. As far as the application goes, the ClientApplet is only interested in GUI-related activities, so it only interfaces directly with the ClientGUI module.
The specific duties of the ClientApplet are:
| Method | Throws | Invoker | Purpose |
| boolean action (Event event, Object object) | applet viewer | This is invoked by the applet viewer whenever the user activates a component. This method does not handle the action but instead passes it to ClientGUI. | |
| void destroy () | applet viewer | This tells the gui that the user is shutting down the client. | |
| void DumpStack (Exception e) | ClientGUI | This prints the specified exception's stack trace to the console. It is used primarily for debugging programming errors. | |
| void init () | applet viewer | This is called whenever the applet viewer starts up the applet. Its main job is to start up the ClientGUI, which in turn starts up the next Module in the chain (i.e., ClientEngine). | |
| boolean mouseDown (int x, int y) | applet viewer | This is invoked by the applet viewer whenever the user presses a mouse button inside the applet. The applet does not itself handle the press but instead passes the mouse coordinates to ClientGUI. | |
| boolean mouseUp (int x, int y) | applet viewer | This is invoked by the applet viewer whenever the user releases a mouse button inside the applet. The applet does not itself handle the release but instead passes the mouse coordinates to ClientGUI. | |
| void paint (Graphics graphics) | ClientGUI | Called by the applet's repaint() method, this enables the ClientGUI to display primitives in the applet viewer by providing the ClientGUI access to the Graphics object. |
The ClientGUI is responsible for accepting information from the ClientEngine and displaying it on the screen, which it does via the ClientApplet. It also accepts user input notifications from the ClientApplet, determines their meaning, and then notifies the ClientEngine of them.
| Method | Throws | Invoker | Purpose |
| ClientGUI (ClientApplet applet, String address, String port) | ClientApplet | By passing a reference to itself when calling the ClientGUI constructor (along with the address and port number, specified on the invoking web page), ClientApplet gives ClientGUI a way to invoke the ClientApplet methods, enabling two-way communication between the applet and the GUI. This constructor then creates a ClientEngine, establishing a similar two-way interface. It also creates and adds any needed screen components and performs any other needed initialization. | |
| void DisplayDetails (int module_id) |
BoundsException
GraphicsException MapException |
ClientEngine | Displays details about the specified Module and its related dependencies. |
| void DisplayDetails (int module_id, int node_id) |
BoundsException
GraphicsException MapException |
ClientEngine | Displays details about the specified Node and its related dependencies. |
| void DisplayMap (Map map) |
GUIException
MapException |
ClientEngine | This displays the specified Map on the screen. |
| void DisplayMap (Map map, int edit_id)
DEPRECATED |
BoundsException
GUIException MapException |
ClientEngine | This displays the specified Map on the screen.
You should probably use the method without the edit_id parameter, since it is no longer used. |
| void DisplayStats (Stats stats) |
GraphicsException
NullException StatsException |
ClientEngine | Displays the specified Stats data structure. |
| void Draw (Graphics graphics) | ClientApplet | The main purpose of this method is to enable the Drawable objects to be displayed in the browser window. These objects need access to the applet's Graphics object. ClientGUI passes a reference to this object to the DrawableMap class, which in turn passes it to the other Drawable classes. | |
| void Error (Exception e) | ClientEngine | Displays the specified error in the message box, and then tells the applet to dump a stack trace to the console. Use this for debugging programming errors./td> | |
| void Freeze () | ClientEngine | This "freezes" the ClientGUI; it disables user input. | |
| void HandleAction (Event event, Object object) | ClientApplet | When the user activates a component, the browser notifies ClientApplet, which then invokes this method (HandleAction). HandleAction's job is to find out which screen object was activated, and then inform the ClientEngine. | |
| void HandleClick (int x, int y) | ClientApplet | When the user presses a mouse button, the applet viewer notifies ClientApplet, which in turn invokes this method (HandleClick) to handle it. | |
| void HandleRelease (int x, int y) | ClientApplet | When the user releases the mouse, the applet viewer notifies ClientApplet, which in turn invokes this method (HandleRelease) to handle it. | |
| void Notify (String string) | ClientEngine | This displays the specified string on the screen. | |
| void Quit () | ClientApplet | This tells the engine that the user is shutting down the client. | |
| void Unfreeze () | ClientEngine | This "unfreezes" the ClientGUI; it enables user input. | |
| void Warn () | ClientApplet, ClientEngine | Displays a warning in the message box. Warning messages must be of interest to the user; use the Error() method for reporting programming errors and facilitating debugging. |
This module handles the high-level logic involved in the operation of the Client. It decides what happens when the user clicks on a Node or a button, what happens when the Client receives a message from the Server, etc.
| Method | Throws | Invoker | Purpose |
| ClientEngine (ClientGUI gui, String address, String port) | Exception | ClientGUI | By passing a reference to itself when calling the ClientEngine construtor, ClientGUI gives ClientEngine a way to invoke the ClientGUI methods, enabling two-way communication between the GUI and the engine. This constructor then creates a ClientRMI, establishing a similar two-way interface. It then performs any other needed initialization. |
| void NodeClicked (int my_module_id, int node_id) | Exception | ClientGUI | Whenever the user clicks on a Node, ClientGUI calls this method. This method is responsible for handling any necessary changes to the state of the map and for subsequently directing the ClientGUI to display those changes. |
| void DoneClicked () | Exception | ClientGUI | Whenever the user clicks on the Done button, ClientGUI calls this method, which then responds by freezing the ClientGUI and sending any changes in the client's module back to the server (via the ClientRMI). |
| void ReceiveMap (Map my_map, int my_module_id) | Exception | ClientRMI | When the ClientRMI receives a map from the ServerRMI, it passes the map to the ClientEngine via this method. The ClientEngine then passes the map to the ClientGUI, whose job it is to display it. The second argument tells the ClientEngine which Module "belongs" to this particular client. |
| void ReceiveStats (Stats my_stats, int my_module_id) | Exception | ClientRMI | When the ClientRMI receives new statistics from the ServerRMI, it passes the stats to the ClientEngine via this method. The ClientEngine then passes the stats to the ClientGUI, whose job it is to display it. The second argument tells the ClientEngine which client this set of stats belongs to. |
| void PrintMessage (String s) | ClientRMI | When the ClientRMI wants to print a string to the GUI, it calls this method. This method subsequently calls the Notify() method belonging to the ClientGUI. | |
| boolean SetClientID (int id) | Exception | ClientGUI | Called when the ClientGUI wants to choose the module id for that particular workstation. This method subsequently calls the SetClientID() method belonging to the ClientRMI. This method returns true if the id is set successfully. False is returned if the requested id does not exist or has already been taken by another client. |
| void Shutdown () | ClientRMI | Called when the ClientRMI is notified by the server that the system is shutting down. This method freezes the user's screen, prints an output message, and returns. | |
| void Error (Exception e) | ClientRMI | Called when the ClientRMI wants to pass an exception to the ClientGUI for display. | |
| void Quit () | Exception | ClientGUI | When the applet is destroyed, the ClientGUI calls this method, which subsequently calls Quit() in the ClientRMI to inform the system that an applet is going away. |
The ClientRMI module handles the Client's side of the communication with the server. It talks to the server through the ServerRMI module, and to the ClientEngine.
| Method | Throws | Invoker | Purpose |
| ClientRMI (ClientEngine engine) | ClientEngine | By passing a reference to itself when calling the ClientRMI constructor, ClientEngine gives ClientRMI a way to invoke the ClientEngine methods, enabling two-way communication between the engine and the RMI. This constructor then performs any other needed initialization. | |
| Map Connect (String ip, String port) | RemoteException, Exception | ClientEngine | The ClientEngine calls this method to get the initial map. The server's hostname/port is polled for the server, and the map received as a return parameter if all is OK. |
| boolean SetClientID (int module_num) | Exception | ClientEngine | The ClientEngine calls this method to request a module. If the server grants the request, the module number is noted and an affirmative answer is passed back to the ClientEngine. |
| void Quit () | Exception | ClientEngine | Client is shutting down. This is a way of notifying the server of this event. |
| void ReceiveMap (Map m) | RemoteException, Exception | ServerRMI (RMI call) | The server sends the entire map using this method. ClientEngine's ReceiveMap() method is called. |
| void ReceiveStats (Stats stats) | RemoteException, Exception | ServerRMI (RMI call) | Same as ReceiveMap, only ClientEngine's ReceiveStats() method is invoked. |
| void SendChanges(Module m) | RemoteException, Exception | ClientEngine | When the user is done destabilizing their module, ClientEngine invokes this method to pass the destabilized module back to the server. ServerRMI's ReceiveModule() method is invoked (RMI call). |
| void Shutdown() | RemoteException, Exception | ServerRMI (RMI call) | This is a message from the server telling all the clients to shut down. The call is passed to ClientEngine's Shutdown() method. |
This is an interface that gets exported to the server so that the server would know where to find the client and what methods of client's it can use.
| Method | Throws | Invoker | Purpose |
| void ReceiveMap (Map m) | RemoteException, Exception | ServerRMI (RMI call) | (see same method in ClientRMI) |
| void ReceiveStats (Stats stats) | RemoteException, Exception | ServerRMI (RMI call) | (see same method in ClientRMI) |
| void Shutdown () | RemoteException, Exception | ServerRMI (RMI call) | (see same method in ClientRMI) |
Version 3.4 - 14-DEC-1998 txe
Cleaned up formatting, typos
Version 3.3 - 14-DEC-1998 rgb
Updated DemonEngine constructor to take address and port
Version 3.2 - 05-DEC-1998 Orim
Added Quit to ClientRMI, other descriptive changes
Version 3.1 - 03-DEC-1998 rgb
Added Quit to ClientEngine
Version 3.0 - 02-DEC-1998 txe
Added ClientApplet.destroy(), ClientGUI.Quit()
Version 2.3 - 18-NOV-1998 Orim
Added RMI info to the document
Version 2.2 - 18-NOV-1998 rgb
Updated exceptions thrown to ClientEngine
Added Error to ClientEngine
Version 2.1 - 17-NOV-1998 txe
Re-alphebetized.
Version 2.0 - 16-NOV-1998 txe
Initial creation (split from spec.html)
Finished ClientApplet and ClientGUI