[qs-dev] for review: documentation

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Hi,

======================================================================== 

Estimated hours taken: 18 

Write a document on how to build the server, how to extend the server
and the interface etc.

/server/USERGUIDE
	the newly added document.

======================================================================== 

This document covers the following topics: 

* Building the web-server
* Running the web-server
* Request methods
  I.  GET
  II. POST
* Encoding rules and schemas
  I.   Simple types
  II.  Enumerations
  III. Structures
  IV.  Lists
* Interface between the server and the client  
* Implementing new method and its interface
* Running the sample program
* References

-----------------------
Building the web-server 
-----------------------

Step 1: Checkout the web-server module with the following instructions:

  1. cvs 
     -d:pserver:ano...@cv...:/cvsroot/quicksilver
     login 

  2. Press the Enter key when prompted for a password.

  3. cvs -z3
     -d:pserver:ano...@cv...:/cvsroot/quicksilver
     co webserver 

Step 2: Build the webserver using the following commands:

  1. mmake GRADE=hlc.par.gc depend

  2. mmake GRADE=hlc.par.gc

It is recommended to use a recent Mercury ROTD to compile the server.
Any release of the day more recent then rotd-2000-08-29 should be fine.

---------------------
Running the webserver
---------------------

To run the webserver, type the following command:

  $ ./server

The server provides 3 options: host, port, and root. Host specifies 
the name of the host which will be listening for the requests; port
specifies which port the server is listening on; root specifies the
root directory for the html files to be served.

For example:

  $ ./server --host localhost --port 8080 --root .

The server now listens for any connection, either from its clients or
from some direct connections to the server (eg. telnet localhost 8080).

---------------
Request Methods 
---------------

Hypertext Transfer Protocol (HTTP) 1.1 is used to transfer requests 
and responses between the server and the client. The server supports 
the following request method: 

  I. GET
  II. POST

I. GET

The GET method requests a document from a specific location on the
server.

