GNTicker Trace Protocol

GNTicker Trace Protocol (GNTP) is designed to allow two-way communication between the GNTicker server (TS) and its clients. The main tasks which can be accomplished using GNTP are:

• Sending a generalized net definition to the TS
• Receiving events for token movement, entrance, leaving or merging from the TS
• Performing a number of steps of the GN execution
• Executing the GN until a specific event occurs, with an upper bound of the number of steps
• Providing client-initiated (active) input in the form of a token, which can be placed in a fixed input place of the GN
• Providing server-initiated (passive) input in the form of a string or double value with a query string
• Client or server initiated halting of the execution
• Error reporting from the TS on all requests

General principles

GNTP uses the design of the Hypertext Transfer Protocol for the presentation layer and XML for the application layer. GNTP messages are requests (issued by the client) and responses (issued by the server). Each message consists of the message preamble (protocol version and method name or response code), optional message headers and message body. The message body, if non-empty, is usually an XML document. The namespace used by the XML documents is the GN definitions namespace: http://www.clbme.bas.bg/GN, which is defined in the following XML schema.

A request to the TS should be formed according to the following template:

<GNTP-request> ::=	GNTP/<protocol-version>\r\n
			<method-name> <method-parameters>\r\n
			(<header>\r\n)*
			\r\n
			<request-body>

<protocol-version> ::=	<decimal-digit>.<decimal-digit>

<method-name> ::=	<capital-latin-letter> | 
			<capital-latin-letter><method-name>

<method-parameters> ::=	<decimal-number> |
			<decimal-number> <method-parameters>

<header> ::=		<header-name>: <header-value>

The GNTP headers will be presented in Headers. The method syntax will be presented in Methods. A response from the TS should be formed according to the following template:

<GNTP-response> ::= 
			GNTP/<protocol-version>\r\n
			<response-code> <response-details>\r\n
			(<header>\r\n)*
			\r\n
			<response-body>

<response-code> ::=
			<response-class><response-type>

<response-class> ::=	<decimal-digit>

<response-type> ::=	<decimal-digit><decimal-digit>

<response-details> ::=	<ANSI-string>

The response codes and details will be presented in Response codes.

Headers

Content-Length

Syntax

Content-Length: <decimal-number>

Description

Specifies the size of the message body in bytes. This header SHOULD be used in requests and responses every time, when the message body is nonempty.

Example

Content-Length: 173

Content-Type

Syntax

Content-Type: <media-type>

Description

Specifies the media type (MIME type) of the message body. This header is optional, if not specified "text/xml" type is presumed by default.

Note: only XML messages are supported up to now.

Example

Content-Type: text/xml

Methods

INIT

Syntax

	INIT

Description

The INIT method should be the first method, which a client should use. A client should use the INIT method to send a GN definition to the server. Only one INIT method should be sent to the server by the client. Each new GN execution requires a new connection to the server. The message body is an XML definition of a generalized net starting with a <gn> element and conforming to GNschema.xsd.

Example

	GNTP/0.1
	INIT
	Content-Length: 492
	
	<?xml version = "1.0"?>
	
	<gn xmlns = "http://www.clbme.bas.bg/GN" name = "MinimalGN">
	   <transitions>
		  <transition id = "Z1">
			 <inputs>
				<input ref = "L1"/>
			 </inputs>
			 <outputs>
				<output ref = "L2"/>
			 </outputs>
			 <predicates/>
		  </transition>
	   </transitions>
	   <places>
		  <place id = "L1" priority = "1"/>
		  <place id = "L2" priority = "1"/>
	   </places>
	   <tokens/>
	   <functions/>
	</gn>

Comment

A minimal GN is loaded in the server.

HALT

Syntax

	HALT

Description

Clients should use the HALT method to initiate halt of the GN execution. The client has to wait for the server to respond and close the connection. The HALT method should be used only after an INIT method. The HALT method does not require a message body.

Example

	GNTP/0.1
	HALT

Comment

The current GN execution is halted and the memory for the GN is freed.

STEP

Syntax

	STEP [<number-of-steps>]
	<number-of-steps> ::=	<decimal-number>

Description

Clients should use STEP in order to execute a number of GN steps of a previously loaded GN. If the parameter is omitted, a default value of 1 is presumed by default. If all the steps are executed correctly, the server responds with an XML document, describing all events in the GN during these steps. The STEP method does not require a message body.

