Test document for page.dtd and page2html.xsl

This is a test document for simple text pages that transform to a single web page. This is text before section1. Within this content section all text formatting is according to text.dtd. Most constructs can be found below.

Introduction

AMUSE is based on protocol interactions among client applications mediated by a server. These protocols provide generic support for common multi-user session activities such as:

These services are extensible for specific multi-user applications such as gaming, chat, teleconferencing and KeyStroke.

Test for anchor stuff. GO TO ANCHOR-14.

Concepts and Definitions

AMUSE concepts are described in "AMUSE Overview".

HERE IS ANCHOR 14

Protocol Specifications

The protocol architecture has been kept reasonably simple. From a network perspective the following happens from a client perspective.

  1. Connect to the AMUSE server through the bootstrap TCP/IP port (usually 4360) .
  2. Exchange XML messages over this connection.
  3. Disconnect.

The XML messages fall into two categories: (1) "AMUSE Protocol", generic messages related to session management. and (2) "Amulet Protocols", messages specific to a Amulet. Only the AMUSE Protocol messages are specified here and recognized by the AMUSE server. Amulet Protocol-specific messages are in general part of the application services. The AMUSE server will take care of routing them to the appropriate Amulets. The AMUSE framework provides ready-to-use Amulets for common services such as Chat, Resource Sharing and RTP data exchange.

AMUSE Protocol Services

Message
Description
<login>
login on an AMUSE server.
<logout>
logout from AMUSE server.
<enter>
enter a Space on the server.
<exit>
exit from a Space on the server. Also used as notification.
<agent>
notification from server that other agents are present in or have joined a Space
<join>
join a Amulet within a Space. Also used as notification.
<leave>
leave a Amulet within a Space. Also used as notification.
<list-spaces>
List information on Spaces from the MetaSpace (version 3.3 and up)
<nack>
"Negative acknowledgement". Sent by server when any of the above commands failed.

The tables below detail the protocol messages with their attributes. "Req", "Rsp" and "Ind" denote the direction and nature of a message. "Req" is a request from client to server. "Rsp" a response from server to client, "Ind" is a spontaneous indication (notification) from server to all clients. "Y" means that the attribute is sent, "N" means that it is not. "O" means that the attribute is optional. "N.A." means Not Applicable.

login

Attribute
Values
Req
Rsp
Ind
Comments
id
string
Y
Y
N.A.
must be registered user id
password
string
Y
N
N.A.
password is not sent back!
protocol-version
string
O
Y
N.A.
AMUSE protocol version, always returned by server
server-version
string
N
Y
N.A.
AMUSE server version, always returned by server

logout

Attribute
Values
Req
Rsp
Ind
Comments
reason
string
O
O
N.A.
optional reason

list-spaces-req|rsp

The <list-spaces-req> command can be used after login to get a list of available spaces. Through the "type" attribute only spaces of a certain type are returned in <list-spaces-rsp> .

Attribute
Values
Req
Rsp
Ind
Comments
type
string
O
N
N.A.
optional type, for example KeySpace or ChatSpace. Otherwise all spaces of all types will be returned.

The <list-spaces-rsp> will contain a set of <space> elements providing attributes for eadch space. Each element has at elast the following attributes.

Attribute
Values
Req
Rsp
Ind
Comments
id
string
N.A.
Y
N.A.
type, for example KeySpace or ChatSpace
type
string
N.A.
Y
N.A.
type, for example KeySpace or ChatSpace
agents
string
N.A.
Y
N.A.
current number of agents in space

enter

Attribute
Values
Req
Rsp
Ind
Comments
space
String
Y
Y
N.A.
Space name like "Space2001" or "KsTest".
name
String
O
O
N.A.
Optional user nick-name (see login for real user name).
uid
int
O
Y
N.A.
Optional preference. Unique user ID within Space.
role
String
O
O
N.A.
Optional role name. See note 1.
netid
String
N
Y
N.A.
Client local socket address/port.

Notes:

  1. If a role name is specified an optional role element may be contained. This remains to be defined.

agent

The syntax of this message is identical to <enter> with all "Ind" set to "Y" or "O" (if optional).

exit

Attribute
Values
Req
Rsp
Ind
Comments
uid
int
N
Y
Y
reason
string
O
O
O

join

Attribute
Values
Req
Rsp
Ind
Comments
uid
int
N
Y
Y
subject
String
Y
Y
Y
Name of the Amulet to join.

Notes:

  1. Additional Amulet-specific attributes/elements may be added/embedded. For example:

    <join subject="rtpchannel" clientport="5000"/>

leave

