Treasure Hunt
Version 1.0

System Design Specification



Libo Xin
Nathan Conklin
Wes Lloyd

CS 5984
Software Design and Quality

November 9, 1999




1. Requirements Summary


The requirements for the Treasure Hunt game have been divided into the following categories: High Level Requirements, User Interface Requirements, Usability Requirements, Performance Requirements, Reliability Requirements, Maintainability Requirements, and Versioning Requirements. Each proceeding section of the document details the specific requirements for the Treasure Hunt game.

1.1. High Level Requirements


The Treasure Hunt is a multi-player distributed client/server based game. Each computer participating in the Treasure Hunt acts as either a client computer or a server computer. There is only one server computer for each game system. There are no strict limits enforced on the number of client computers that can participate on a single game system.

A client computer runs the Treasure Hunt client software. The client software displays the user interface and facilities interaction between the game player and the Treasure Hunt game system.

A server computer runs the Treasure Hunt server software. The server mediates the Treasure Hunt. The server allows multiple players to participate in the game, while providing the necessary communication between client computers for game play.

The Treasure Hunt will have an open source code-base. All system code is freely distributable.

1.1.1. Target Platform


1.1.1.1. Client computer systems


The target hardware platform for a Treasure Hunt client is any web based computer, with an Internet web browser. The web browser must support a Java virtual machine (VM) of version 1.1 or higher. Typical examples are Microsoft Internet Explorer 4.x, or Netscape Navigator 4.x. The minimum Client CPU requirement for the Treasure Hunt game is an Intel Pentium P166 MHz or comparable 5th generation processor. Client systems should have a minimum amount of memory in order to support efficient operation of any web browser with a Java VM version 1.1 or higher.

1.1.1.2. Server Computer system


The target hardware system for a Treasure Hunt server should be any computer that can run a Java Virtual Machine and an Internet web browser. The minimum server CPU and memory requirements are the same as the minimum client CPU requirements as defined above. Due to the noncomplex nature of our system, the server system does not require significantly more processing power than the client. Therefore we do not foresee the requirement for more robust hardware for implementing a Treasure Hunt server.

1.1.1.3. Network system


The Treasure Hunt game system must use the TCP/IP protocol, which is standard throughout the Internet. The TCP/IP protocol supports game communication between the clients and server. The PPP/SLIP protocols can be used to support dialup access to the system.

1.2. System Description


The Treasure Hunt is a multi-player game. Each player sails a ship in the ocean. The contest is to see which player can find the most treasure during the game. The game is over when all treasure has been found and recovered. The player who found the most treasure wins the Treasure Hunt.

The Treasure Hunt system has (3) major components: the ocean, ships, and divers.

1.2.1. Ocean


The Ocean is a large body of water wherein the ships sail and search for treasure. Somewhere on the bottom of the ocean floor there are treasures to be found. The object of the game is for players to control ships in the ocean, to search for the treasure.

1.2.1.1. Ocean Quadrants


Within the game the ocean is divided into quadrants. On the ocean floor, each quadrant has either: a treasure, a reef, a shipwreck, or nothing. On the ocean surface, each quadrant has either: a ship, an island, or only water.

1.2.1.2. Object Positions


Ships are not permitted to share the same quadrant position in the ocean. If a ship attempts to move to an ocean quadrant that is already occupied, then the ship is destroyed.

1.2.2. Ships


The player controls the ship to search for the treasure in the ocean. The player can sail the ship to a new location, use the sonar to scan the ocean floor, visually scan the surrounding from the deck of the ship, and launch divers to search a quadrant of the ocean floor for treasure.

1.2.2.1. Ship Movement


The player commands the ship where to move. The ship can move one ocean quadrant per turn. If a player attempts to move the ship to an ocean quadrant that is occupied by another ship or by an island then the ship is destroyed and the player looses the game.

1.2.2.2. Sonar Scan


Ships are equipped with sonar equipment that can scan the bottom of the ocean floor. The sonar equipment can detect the presence of an item of interest on the ocean floor within the scanning range. Items of interest are: reefs, shipwrecks, and treasure. The sonar cannot determine what type of item is found, it only reports that there is an item of interest on the ocean floor. The sonar cannot determine which ocean quadrant possesses the item of interest. The sonar will only detect the existence of an item within the range of the scan. The sonar will scan all adjacent quadrants to the ship, including the quadrant that the ship presently occupies.

1.2.2.3. Visual Scan


The player can view the surface of the ocean's adjacent quadrants by gazing from the deck of the ship. The player can detect islands, other ships, or empty water on the ocean.

1.2.2.4. Divers


Treasure cannot be seen from the ship, so divers must be sent underwater to check whether a quadrant posses treasure or not. Each ship has a crew of divers. They are sent into the ocean to explore the ocean floor. A ship can send divers to its present quadrant or any adjacent quadrant. Divers can be lost due to conflicts and errors made by the player. If a ship runs out of divers then the player looses the game.

1.2.3. Divers


Divers are deployed by treasure hunting ships to search for treasure on the ocean floor. A diver will report its findings to the ship. A diver can discover: treasure, reefs, other divers, shipwrecks, or nothing.

1.2.3.1. Treasure


If a diver is deployed to an ocean floor quadrant possessing treasure and the diver survives the dive, they will report the discovery of treasure.

1.2.3.2. Other Divers