Example

	GNTP/0.1
	STEP 10

Comment

The loaded GN is executed for ten steps and events are returned in response.

STEPUNTIL

Syntax

	STEPUNTIL <event-name> <number-of-steps> [<token-ids>]

	<event-name> ::=	ENTRANCE|MOVEMENT|EXIT|MERGE

	<number-of-steps> ::=	<decimal-number>

	<token-ids> ::=		<token-id>|<token-id> <token-ids>

	<token-id> ::= 		<identifier>

Description

Executes a GN until a step, where a specific token event occurs. Events are correspondingly entrance of a token, movement of a token, exit of a token or merging of a token. Note that the whole last step is performed, i.e. execution is not stopped immediately when the event occurs but only after the step is completed. The <number-of-steps> specifies the maximum number steps which are performed, while waiting for the event. It is a required argument to avoid infinite cycles. If a list of token IDs is specified, then only the token with IDs in the list are monitored for the selected event. The STEPUNTIL method has to be executed after an INIT method. The STEPUNTIL method does not require a message body.

Example

	GNTP/0.1
	STEPUNTIL EXIT 100 MessageToken ErrorToken

Comment

The GN is executed until at least one of the tokens MessageToken or ErrorToken leaves the GN, or until 100 steps are completed.

TOKENS

Syntax

	TOKENS

Description

Clients should use the TOKENS method to insert tokens in the GN in the time of execution. Therefore, the TOKENS method should be used for active input in the GN. This method requires an XML message body with a <tokens> element, as described in GNschema.xsd. The TOKENS method can be executed only after the INIT method.

Example

	GNTP/0.1
	TOKENS
	Content-Length: 252
	
	<?xml version = "1.0"?>
	<tokens xmlns = "http://www.clbme.bas.bg/GN">
	  <token id = "PriceToken" host = "L1">
	    <char name = "Product" type = "string">PS/2 mouse</char>
	    <char name = "Pricce" type = "double">3.50</char>
	  </token>
	</tokens>

Comment

In this example the client requests to insert a token with ID "PriceToken" into the place with ID "L1". The token has two characteristics - a string characteristic "Product" with value "PS/2 mouse" and a double characteristic "Price" with value 3.50.

INPUT

Syntax

	INPUT [<number-of-inputs>]

	<number-of-inputs> ::= <decimal-number>

Description

The INPUT method should be used by the client when the last response by the TS requires input. Therefore, the INPUT method provides passive input in the GN. The TS initiates passive input with a Class 3 response code. The response body of a Class 3 response is an XML with an <input-request> element, containing <value> elements, conforming to GNschema.xsd. This body should be used as a template by the client and filled with client-provided data. The difference is that the result should be enclosed in an <input-response> element.

The INPUT method should be executed only immediately after a Class 3 response; it is also the only allowed method after such a response code. As with all other methods, INPUT has to be executed only after the INIT method.

Example

	GNTP/0.1
	INPUT
	Content-Length: 214
	
	<?xml version = "1.0"?>
	<input-response xmlns = "http://www.clbme.bas.bg/GN">
	     <item name = "Product" type = "string">Mouse pad</char>
	     <item name = "Price" type = "double">1.00</char>
	</input-response>

Comment

A client responds to a server Class 3 response code, which required two values: a string value with a query string "Product" and a double value with a query string "Price".

SAVE

Syntax

	SAVE

Description

The SAVE method should be used by the client to receive the current state of the GN. The server responds with a GN definition conforming to GNschema.xsd. If the GN model has already performed a number of steps, the current time of the GN is indicated by the time attribue in the <gn> tag.

As with all other methods, SAVE has to be executed only after an INIT method and when the previous respose code was Class 2.

Example

Client:

	GNTP/0.1
	SAVE

Server:

	GNTP/0.1
	200 Request completed successfully
	Content-Length: 504
	
	<?xml version = "1.0"?>
	
	<gn xmlns = "http://www.clbme.bas.bg/GN" name = "MinimalGN" time = "10">
	   <transitions>
		  <transition id = "Z1">
			 <inputs>
				<input ref = "L1"/>
			 </inputs>
			 <outputs>
				<output ref = "L2"/>
			 </outputs>
			 <predicates/>
		  </transition>
	   </transitions>
	   <places>
		  <place id = "L1" priority = "1"/>
		  <place id = "L2" priority = "1"/>
	   </places>
	   <tokens/>
	   <functions/>
	</gn>