For example, the client wants to retrieve a file named `server.m' in  
the root directory of the server, thus the client issues the following 
request:

  GET /server.m HTTP/1.1

The corresponding response will be:

  HTTP/1.1 200 OK

  [Body of the document]

II. POST

The POST method sends data to the server. In particular, the POST method
is used to encapsulate and exchange remote procedure calls and responses.

A POST request includes a request, headers, and an entity-body containing
the data to be sent. The server uses Simple Object Access Protocol (SOAP)
1.1 to represent the data body. It is an XML based protocol that consists
of three parts:

  * a SOAP envelope describing what is in a message and how to process it;
  * SOAP encoding rules defining datatypes;
  * SOAP RPC representation defining a convention that can be used to 
    represent remote procedure calls and responses.

An example of SOAP message embedded in HTTP issuing a call to the predicate 
"Hello" in the library file "libsoap_test_methods.so" will be:  

  POST /libsoap_test_methods.so HTTP/1.1
  Host: www.cs.mu.oz.au
  Content-Type: text/xml
  Content-Length: 227
  SOAPAction:

  <SOAP-ENV:Envelope
   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Body>
      <GetStockPrice>
 	<stocknum xsi:type="xsd:int">1</stocknum>
      </GetStockPrice>
    </SOAP-ENV:Body>
  </SOAP-ENV:Envelope>

A SOAP envelope consists of a mandatory SOAP envelope, an optional SOAP 
header and a mandatory SOAP body. Currently the server accepts messages
with header without process it.

Inside the SOAP Body is the RPC, which includes the method name and the
parameters. Each element name within the method represents the name of
the parameter and the type represents the type of the parameter. These 
parameters appear in the same order as in the method call.  

Extra information:

  * HTTP applications must use the media type "text/xml" when including
    SOAP entity bodies in HTTP messages
  * An HTTP client must use "SOAPAction" HTTP request header field when 
    issuing a SOAP HTTP Request.
  * Assume only one RPC per SOAP message 

Responses, similar to requests, bind SOAP with HTTP such that headers 
use HTTP protocol and messages use SOAP protocol. Responses for RPC 
are represented by appending the string "Response" to the method name.

The corresponding response for the above SOAP message will be:

  HTTP/1.1 200 OK
  Content-Length: 199 
  Content-Type: text/xml

  <SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Body>
  <GetStockPriceResponse>
  <price>34</price>
  <GetStockPriceResponse>
  </SOAP-ENV:Body>
  </SOAP-ENV:Envelope>

(See http://www.w3org/TR/SOAP for more details)

--------------------------
Encoding rules and schemas
--------------------------

The server uses the following schemas to encode/decode mercury data
types. 

I. Simple types

A mercury predicate which takes in an integer, a float and a string will 
have the following schema

        <element name="arg1" type="xsd:int"/>
        <element name="arg2" type="xsd:float"/>
        <element name="arg3" type="xsd:string"/>

II. Enumerations

For mercury enumerations, eg.

	:- type fruit
		---> 	apple
		;	orange
		;	banana
		;	pear.

The schema will be:

	<element name="fruit" type="tns:fruit"/>     

	<simpleType name="fruit">
	  <restriction base="mercury:string">
	    <enumeration value="apple"/>
	    <enumeration value="orange"/>
	    <enumeration value="banana"/>
	    <enumeration value="pear"/>
	  </restriction>
	</simpleType>

III. Structure

For mercury structures, eg.

	:- type book
	       --->    book(
			       title   :: string,
			       author  :: author
		       ).

	:- type author
	       --->    author(
			       surname   :: string,
			       firstname :: string
		       ).

The schema will be:

	<element name="book" type="tns:book"/>
	<element name="author" base="tns:author"/>

	<complexType name="book">
	  <sequence>
	    <element name="title" type="mercury:string"/>
	    <element name="author" type="tns:author"/>
	  </sequence>
	</complexType>

	<complexType name="author">
	  <sequence>
	    <element name"surname" type="mercury:string"/>
	    <element name"firstname" type="mercury:string"/>
	  </sequence>
	</complexType>

IV. Lists

For mercury lists, eg.

	:- type list(T)
		--->	[]
		;	[T|list(T)].

The schema will be:

	<element name="list" type="tns:list"/>
	<element name="nil" type="tns:nil"/>
	<element name="cons" type="tns:cons"/>

	<complexType name="list">
	  <sequence>
	    <choice>
	      <element name="nil" type="tns:nil"/>
	      <element name="cons" type="tns:cons"/>
	    </choice>
	  </sequence>
	</complexType>

	<complexType name="nil>
	  <complexContent>
	    <restriction base="xsd:anyType">
	    </restriction>
	  </complexContent>
	</complexType>

	<complexType name="cons">
	  <sequence>
	    <element name="head" type="xsd:anyType">
	    <element name="tail" type="tns:list"/>
	  </sequence>
	</complexType>

-------------------------------------------
Interface between the server and the client
-------------------------------------------

This module, soap_interface.m, provides an interface for programmers
to send messages to the SOAP server. It is aimed to hide all the 
SOAP and HTTP details away from the client. In doing so, the client    
is able to communicate with the server in mercury types. 

In addition, the interface also allow an arbitrary XML message to be
passed using SOAP (and the response will be returned as XML too).  
This will allow programmers to use their own encodings and communicate
with any SOAP based service.

-----------------------------------------
Implementing new method and its interface
-----------------------------------------

When adding a new method, the following steps will have to be taken:

  1. Add the method in a separate module, for example, soap_test_methods.m 

  2. Modify web_methods.m such that the library code is loaded for the 
     new method when the server runs.

  3. Re-build the server.

     The server now supports the new RPC via direct access (ie. telnet
     to the server and send the request using HTTP and SOAP protocol). 

  4. Modify soap_interface.m to allow clients to send messages to the
     server in mercury types.  

An assumption that has been made is that, the client is assumed to have
a copy of the schema that is used in the server for encoding and decoding
types in XML. 

--------------------------
Running the sample program
--------------------------

The sample program demonstrates four common examples, ie. printing 
"Hello world", adding 3 integers, placing a query and placing a purchase 
order. In addition, the program accepts xml messages. 

To build the sample program, type the following commands:

  $ mmake client_demo.depend
  $ mmake client_demo 

To print "Hello world":

  $ ./client_demo -m Hello

To add 3 integers:

  $ ./client_demo -m Add3Ints --add1 1 --add2 2 --add3 3

To place query for a specific stock's price:

  $ ./client_demo -m GetStockPrice -i stocknumber 

To purchase a book:

  $ ./client_demo -m PurchaseBook -t booktitle -a surname,firstname

To print "Hello world" using XML format instead:

  $ ./client_demo -x "<Hello></Hello>"

----------
References
----------

http://www.w3.org/TR/SOAP
http://www.oreilly.com/openbook/webclient/