If a diver is deployed to an ocean floor quadrant that is already occupied by a diver from another ship, then the two divers will fight to the death. One diver will survive and continue to search the ocean floor quadrant for treasure. The other diver perishes and will not return to their ship. The Ocean server randomly determines the winning diver.

1.2.3.3. Reefs, Shipwrecks, or Nothing


If a diver is deployed to an ocean floor quadrant possessing reefs, shipwrecks, or nothing of interest it will report the insignificant finding to the ship.

1.2.3.4. Movement


Divers cannot move outside the ocean floor quadrant they were sent to.

1.3. User Interface Requirements


The Treasure Hunt game is a client/server web based application. The game's client interface is a web based graphical interface implemented as a Java applet that can be operated with any 4.x Internet web browser. The GUI includes a graphical depiction of the ocean.

1.3.1. Mouse Operation


The Treasure Hunt offers a mouse driven, point and click interface that does not require keyboard intervention. The player's ship can be controlled using a set of command buttons and mouse actions, offering available operations to the user.

1.3.2. Keyboard Operation


The Treasure Hunt game should be playable without a mouse, for those cases when a computer's mouse fails. Keyboard sequences should be available for all game operations in the event of mouse failure. However ease of use preference should be given to the game's mouse based operation.

1.4. Usability Requirements


The Treasure Hunt is an easy to play, mouse-operated game.

1.4.1. Users


Users of the Treasure Hunt game are considered to be below average application users with no systems or programming experience. They fit the description of "average web surfers", with some experience web searching and browsing.

1.4.2. Application Fluency


Ease of use is a goal of the Treasure Hunt game system. New users should be able to learn how to play the game quickly, so they are capable players in only a short amount of time. Application fluency should be obtainable in about 15 minutes for the average Treasure Hunt player.