Comment

A client queries the server for the current state of the GN model being executed. The server responds with a Class 2 success code and a GN, which has been executed for 10 steps.

Response codes

Response codes are used to help clients quickly identify the TS response. Most responses include a response body with XML containing details about the response. The root element of the XML document depends on the class of the response code. Below the response codes are listed by class.

Class 1 - Invalid request

Class 1 response codes are presentation level errors. They are issued by the TS if a server cannot understand the client request. The TS should not close the connection after Class 1 response codes. The response body of a Class 1 response is an XML document with an <request-error> element, conforming to GNschema.xsd.

Response	Explanation
100 Malformed request	The client request does not comply with the GNTP protocol. This code is sent when the server cannot parse the request.
101 Unsupported protocol version	The server does not support the required protocol version.
102 Method not implemented	The server does not implement the requested method.
103 INIT method expected	The client is trying to execute a method for running or changing the currently loaded GN model, but no GN has been loaded yet with the INIT method.
104 INPUT method expected	The TS has requested information with a Class 3 response code, but the client is trying to execute a method, different than INPUT and HALT.
105 Unexpected INPUT method	The client is providing passive information without being requested to do so by the TS with a Class 3 response code.

Class 2 - Successfully completed request

Class 2 response codes are sent by the TS if the request has been successfully completed. The message body of a Class 2 response is an XML document with an <events> element, conforming to GNschema.xsd.

Response	Explanation
200 Request completed successfully	The clients request has been completed successfully.
201 Request completed successfully after passive input	The TS issues this response code when the clients request has been successfully completed after a passive client input using the INPUT method.
202 Maximum number of steps of STEPUNTIL method reached	This is a response to a STEPUNTIL method when the monitored event did not occur but the maximum number of steps was reached.

Example of response code 200

Client:

	GNTP/0.1
	STEP 10

Server:

	GNTP/0.1
	200 Request completed successfully
	Content-Length: 609
	
	<?xml version="1.0"?>
	<events xmlns = "http://www.clbme.bas.bg/GN" start="0" end="9">
	  <entrance place="L1" token="Product" step="2">
	    <char name="Product" type="string">Desktop stereo speakers</char>
	    <char name="Price" type="double">15.00</char>
	  </entrance>
	  <movement place="L2" token="Client1" step="3">
	    <char name="ID" type="double">12345</char>
	    <char name="Name" type="string">John Doe</char>
	  </movement>
	  <exit place="L5" token="Client2" step="3">
	    <char name="ID" type="double">12346</char>
	    <char name="Name" type="string">Mary Jane</char>
	  </exit>
	</events>

Comment

The TS has executed steps from 0 to 9 inclusive. On step 2 the "Product" token has entered place "L1" with the specified characteristics. On step 3 the "Client1" has moved to place "L2" and token "Client2" has left the GN through place "L5".

Class 3 - More information needed

Class 3 responses are sent by the TS when the execution of the GN requires additional input. In this case the TS sends as a response body an XML document with an <input-request> element, conforming to GNschema.xsd.

Response	Explanation
300 Input request	This response code is used to notify the client that an INPUT method is expected to provide data. The possible methods after this response are INPUT and HALT.

Example of response code 300

Client:

	GNTP/0.1
	STEP 10

Server:

	GNTP/0.1
	300 Input request
	Content-Length: 200
	
	<?xml version = "1.0"?>
	<input-request xmlns = "http://www.clbme.bas.bg/GN" step = "3">
	     <item name = "Product" type = "string"/>
	     <item name = "Price" type = "double"/>
	</input-request>

Comment

The TS queries the client for two values: a string value with a query string "Product" and a double value with a query string "Price". An INPUT method, which is executed by the client in response to this request can be found in here.

Class 4 - Message body errors

Class 4 response codes are returned by the TS if an XML message body is not correct. An <xml-errors> element conforming to GNschema.xsd is returned as the response body containing details about the error. The TS should not close the connection after a Class 4 response code.

Response	Explanation
400 XML is not well-formed	This response code is sent if the XML document sent by the client is not well-formed.
401 XML validation errors	This response code is sent if the XML document sent by the client does not conform to GNschema.xsd.
402 XML parser internal error	This response code is sent if an exception occurs inside the XML parser used by the TS.

