Guidelines for developing a NOOGA XML Client
 

Before beginning our discussion of the NOOGA XML protocol, it would be useful to be aquainted with the basics of XML and DOM.
Some useful links to this purpose are:
 
 
 


 

Introduction to the NOOGA XML protocol :

The structure of XML is very similar to that of HTML in that it is basically composed of textual information nested within tags.
For example: All commands are sent in the format that follows:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE Command SYSTEM "dtd/CommandName.dtd">  ===> where CommandName.dtd can be replaced
<Command>
                <Method>        </Method>
                <Arg1>            </Arg1>
                <Arg2>            </Arg2>
                    .
                    .
                    .
</Command>
 

The name of the method that the server or client wants to call on the other side is encapsulated within the "Method" tags.
The following arguments can be encapsulated within appropriate tags.. not neccessarily "Arg1," "Arg2," etc...
This format must be followed even if the command has no arguments.
 

Ex. A command with no arguments

<?xml version="1.0" standalone="no"?>
<!DOCTYPE Command SYSTEM "dtd/CommandName.dtd">
<Command>
                <Method>"PlayGame"</Method>
</Command>
 
 

The header <?xml version="1.0" standalone="no"?> are instructions to the XML parser which tell it what version of XML is being used, and whether the XML document is standalone, or associated with a dtd. Additionally, the line Doctype declaration <!DOCTYPE Command SYSTEM "dtd/CommandName.dtd"> serves to identify the root tag and to tell the parser where to find the associated dtd file.
All XML communication with the NOOGA server, aside from the initial bootstrapping, MUST be validated with a dtd file, so the attribute "standalone" in the header should always equal "no".  A valid Doctype declaration must always be provided, or the server will automatically disconnect the player and return an error message.

On the server side, all dtd files for NOOGA games will be located in the directory "dtd/". Therefore, the SYSTEM attrubute of the Doctype declaration of any XML document going from client to server should contain "dtd/" followed by the appropriate dtd file name. The NOOGA server is very stringent on validation, and this procedure gives the server a protective layer from malformed, incorrect, or unexpected XML communication.

While it is not absolutely necessary that the client validate XML documents sent to it from the server, it is definately encouraged as a safeguard to promote stability and robustness. Depending on which XML parser the client is using, validation may need to be turned on in the client, or may not be available as a function of that particular parser. We recommend using the Xerces XML parser, available from Apache.
To activate validation with the Xerces parser, the following line of code needs to be executed:

Ex. myParser.setFeature("http://xml.org/sax/features/validation",true);

The client also needs to tell the server where it can find the dtd files to validate the XML documents. This is done in the bootstrapping process explained below.
 

Bootstrapping

The NOOGA server supports simple string communication as well as XML, so a joggle client needs to tell the server what protocol to use as well as the game type and location of the DTD files.
When the client opens a socket connection to the server, the server should send the string "SetupInfo\n" to the client. In this case, the joggle client should reply by sending "xml\n",  "joggle\n" (as in nooga.util.Constants), and "dtd/\n" in that order, where the directory "dtd/" is the location of the dtd files. Notice that this directory need not be local. A web address is perfectly acceptable. However, frequently accessing web addresses can cause your application to run slighltly slower than if the copies of the dtd files are local. It is therefore advisable to keep local copies of the dtd files, which are available at home/home3/bkk/public_html/dtd/
 

CAUTION: The NOOGA Server cannot ensure the integrity of textual data if unnecessary whitespace, such as carriage returns or other invisible characters are present in the XML document. It is advisable to omit these characters and to transmit the XML document as one long string without endofline characters.

Ex. We advise that the XML document above be transmitted in the following format:
<?xml version="1.0" standalone="no"?><!DOCTYPE Command SYSTEM "dtd/CommandName.dtd"><Command><Method>"PlayGame"</Method></Command>
 
 

Defining the interfaces
 

  • Guidelines for creating a XML Joggle Client
  • Guidelines for creating a XML Dots Client
  • Guidelines for creating a XML BattleShip Client

  •