jCML Communication Protocol

The jBASE Remote Connectivity Layer defines a communication protocol, which the client library uses to send requests to and receive replies from the remote server process. The protocol is based on Extensible Mark-up Language (XML) and will be named JCML (jBASE Communication Mark-up Language). The structure of JCML is discussed further in this section and is based on the following assumptions:

1. The underlying networking protocol used for transmission of JCML is connection-oriented, reliable, error-correcting and stream-capable. Protocols falling into this category are TCP, SPX, UNIX domain sockets, stream pipes, and FIFOs. The implementation of JCML will be discussed in the context of TCP/IP, but this specification does not preclude implementation of JCML on other fundamental network protocols.
2. All data link security is handled in the underlying network protocol. The security strategy may include access restriction techniques, such as firewalling, or transparent data encryption (PPTP, IPSec, SSL, or SSH tunnelling). JCML does not incorporate any security features and in its unmodified form is suitable for LANs and VPNs.
3. JCML messages are synchronous and atomic and assume that requests are paired with replies from the server and that not more than one outstanding request is pending for the server at any given instant. This implicitly assumes that requests from multiple client threads are serialized prior to being communicated to the server.

Overall Structure of JCML

JCML mark-up incorporates several tags, defining the structure of the message. The tags are listed in the following table:

The valid message formats in JCML are defined below.

Request for service is the message sent by the client library to the remote server to initiate a service request (remote function call). The format of the message is as follows: 

1. A <jcml> tag with src="client" and type="req".

2. A <obj> tag with handle of the target object.

3. A <cmd> tag with name of the function to be invoked on the object.

4. Zero or more optional <data> tags with encoded function parameters.

Example:

The XML fragment above calls the function oconv in object 0 (connection object) and passing it string "Test" as the first parameter and string "MCU" as the second parameter.

The service reply message is sent by the remote server after the processing of the client‟s request is completed. The message is formatted as follows:

1. A <jcml> tag with src="server" and type="reply".

2. A <stat> tag with id set to the return code and containing the error message.

3. Zero or more <data> tags containing return values.

Example:

<?xml version="1.0" encoding="UTF-16"?>

<jcml src="server" type="reply">

<stat id="0"></stat>

<data enc="esc">TEST</data>

</jcml>

This example illustrates a possible server reply to the sample request constructed in previous section. It instructs the client that the server function has completed with status code of 0, no error messages, and the return value is "TEST".

This message may be sent by the server to the client while the request for service is being executed. It indicates that the server has generated terminal output during the course of its processing and is supplying the output to the client. This message requires neither acknowledgement nor a reply. The structure of the message is as follows:

1. A <jcml> tag with src="server" and type="termout".

2. A <data> tag supplying the terminal output. Due to the fact that terminal output may contain non-printable characters and escape codes, this parameter is typically base64-encoded.

Example:

<?xml version="1.0" encoding="UTF-16"?>

<jcml src="server" type="termout">

<data enc="base64">VGVzdCBvdXRwdXQK</data>

</jcml>

This example illustrates a terminal output message from the remote server supplying a base64-encoded string "Test output" to the client.

A request for input is sent to the client when the server encounters a command requiring terminal input while processing the client request. This message requires the client to send back a terminal input message with input characters for the server process. The request for input is typically formatted as follows:

1. A <jcml> tag with src="server" and type="prompt".

2. An optional <data> tag with a parameter defining the maximum length of input requested. If this parameter is omitted, the amount of input the client can supply is unlimited.

Example:

<?xml version="1.0" encoding="UTF-16"?>

<jcml src="server" type="prompt">

<data enc="esc">100</data>

</jcml>

This example illustrates the server request for at most 100 characters to be returned from the client.

The terminal input message is sent by the client in response to the server‟s request for input. This message has the following format:

1. A <jcml> tag with src="client" and type="termin".

2. A <data> tag with terminal input characters supplied to the server. The input is typically base64-encoded because it may include binary data. The data itself is not converted to UTF-16, but is base64-encoded and passed verbatim to the server.

Example:

<?xml version="1.0" encoding="UTF-16"?>

<jcml src="client" type="termin">

<data enc="base64">VGVzdCBpbnB1dAo=</data>

</jcml>

This example illustrates a terminal input message sent to the server with base64-encoded string "Test input" as input.