Example of response code 400

Client:

	GNTP/0.1
	INIT
	Content-Length: 490
	
	<?xml version = "1.0"?>
	<gn xmlns = "http://www.clbme.bas.bg/GN" name = "MinimalGN">
	   <transitions>
	      <transition id = "Z1">
	         <inputs>
	            <input ref = "L1"/>
	         </inputs>
	         <outputs>
	            <output ref = "L2"/>
	         </outputs>
	         <predicates/>
	      </transition>
	   </transitions>
	   <places>
	      <place id = "L1" priority = "1"/>
	      <place id = "L2" priority = "1"/>
	   </places>
	   <tokens>
	   <functions/>
	</gn>

Server:

	GNTP/0.1
	400 XML is not well-formed
	Content-Length: 250
	
	<?xml version = "1.0"?>
	<xml-errors xmlns = "http://www.clbme.bas.bg/GN">
	  <xml-error line = "19" column = "16">Unknown element 'functions'</xml-error>
	  <xml-error line = "20" column = "5">Expected end of tag 'tokens'</xml-error> 
	</xml-errors>

Comment

The XML element <tokens> does not have a closing tag, so the server reports XML errors.

Example of response code 401

Client:

	GNTP/0.1
	INIT
	Content-Length: 481
	
	<?xml version = "1.0"?>
	<gn xmlns = "http://www.clbme.bas.bg/GN" name = "MinimalGN">
	   <transitions>
	      <transition>
	         <inputs>
	            <input ref = "L1"/>
	         </inputs>
	         <outputs>
	            <output ref = "L2"/>
	         </outputs>
	         <predicates/>
	      </transition>
	   </transitions>
	   <places>
	      <place id = "L1" priority = "1"/>
	      <place id = "L2" priority = "1"/>
	   </places>
	   <tokens/>
	   <functions/>
	</gn>

Server:

	GNTP/0.1
	401 XML validation errors
	Content-Length: 181
	
	<?xml version = "1.0"?>
	<xml-errors xmlns = "http://www.clbme.bas.bg/GN">
	  <xml-error line = "4" column = "19">Required attribute 'id' was not provided</xml-error>
	</xml-errors>

Comment

The XML element <transition> does not have an id attribute, which is required in GNschema.xsd.

Class 5 - GNTicker interpreter errors

Class 5 response codes are sent by the TS on behalf of the GNTicker interpreter whenever there are errors in the GN definition or run-time errors. Note: most of the GN definition errors are reported as response code 401 as they can be detected via validation against GNschema.xsd. Class 5 responses cover GN definition semantic errors, which are not straightforward to detect. The response body contains XML with a <gnticker-errors> element conforming to GNschema.xsd. After sending any Class 5 response code, the TS closes the connection.

Response	Explanation
500 GN definition error	This response code is sent after an INIT method if the GN definition has errors, which are cannot detected by validation against the XML schema. Such errors may include double input or output place binding, invalid characteristic types, etc. One or more <gn-error> elements are nested in the <gnticker-errors> element.
501 GNTCFL definition error	This response code is sent after an INIT method if there are errors in the definition. Such errors may include all kinds of syntax errors, frame definition errors and undefined functions being referenced. One or more <gntcfl-error> elements are nested in the <gnticker-errors> element.
502 Runtime error	This response code is sent after a STEP or a STEPUNTIL method if any runtime errors occur in the GNTCFL functions. Such errors may include stack overflow, wrong number or type of arguments in call and errors raised by the GNTCFL primitives. One or more <runtime-error> elements are nested in the <gnticker-errors> element.
503 Input error	This response code is sent after an INPUT or a TOKENS if any errors while executing the input methods occur, which are not reported as a 401 response code. Such errors may include incorrect characteristic types, non-matching passive INPUT response by the client, duplicate token ID in a TOKENS method, incorrect token characteristic or host place. One or more <input-error> elements are nested in the <gnticker-errors> element.
504 Internal error	This response code is sent after any method if an exception occurs inside the GNTicker interpreter. This response code is also sent when the server cannot complete the request by the client because it is being shut down. One or more <internal-error> elements are nested in the <gnticker-errors> element.

References

• GNTicker Trace Protocol (GNTP)