Application fluency in the scope of the Treasure Hunt system is defined as:

     
  • Ability to start a new game      
  • Ability to perform ship navigation      
  • Ability to play a game to completion      
  • Ability to deploy divers to search for treasure

    1.5. Performance Requirements


    The Treasure Hunt game should run fluidly on any computer with a web browser featuring a Java v1.1 virtual machine.

    1.5.1. Ship Movement


    When a player requests to move the ship to a new ocean quadrant, this operation should take no more than 5 seconds. This time is measured from the time the user makes the movement request until the ship has moved and the player has been informed of the success/failure of the move. It can take longer than 5 seconds for Treasure Hunt clients to realize that an opposing player has moved.

    1.5.2. Diver deployment


    When a player requests to deploy a diver to the ocean floor, it should take no more than 10 seconds. This time is measured from the time the user makes the initial diver deployment request until the player is informed that his/her diver is diving in search for treasure.

    1.6. Reliability Requirements


    The Treasure Hunt game should be stable and offer reliable play without failure. The following are MTF (mean time between failure) rates that define operational targets for our system. Mean time between failures is the average measured time between system crashes.

    In considering our systems MTF requirements, we assume that uncontrollable factors such as hardware failure and power failure are not part of the MTF. The MTF measures failures related to the operation of the Treasure Hunt software.

    1.6.1. Client Mean Time to Failure (MTF)


    The Treasure Hunt client should exhibit a minimum MTF of 5 hours. The minimum average measured time between client system crashes should be no less than approximately 5 hours.

    1.6.2. Server Mean Time to Failure (MTF)


    The Treasure Hunt server should exhibit a minimum MTF of 125 hours. The minimum average measured time between server system crashes should be no less than approximately 125 hours.

    1.7. Maintainability Requirements


    The Treasure Hunt game system should exhibit good software maintainability. It should be easy to implement error corrections and feature enhancements to future game system revisions.

    1.7.1. Understandability


    Treasure Hunt system code should be easily understandable by any software developer familiar with the Java programming language.

    1.7.1.1. Design Documentation


    The Treasure Hunt system should have a detailed set of design documents describing the decomposition of code objects and modules of the system. The document should be maintained throughout the lifetime of the product.

    1.7.1.2. Standard Headers


    Each class/module and each function/element of the Treasure Hunt system should have a standard header. This header should provide explanation to enhance the understandability of each class/module or function/element.

    Here is an example of a class/module header:

    /****************************************************************************************
         CLASS.......:
         PURPOSE.....:
         PROPERTIES..:    Name                 Purpose
                         ---------------      -------

         METHODS.....:    Name                 Purpose
                         ---------------      -------
                         *PUBLIC*
                         *PRIVATE*

         CHANGE LOG..:    Date      By   Comments
                         -------- --- --------
                         10/14/99 WJL Creation date.
    ****************************************************************************************/

    Here is an example of a function/element header:

    /****************************************************************************************
         METHOD......:
         PURPOSE.....:
         INPUTS......:
         RETURNS.....:
         CHANGE LOG..:    Date      By      Comments
                         -------- ---     --------
                         10/14/99 WJL     Creation date.
    ****************************************************************************************/

    1.7.2. Readability


    To enhance the readability of the code of the Treasure Hunt system a consistent coding style
    should be used throughout the implementation.

    1.7.2.1. Coding Standard


    A coding standard should be devised and employed in the implementation of the Treasure Hunt
    game system. The coding standard includes:

         
  • Consistent variable naming scheme, that aids in identification of scope, and type of variables      
  • Consistent formatting and layout for readability of nested statements      
  • Consistency in class method names

    1.8. Versioning Requirements


    Treasure Hunt systems will use a standard versioning number sequence. Numbers to the left of the decimal will specify the major release number. Numbers to the right of the decimal should specify the minor release number. Minor release numbers may be up to (3) digits long.

    The Treasure Hunt server must allow for backward compatibility with all previous Treasure Hunt clients known to exist that have the same major release number. Each revision to the server should support game play with previous clients. If a major change is required to the server, which requires backward compatibility to be discontinued, then the major release number of the server is incremented. The new server will only guarantee support of clients with the same major release number.


    Release Number:



    Major Release # -> 1.0 <- Minor Release #


    2. High-Level Design


    For the top-level design of the Treasure Hunt system we have selected to use a client/server architecture. The functions of the game are divided into a client and a server. The client provides the graphical interface that presents the game to the players, while the server tracks game state and mediates communication with all game clients. Objected-oriented decomposition is used for both the client and server design.


    2.1. Client Architecture


    The Treasure Hunt client implements the graphical user interface for the game. The client is implemented as a Java applet running inside a web browser. The client's functionality is decomposed into classes using a traditional object oriented style. Communication between classes is event driven.

    2.1.1. Object Oriented Decomposition


    The Treasure Hunt client is broken down into a set of objects that manage either a thread of control or a set of user interface events. The Ship and Diver classes represent each entity as part of the system. Each is its own thread of control and models the timing of the system through both communication delays with the server and thread suspension. The Treasure Hunt Frame, Navigation Wheel, Grid, and Ocean View each represent a graphical entity within the user interface. These components run within the Ship's thread of control while implementing a set of features to handle user interface events and present the system state in a visual manner.


    2.1.1.1. Ship Class


    The Ship class runs as the client manager. It maintains the communication between each of the components that build up the client. Each user interface component is designed to handle an event representing the user's input; they then transform that event into a call to the Ship. The Ship interprets each call and will exert the set of actions that fulfills that request. The Ship maintains communication with the Treasure Hunt Server via Java's Remote Method Invocation (RMI).

    The Ship will communicate with each component in fulfilling the client's actions. If the client makes a request to move the ship, deploy a diver, or execute a sonar scan, the appropriate user interface component will invoke the operation on the Ship. The Ship will provide a set of operations that fulfills each of those requests.

    2.1.1.1.1. Move the Ship

    The Move request is implemented within the Ship. It may be invoked by the Ocean View component or by the Navigation Wheel component. The Ship will contact the Ocean server, via RMI, and request to move to a new location on the map. The Ocean will then determine if the Ship is capable of moving to the destination and will return a value representing the Ship's success or failure. If the Ship has successfully moved to the location it will request a View Scan of the new location from the Ocean. When the Ocean returns the scan, the Ship will hand it over to the Ocean View component for updating the user.

    2.1.1.1.2. Deploy a Diver

    The request to deploy a diver is invoked by the Ocean View. The Ship is requested to deploy the diver at a location relative to itself. The Ship will check that it has divers on board for deployment. If so, the ship instantiates a Diver object and specifies which location on the ocean floor to search. Since the Diver is within its own thread of control, the Ship will continue to service the user's requests until it hears back from the Diver. The Diver may reply with either a success or failure, informing the Ship about the amount of treasure found. It may also inform the Ship about the death of the diver that it represents.

    2.1.1.1.3. Execute a Sonar Scan

    The execution of the Sonar Scan is implemented within the Ship. It is invoked by the Treasure Hunt Frame and represents a sonar scan of the ocean floor directly below the ship. The Ship will contact the Treasure Hunt server and request a sonar scan at its current location. The Treasure Hunt server will return the scan, which simply denotes to the client that there may be something of interest below the ship (i.e. a treasure, a reef, or a shipwreck). The Ship will then present the scan to the Grid Component so that it may update the user.

    2.1.1.2. Diver Class


    The Diver class executes within its own thread of control. This allows the Ship to continue to service the user and a set of multiple divers. As the Diver is instantiated from the ship, it is provided with its location relative to the ship. It will then contact the Treasure Hunt server via RMI. It will inform the ocean that it has started its scan of the floor within the quadrant. The server will return a value representing the amount of time that the Diver will take in scanning the floor. Once the Diver has received the value, it will suspend its thread of control for the duration. Once the Diver's thread has been awakened, it will contact the Treasure Hunt server and receive a DiverScan object representing what the Diver has found.

    The suspension of the Diver thread is important to model the actions of a Diver. It represents the amount of time the Diver needs in order to scan the ocean floor. The delay and set of two communications also provides the Treasure Hunt server with information regarding the time that it has entered the quadrant and when it has left the quadrant. This delay makes it possible for two Divers to attempt to occupy the quadrant at one time. In such a case, the server simulates a duel between the two divers.

    The Diver's second request to the Treasure Hunt server returns the DiverScan object. The object contains several pieces of information. First, it denotes whether or not the Diver faced a dual while diving for treasure. If a dual did occur, a second bit of information denotes the outcome of the dual. This is important for the Diver to determine whether or not it survived during its dive. Also, included within the DiverScan is the detailed description of that ocean floor quadrant.

    Once the Diver has ascertained the outcome of its dive, it will inform both the Ocean View Component and the Ship of the outcome. The Ocean View will update the display with an animation showing the results of the diver. The Ship will update its count of Divers. If the diver returned, then he is "back onboard" the Ship and prepared to dive again. If he died, the Ship has one less Diver to work with throughout the game.

    Below is a prototype of the user interface:




    The user interface has several graphical components to handle the user input events and display the status of the game to the user. These components include the Treasure Hunt Frame (the main window or frame of the application), the Ocean View Component (the graphical panel displaying what is seen above water), the Grid Component (the graphical location grid at the bottom), and the Navigation Wheel Component (graphical wheel at bottom right).

    2.1.1.3. Treasure Hunt Frame


    The Treasure Hunt Frame is the main frame for the client's graphical interface. Upon this frame rest each of the components to the interface. As user events enter the system they will be passed to the component that the event occurred within. These events are to be handled within that component, whether it is the Ocean View, Grid, or the Navigation Wheel Component. For cases when events occur outside of these components or are not handled by these components, the Treasure Hunt Frame will handle the event.

    Events handled by the Treasure Hunt Frame include initialization of a new game, quitting an existing game, and preparing the interface for one of the set of game commands. These commands include moving a ship, deploying a diver, and a sonar scan

    2.1.1.3.1. Moving a Ship

    In moving a ship the user will click on the "Move Ship" button and then click onto the Ocean View Component to determine the destination for the ship to move. First, when the "Move Ship" button is clicked the Treasure Hunt Frame will handle this user event, create a new event, and throw it to the Ocean View Component. This new event signals to the Ocean View that the next click to occur within its panel is a new destination. The ship may also be moved as detailed in the Navigation Wheel Component.


    2.1.1.3.2. Deploying a Diver

    When a user wishes to deploy a diver into the ocean, they click onto the "Deploy Diver" button. The user will then click onto the Ocean View. The Treasure Hunt Frame will manage the event handling for clicks on the "Deploy Diver" button. When the button is clicked, the Treasure Hunt Frame will create and throw an event to signal to the Ocean View that a diver is to be deployed. When the Ocean View receives the event, it will know that the next click will signal the location to deploy the diver.

    2.1.1.3.3. Sonar Scan

    The Treasure Hunt Frame manages "Sonar Scan" button events. When the button is clicked, the Treasure Hunt Frame informs the Ship of the action. This is a simple event because a sonar scan only occurs directly below the ship. If the game were to change to allow sonar scans away from the ship, these events would be handled similar to the diver deployment.

    2.1.1.4. Ocean View Component


    The component responsible for providing the ship's view of the ocean is the Ocean View. The Ocean View maintains the ship's display for the ocean surface, surrounding land, neighboring vessels, and the location of the ship. For each move the ship makes, the Ship will query the Ocean Server for a ViewScan object. That ViewScan object is then handed over to the Ocean View Component so that it can display the results to the user. Each object in the ViewScan will have its own graphical representation, probably a bitmap image, which is shown to the user.

    The Diver also communicates with the Ocean View to display the results of the dive. When the Diver has finished its dive to the ocean it will contact the Ocean View so that it can display the results to the user. The Ocean View will draw a graphical representation of either a successful (found treasure) or unsuccessful dive. There will also be representations for demonstrating the results of underwater encounters between divers.

    The Ocean View interacts with the Treasure Hunt Frame and the Grid Component when handling the user interface. The interaction between these components is event based and results in implicit operation invocation. These communications are described in Section 2.1.2.

    2.1.1.5. Grid Component


    The Grid is a graphical representation of the partitioning of the Ocean View. As the user runs his/her mouse through the Ocean View, the corresponding square in the Grid becomes highlighted. This allows the user to gain perspective on the ocean layout and improve accuracy on ship movement and diver deployment actions.

    The Grid also displays results of the sonar scan. Because the SonarScan only denotes a simple yes/no value, a simple animation will display whether or not there is an object of interest found during the sonar scan.

    2.1.1.6. Navigation Wheel Component


    The Navigation Wheel is provided as a second option to request the movement of the Ship. The user may wish to quickly move his/her ship to avoid competition. This is difficult to do when the move operation requires a sequence of user actions (i.e. click on "Move Ship", click on destination) so the Navigation Wheel is a shortcut for the user to quickly control their ship.

    2.1.2 Event Based Architecture


    2.1.2.1. Graphical User Interface Events



    Java technology includes an Abstract Window Toolkit (AWT) that provides support for an event driven user interface. Each component of the user interface implements a handleEvent operation. This operation is executed when the user invokes an action within the user interface. The AWT generates an event corresponding to the user's action and throws the event. If the handleEvent operation is defined for the component, it is executed with the event as its parameter.

    Each component of the user interface is required to handle its own events. Events generated by the Navigation Wheel are handled by the Navigation Wheel Component; and so on for each user interface component. This helps to encapsulate events and their corresponding system actions into individual control components. The alternative is to have a single event manager handling all the user events for the system. This alternative is a functional decomposition and does not correspond to modular decomposition provided.

    2.1.2.2. System Generated Events


    A second use of the event-based architecture includes the intermodule events between the user interface components. These communications are denoted in red in the class diagram. Communication between the OceanView and the Treasure Hunt Frame and communication between the OceanView and the Grid are event based.

    2.1.2.2.1. OceanView - Grid Events

    The Grid Component acts to mimic mouse movement within the OceanView. As the user moves the mouse through the OceanView Component the corresponding grid in the Grid Component is highlighted. This allows for the user to visualize a grid breakdown of the OceanView.

    The OceanView handles AWT events signaling where the mouse is within its Panel. As the mouse moves through the Panel, the OceanView signals the Grid. Each time the mouse moves into or out of a grid square, the OceanView Component creates an event. The Grid then handles the event, highlighting the appropriate square within the component.

    2.1.2.2.2. Treasure Hunt Frame - OceanView Events

    Event based invocation is used to signal the OceanView when the user is about to deploy divers or move the ship. The user clicks on the "Move Ship" or "Deploy Diver" button. The Treasure Hunt Frame handles the user event from the AWT. It then creates an event to be handled by the OceanView. This event signals to the OceanView that the next click to occur within the OceanView represents either a ship movement or diver deployment.

    2.1.3 Client Design Support


    2.1.3.1. Usability


    The user interface for the Treasure Hunt client only requires use of a mouse. Integrating keyboard and mouse use can result in cases where the user is unsure of how to invoke the action that they wish to occur. Therefore, each command that can be invoked by the user is available via the graphical user interface.

    Keyboard input is supported. Cases such as expert users or mouse less users have required the necessity to provide shortcut keys for user actions. Shortcut keys will be provided for invoking a sonar scan, moving the ship, and deploying a diver. In cases where the shortcut key is invoked to move a ship, the ships quadrant of the grid becomes highlighted. The user can then use the arrow keys to select a quadrant for movement or deployment. Once the quadrant is selected the user will hit "Enter". The Grid highlights quadrants as it would for mouse movement.

    The actions that a user can invoke have been tailored in an attempt to improve on the user's capability to become fluent with the system. They have been evaluated and reduced down to the minimal set required to provide the functionality. Learning the game only requires learning the small set of actions available to the user (ship moving, sonar scan, and deployment of divers).

    2.1.3.2. Network Distribution


    As the distribution between client and server is event-based, there is no network overhead resulting from a continually polling application. The network message requirements are those needed to implement the distributed communication. The messages include moving the ship, requesting the ship's view, requesting a sonar scan, diver deployment, and completing a diver scan. Each message sent from the client is followed by a reply from the server. These messages are only sent based on user events, so the network load is minimal. If the user requests to move a ship, the ship is moved and a request is sent for the new VisualScan. The client application then sits idle waiting for the user to request the next action. Because of the small network load, this application can be implemented over both dialup and high-speed networks.

    2.2 Server Architecture


    The Treasure Hunt server is implemented as a standalone Java program. The server uses an object-oriented architecture.

    2.2.1. Object Oriented decomposition


    The Treasure Hunt server functionality is decomposed into five major classes. These classes are: Ocean floor class, Square class, DiverScan class, ViewScan class, and SonarScan class.

    2.2.1.1. Ocean Floor Class


    The Ocean Floor class maintains and reports positions of all objects in the Treasure Hunt including number and position of ships, number and position of divers, number and position of treasures, reef, islands and sharks.

    The Ocean Floor class facilitates ships and divers searching the ocean floor. It accepts search requests from Treasure Hunt clients (Diver scan, View scan and Sonar scan). The server interacts with the ocean floor and reports the findings about the area and item being searched to whom submitted the request.

    The Ocean Floor class tracks object positions and resolves occupancy conflicts over identical ocean floor squares. Possible conflicts include: ship/ship, diver/diver, ship/island, and diver/shark.

    2.2.1.2. Square Class


    The Square class describes the above water and underwater contents of an ocean quadrant. The surface of an ocean floor quadrant can contain an island, water, or treasure hunting ships. Underwater an ocean floor quadrant can contain reefs, treasure, and shipwrecks.

    2.2.1.3. DiverScan Class


    The DiverScan class describes the results of a diver's underwater search for treasure. The DiverScan object reports finding: treasure, reefs, shipwrecks, sharks, or nothing.

    2.2.1.4. ViewScan Class


    The ViewScan class is used to describe the items above the water within the visual scanning range. ViewScan objects describe the observation of islands, ships, or nothing (water).

    2.2.1.5. SonarScan Class


    The SonarScan class detects whether or not there is an item of interest within the sonar scanning range. Those items of possible interest include treasure, reef, and shipwrecks. The sonar scan does not discern the type of item detected. The type, and quantity of items, is unknown. To identify type and quantity of an item, the ship must send a diver to explore the quadrant.

    2.3. Client/Server Communication





    In all client/server architectures, there must be a method by which the client communicates with the server and visa-versa. A very common method is to use a communication protocol supported by TCP/IP sockets.

    Our Treasure Hunt client must interact and use objects, and object methods residing on the Treasure Hunt server. To access these objects we use Java RMI, Remote Method Invocation. Java RMI, is the Java implementation for remote procedure calls. It is based on TCP/IP socket based communication. Using Java RMI, the client application can use methods and instantiate objects that reside on the server. Java provides built-in support for marshalling data for proper execution of object methods on remote computers with RMI technology.

    2.3.1. Layered Architecture





    We have a Java RMI class which acts as the communication layer that encapsulates the Treasure Hunt Server. Treasure Hunt clients never interact directly with the Treasure Hunt Server. All interaction is passed through the communication layer. With the communication layer abstracted from the Treasure Hunt server, we can replace the communication layer with a new layer using a completely different communication technology. This change can be accomplished with no code changes to the Treasure Hunt Server. This architecture abstracts the system functionality from the communication in the system.

    2.3.2. Interface Abstraction


    Java requires the use of interface files to present available functionality to remote clients. The client must know the format of the methods available on the RMI server. Common interface files are shared between the Treasure Hunt client and RMI Server. These interface have no code. They are simply files with the function/method prototypes defined. This is known as Interface Abstraction. The interface is abstracted from the code that implements the functionality. The RMI Server actually implements the interface, and provides code that performs the actions of the defined interface.

    The architectural paradigm offers great advantages to support backward compatibility with future versions of the system. For future releases of the server, we can create new interface files that the new clients can use. New servers should support all known interfaces until no longer possible. This allows a specific method call to be modified to include new parameters, without breaking backward compatibility for that method.




    2.3.3. System Components


    The client/server diagram defines the following system components: Treasure Hunt Client, RMI Server Interface, RMI Server, and Treasure Hunt Server.

    2.3.3.1. Treasure Hunt Client


    The Treasure Hunt client makes calls to functions defined in the RMI server interface file.

    2.3.3.2. RMI Server Interface


    The RMI server interface is a collection of function/method prototypes that defines the interface that the RMI server provides. This interface contains no code, only prototypes defining the inputs and outputs of the methods.

    2.3.3.3. RMI Server


    The RMI server implements the RMI server interface. The RMI Server provides results to the client. The RMI Server is a layer of abstraction that encapsulates the Treasure Hunt server. This layer is the communication layer that provides the mechanism through which clients interact with the Treasure Hunt Server.

    2.3.3.4. Treasure Hunt Server


    The Treasure Hunt server does not communicate directly with Treasure Hunt clients. The methods and data of the Treasure Hunt server are encapsulated by the RMI server, which provides communication to clients.

    2.4. Reliability Support


    The Treasure Hunt system, written in Java, will implement the try/catch clauses to catch and handle all errors and exceptions that occur during runtime. A through unit test will be conducted with each class before integrating it with the system. An error handler class will record error information to a text file, helping developers to reproduce and correct errors. The error information will include: error name, class, method, date/time, and machine name.

    An error-tracking database will be utilized to track the status of errors found in the system. Developers will use the database to record information about re-creation, and correction of errors in the system.

    We believe that by implementing the measures described above the Treasure Hunt Game system should be able to achieve the Mean Time to Failure (MTF) requirements as stated in the system's functional specification.

    2.5. Versioning Support


    Using interface abstraction as described in section 2.3.2 the Treasure Hunt server's will support backward compatibility for all clients with the same major release number. When a new server is released, it will support all previous interfaces known interface having the same major release number. If for some reason a previous interface can't be supported, then the server must increment the major release number.

    Using this versioning design, clients are only guaranteed to work with servers that have the same version number or greater

    2.6. Coding Standard


    The implementation of the Treasure Hunt system will follow a coding standard that supports understandability and readability.

    2.6.1. Consistency


    Each piece of code should be written in an internally consistent style. Coding standards incorporating variable naming standards, indentations standards, and commenting standards will be implemented to support code consistency.

    2.6.2. Modularity


    The following are guidelines to support system modularity.
         
  • Each method (procedure) should be no more than 30 lines long.      
  • All modules requiring more than one compilation file must use Java packaging.

    2.6.3. Error handling


    The following are guidelines for a system level error handling class.
         
  • No error condition should ever cause a system crash.      
  • Error messages should be logged into an error database on each client's machine. Logged error messages should include some indication of where in the code the error occurred (e.g., method name) and a description of the error.

    2.6.4. Documentation


    2.6.4.1. Class/Method Headers


    Each file, class/module, and function/element should include header comments with the following information.

    File:    author's full name, date, purpose of classes in file, history. Class:   name, author, date, purpose, property name and purpose, method name and purpose, and history Method: name, author, date, purpose, parameters (inputs and outputs), and history

    The suggested examples show in section 1.7.1.2 could be used.

    2.6.4.2. General.


         
  • The header should include descriptions of algorithms when not clear from context. Any limitations of anticipated extensions should also be noted.      
  • Any obscure code must include line comments explaining the obscurities.      
  • Code that is altered, untested, or known to be buggy must include warning comments.      
  • When a developer modifies another programmer's code, they should include initials and reason for the change.      
  • Each version should contain a document explaining features of the version including version differences.

    2.6.5. Testing


    No module can be deemed complete until it is thoroughly tested and tidied up, and until all code commenting is done.

    2.6.6. Naming conventions


    We use a slightly modified Hungarian Notation for the Treasure Hunt coding standard.

    2.6.6.1. Class name


    Capitalize the first letter of a class name. If the class consists of several words, they are run together and the first letter of each embedded word is capitalized. Such as:

          Class VisualScan {...

    2.6.6.2. Method name


    Just as it is for classes except that the first letter in the identifier is lower case. Such as:

          int getVisualScan () {...

    2.6.6.3. Variable naming


    Variable names should be prefixed with a letter to indicate variable type. The prefix should be lower case, followed by the first letter of the Variable name in upper case.

          boolean bHelloWorld = TRUE;
          double dFooBar = -345.53224324324;

    Constant should be in all UPPERCASE letters.

          public static final int nVARIABLE = 342;

    Arrays can be prefixed with a letter a, before other prefix letters.

          public long alScores [ ];

    2.6.6.4. GUI component names


    Naming Conventions will be extended to include GUI components.

    2.7. Trace-ability Matrix


    Functional Requirement
    Requirement Description
    Design Support
    1.1.1.3
    Network System 2.3, 2.1.3.2
    1.2.1.1
    Ocean Quadrants 2.2.1.1
    1.2.1.2
    Tracking of Object Positions 2.2.1.1
    1.2.2.1
    Ship Movement 2.1.1.1.1, 2.2.1.1,2.1.1.3.1,2.1.1.6
    1.2.2.2
    Sonar Scan 2.1.1.3, 2.1.1.3.3,2.2.1.5
    1.2.2.3
    Visual Scan 2.1.1.4,2.2.1.4
    1.2.2.4
    Ships launch Divers 2.1.1.1.2, 2.1.1.3.2
    1.2.3.1
    Divers search for Treasure 2.2.1.3,2.1.1.2
    1.2.3.2
    Hostile Diver Encounters 2.1.1.2
    1.2.3.3
    Finding Reefs, Ship Wrecks, or Nothing 2.2.1.3
    1.2.3.4
    Diver Movement 2.1.1.2
    1.3.1
    Mouse Support 2.1.3.1
    1.3.2
    Keyboard Support 2.1.3.1
    1.4.2
    Application Fluency for average use in 15 minutes 2.1.3.1
    1.5.1
    Ship Movement Performance 2.1.3.2
    1.5.2
    Diver Response Performance 2.1.3.2
    1.6.1
    Client Mean Time to Failure 2.4
    1.6.2
    Server Mean Time to Failure 2.4
    1.7.1
    Understandability 2.6.4
    1.7.2
    Readability 2.6.1, 2.6.2, 2.6.6
    1.8
    Versioning Support 2.5

    3. Design Rationale


    Two types of rationale exist behind the design choices that have been made. This set of rationale has been explicitly documented via the key decisions made during the design or evaluated through a set of possible enhancements and design changes. Each decision is evaluated in terms of the requirements it fulfills, changes that are supported, features that become unchangeable, how the software design addresses the design decision, and any alternative design decisions that may provide perspective.

    3.1. Key Design Decisions


    3.1.1. Object Oriented / Abstract Data Type Structured Breakdown


    The Object Oriented decomposition attacks the requirements of understandability and system design flexibility. Decomposing the system into a set of data encapsulating modules improves the system's understandability. Because each module can be understood in its entirety, the combinations of modules allow for the system to be understood as a whole. With each component representing an actor in the system (the Ship, Diver, and Ocean), it is easy to describe the component's role in the system.

    System flexibility is improved because of the encapsulation and information hiding occurring with the module's data. Changes to the data can be maintained within a single component without interfering with interfaces between other system components. A strong case for an object-oriented decomposition can be made for the SonarScan, DiverScan, and VisualScan objects. These objects are data containers. The data within these objects represents the state of the system or outcome of an event. As the Treasure Hunt takes on new requirements throughout its lifecycle, scan objects can be expanded to include new descriptive data. A new requirement may be to enable the SonarScan to scan a larger/smaller region. Another future requirement may be to give a probabilistic distribution as to where the treasure is likely to be. The DiverScan class is extendable to support new game requirements. The size of a treasure could be larger than what a diver can retrieve in a single dive; the dive could be too deep for a diver to complete; the water may be murky so the dive takes much longer. Changes to the DiverScan class are able to accommodate many future requirements. The VisualScan can also be changed to encompass requirement changes. Such changes could include radar technology, mapping technology, and even ocean surface weather conditions.

    The Diver, Ship, and Ocean each have a defined set of functional capabilities. New requirements for system functionality will challenge the design's capability to support change. Alternative design decisions may provide for mechanisms that functionally decompose the system. Such decomposition does not seem to map well to expected changes because the system's purpose is not expected to change. Within a Treasure Hunt, the role of the ship, divers, and the ocean is expected to remain, while their capabilities may change.

    3.1.2. RMI Event Based Invocation


    The Treasure Hunt server interfaces with the client using Event Based, Remote Method Invocation (RMI). Events on the client such as a request to deploy a diver, or move the ship cause the client to invoke methods on the server. This technology allows methods to be invoked implicitly, when they are needed. Server initiated callbacks are invoked on client machines to communicate back results of operations such as a Diver's scan of the ocean floor. Using this method invocation, the need for polling is eliminated. The client or server never requires busy waiting during operation.

    An alternative to using Event Based, Remote Method Invocation (RMI), is implement the client to poll the server periodically to wait for state changes, and information updates. Periodic polling provides a programmatically simpler method for the client to receive data concerning diver scans, but it creates additional unnecessary network traffic, while adding a stress to the server's operation. If there were several dozen game clients all polling a single server, significant game delays could be seen.

    3.1.3. Layered Server Architecture


    The Treasure Hunt server is implemented with a layered structure. The RMI communication layer encapsulates the server classes. This separation of the game's functionality from the client/server communication interface is a design decision. This separation allows for infinite game logic changes to the Treasure Hunt server without changing the interface to the client. The game's functionality can be expanded and corrected without redistributing new versions of the client software. With the interface is decoupled from the game's functionality, we can support multiple clients, by supporting multiple interfaces. A single server can support multiple interface sets. This enables a single server to facilitate game play between clients having the same major version number. (see section 2.5, and 2.3.2)

    Another advantage to the server's layered architecture is the client/server communication protocol can be changed, without requiring any changes to the game's functionality and coding. RMI could be replaced with socket based communication, or even CORBA. This flexibility is a good example of how an n-tier architecture has advantages over a traditional client/server model.

    An alternative to a layered architecture is to couple the communication and server layer together. An example of this implementation would be a Treasure Hunt server written in C, using TCP/IP sockets to facilitate client/server communication. Communication logic would be coded integrated within functions implementing Treasure Hunt server logic. The disadvantage of this implementation is the server can't be changed without changing the client. To change the communication protocol would require a rewrite of the entire server. Implementing a change to the Treasure Server logic would require a code modification to code that is also responsible for communication among clients. This design would be difficult to test, maintain and update.

    3.1.4. Client User Interface Separation


    The user interface has been decoupled from the client classes into a separate set of GUI components and classes. The Ship and the Diver classes represent the client's Application Interface (API). The user interface implements the functionality required to allow users to play the game. The user interface interacts with the client through the defined application interface (API) provided by the client classes.

    The separation of the user interface allows the interface design to be changeable. New user interfaces can be implemented for the game, utilizing the same interface to the client classes. This allows for multiple interface types, such as a browser applet interface, a command-line interface, or a graphical application interface. The application interface between the client classes and the user interface is not easily changeable. If multiple user interfaces are implemented and the application interface (API) changes, each user interface implementation will require changes.

    Another benefit of the separating the client components from the user interface is the ability to change the client/server communication protocol. If the protocol between the client and the server changes (i.e. from RMI to Corba, JavaSpaces, or sockets), those changes are consolidated to the client components. Only the Diver and Ship classes require changes to implement a different communication protocol. The new implementation can be plugged together with the existing user interface and the system will remain operational.

    Bundling the user interface with the client classes is an alternative design decision for the client decomposition. If the client components are not decoupled from the user interface components, less formal design is required. This decision supports rapid development of the client with a cost of less flexibility in the future. To support changes to both the client interface and functionality we have chosen to decouple the client classes from the user interface components.

    3.1.5. User Interface Components and Choices


    The user interface has been broken down into a set of components that communicate through an event driven mechanism. Each component has responsibility for providing feedback to the user and taking input from the user. Both interact with the user interface component via the event handling mechanism. Each component must define a set of events that it handles; they may be created by the AWT or by other UI components. Likewise, each component has a define set of events that it may create. The communication is handled by the creation and throwing of events. The event will encapsulate the data required to handle the event. As events are thrown, the appropriate component will handle the event.

    The event driven user interface mechanism provides the capability to add new user interface components to the system. If a new component is added, it will service a new set of user events or system events. If it services a new set of system events, other system components will need to be changed. If the new component handles a new set of user events, a minimal set of changes will be required in other system components.

    3.2. Possible Enhancements or Design Changes


    3.2.1. Single Player


    The Treasure Hunt game requires multiple players distributed across a network for competitive game play. An enhancement would be to allow for single player games. This would require the computer to drive opponent ships in search for treasure to compete with the actual player.

    This feature could be realized by having a separate auto-play client. The auto-play client would interface with the Treasure Hunt server and pose as an ordinary opponent. This feature could also be implemented by having built-in server driven opponents within the Treasure Hunt server.

    Our design easily accommodates auto-play client programs. We would have to devise a method to start and stop clients, and also track the number of opponents to play the game.

    Implementing server driven opponents could require some recoding and extending of the Treasure Hunt server.

    3.2.2. Pirate Ships


    The Treasure Hunt game lacks combat on water. If pirate ships are implemented combat between player ships and pirate ships adds an additional challenge to winning the game.

    Another enhancement is to allow opponent ships to attack each other. If one opponent defeats another ship then the winning ship takes possession of the opponent's treasure.

    Our design should easily accommodate these enhancements. New features would need to be added to launch attacks on opponent ships, and for tracking incoming attacks.

    3.2.3. Treasure on Land


    The treasure could be placed on land as well as underwater. This would require that ships send rowboats to the islands, and then a search party would scour the island for treasure. Very similar to diving, this added dimension to the Treasure Hunt could be implemented in a similar manner.

    3.2.4. Technology Improvements


    When ships locate treasure an enhancement is to allow them to invest their wealth into the purchase of new technology to improve their capabilities of finding treasure. This enhancement would require the design and implementation of new technologies. Each technology could be purchased for a specified price and would enhance the ship's capabilities.

    In our design implementing new technologies would be similar to adding a new Sonar device. New classes and methods would be required on the server to support new technologies. The client would have to interface to these technologies to utilize them.

    3.2.5. Mapping Mechanisms


    A map editor tool could be implemented to allow the Treasure Hunt world map to be customized. This editor would allow for the placement of islands, reefs, shipwrecks, and treasures throughout the ocean map. This is an alternative to using a pre-generated or random map of the world.

    If the map data is handled externally from the Treasure Hunt server, then it really does not matter who generated the data. This tool could be an easy addition to the system if the map is kept external to the server.

    A logical addition is to have the ship record a map of everywhere it has been. This map should be displayable on screen, to allow the player to see the ships location relative to the charted world.

    3.2.6. Others


    Here are some additional potential system enhancements:

         
  • Provide terminal based access to the game, so people can play the Treasure Hunt game without a GUI, on legacy systems, or over poor network connections.      
  • Implement weather such as storms, wind, and water currents which effect ship travel speed, and navigation.      
  • Implement cloudy murky water, which disturbs a diver's search abilities, and the ship's sonar scan abilities.      
  • Develop and Support a Treasure Hunt client that runs on handheld devices. Support use of a joystick for game play. Use voice recognition to allow users to play the game by voice commands only.