Attribute
Values
Req
Rsp
Ind
Comments
uid
int
N
Y
Y
subject
String
Y
Y
Y
Name of the Amulet to leave.

explore

The syntax for this message remains to be defined. Also it will not be required that one has entered a Space to issue this command.

nack

Attribute
Values
Req
Rsp
Ind
Comments
reason
String
N.A.
O
N.A.
Provides text of reason why command request failed.

Amulet Protocols

Specific messages for Amulets can be freely defined by those who develop Amulet implementations. The only requirement is that they follow this syntax:

<subject-name> <specific-messages> </subject-name>

Responses and notifications always carry the 'uid' attributes, such that a receiver knows by whom the message was sent. Examples:

(client with uid=3 sends chat message) <chat> <msg msg="here is my message to you" /> </chat> (others including sending client receive) <chat uid="3"> <msg msg="here is my message to you" /> </chat>

Carrier Protocols and Encoding

This section pertains to specific protocols that are used to carry the AMUSE XML protocol messages and specifies how messages are encoded.

TCP/IP Ping-Pong Protocol

When using TCP/IP for any multi-user or client/server purpose, there is always the possibility that the connection is physically broken or the client crashes (the server never crashes offcourse :-)). It may take several minutes before this is detected. In a multi-user session it may seem that a participant is still present since the server cannot detect an abrubtly broken TCP/IP connection. This is a common issue for many higher level protocols.

Enter the ping-pong protocol. The ping-pong protocol operates below the AMUSE protocol. It is initiated by the server to ask from clients: are you still alive ? It works as follows.

  1. at regular intervals the server sends the XML message <ping t="someNumber" /> to clients (t is the time at the server)
  2. the server expects a <pong t="someNumber" /> response within a certain timeframe (pongTimeOutMillis in server.xml config file)
  3. if at 1. sending fails immediately the server knows that the client has left
  4. if at 2. the client returns any other regular AMUSE messsage, the server knows the client is alive and starts retiming the pong
  5. if at 2. the timeout is reached the server knows that the client has left
  6. the "t" attribute should be returned unaltered by the client. It is used to determine the latency between client and server.

XML Message Encoding

XML messages are self-delimiting. They can be sent over TCP/IP as an ASCII string (ignoring Unicode for now). A receiver will know where a message begins and ends by parsing from the incoming TCP/IP packets. XML messages and TCP/IP packets don't map one-to-one however: one TCP/IP packet may contain multiple XML messages or an XML message may be split over multiple TCP/IP packets. The best strategy is to parse XML directly from the incoming TCP/IP stream regardless of the packets.

Enter Flash clients. Yes, your Flash (5) application can be a client of the AMUSE server using a Flash XMLConnection object. What we discovered is that Flash adds a '\0' (hex 0x00) after each XML message. For this reason the AMUSE server will also append a 0x00 to all its outgoing XML messages, but does (yet) not expect clients to send 0x00 after each message. As a client you may use this to read an entire XML message before decoding.

Scenarios

The syntax is illustrated in scenarios below. These follow the steps:

  1. AMUSE Server listens on one TCP/IP port (usually 4358)
  2. Client connects with TCP/IP to that port
  3. Further steps are below. For now using raw test output. "Request" is from client to AMUSE server. "Response" is from AMUSE server to client.

========================== TEST: name=login --Request[client1] <login id="just" password="my-password /> --Response[client1] <login id="just" protocol-version="1.0" server-version="1.0.6" /> ========================== TEST: name=enter --Request[client1] <enter name="justio" space="KsTest" role="player" /> --Response[client1] <enter uid="0" name="justio" role="player" space="KsTest" netid="194.134.18.14:1048" /> ========================== TEST: name=join --Request[client1] <join subject="chat" /> --Response[client1] <join uid="0" subject="chat" /> ========================== TEST: name=msg --Request[client1] <chat > <msg msg="hello" /> </chat> --Response[client1] <chat uid="0" > <msg msg="hello" /> </chat> ========================== TEST: name=leave --Request[client1] <leave subject="chat" /> --Response[client1] <leave uid="0" subject="chat" /> ========================== TEST: name=exit --Request[client1] <exit /> --Response[client1] <exit uid="0" /> ========================== TEST: name=logout --Request[client1] <logout /> --Response[client1] <logout />

Open Issues

Test for anchor stuff. GO TO ANCHOR-14.

  1. Roles
  2. Explore syntax
  3. Splitting usernames into name (email) and nick.

Just van den Broecke - November 1, 2002 - $Id: mypage.html,v 1.2 2002/07/07 21:49:43 just Exp $