Data object subscription <Subscribe/>

This command requests asynchronous data updates based on content changes of a data object or data member elements from the server. Requests are specified by a simple url (e.g. EngineSpeed). The data updates will be sent using <Dat/> envelopes.

The <Dat/> envelopes shall be sent, when the content of the data object specified by url is updated at the event source or by the server application implementation. To initialize the client applications state, a <Dat/> message with the current object state shall be sent immediately after the subscribe command was accepted, even if the state of the newly subscribed data object is "nodata" or "error".

• Note 1: A subsequent <Subscribe/> request (i.e. with the same url) shall overwrite an existing request. If the optional attributes are not specified, the default values shall be assumed by the server.

• Note 2: EXLAP versions before 1.3 had the optional attribute notification with the values onUpdate, never (default) and onceAvailable. EXLAP 1.3 services will always deliver updates of subscribed data objects, which follow the onUpdate behaviour. New service server implementations may support the old notification attribute and set the interval on their behalf to 60000 if they do receive a notification="never" or notification= "onceAvailable" in subscribe requests to mimic the old behavior to a certain degree.

Format for a <Subscribe/> request:

<Req> <Subscribe url="url" {ival="[milliseconds:xsd:nonNegativeInteger(0)]"} {content ="[true|false]"} {timeStamp ="[true|false]"}/> </Req> Request attributes: Attribute Description

url _{The url of the data object to be subscribed.}

ival _{Optional attribute to specify the minimal interval in milliseconds (ms)} between an update of a data object sent by the server (i.e. sending of two subsequent <Dat/> messages for the same url) in a

xsd:nonNegativeInteger format.

• Note 1: An ival with the value of "0" disables any throttling of updates, which shall also be the default value, if this optional parameter is not supplied.

• Note 2: An ival shall only apply for data objects with a “dynamic” characteristic (see section 3.5.11 and 4.3). If applied to data objects with a characteristic of “event” or “static” the ival attribute shall be ignored.

• Application note: The motivation behind this option is to slow down the rate in which updates of data objects are sent to the client, since not all clients might be able or might be interested to process every change of the content.

<Req id="56567">

<Subscribe url="EngineSpeed" ival="200"/> </Req>

content _{Optional attribute to specify if data shall be sent in the body of an <Dat/>} message in case of a data object update, with a default value of "true". In case no data shall be sent in the body of an <Dat/> message, the attribute value must be "false". The empty <Dat/> message will signal the client that value of the data object specified by "url" has changed and can be retrieved with a <Get/> command from the server.

• Note: This mechanism is intended for complex objects with many This work is licensed under the Creative Commons Namensnennung-Weitergabe unter gleichen

members, so that the application logic at the client can decide when the data is really required and should be transferred (i.e. via <Get/> command).

<Req id="56567">

<Subscribe url="EngineSpeed" content="false"/> </Req>

Results in the following <Dat/> for every change in EngineSpeed:

<Dat url="EngineSpeed"/>

timeStamp _{Optional and not mandatory to implement attribute to denote the date/time} the <Dat/> message was produced at the server, with default value of "false". To enable the time stamping the attribute value must be “true”. • Note 1: If the generation of time stamps is not supported by the server,

this field shall be ignored by the server if present in a client request. To check if time stamping is supported, the client should use the information replied by the <Protocol/> command, as described in section 3.3.4.

• Note 2: The intention behind this option is that the client can timely relate the received data object updates in case of congestions on the transport layer (i.e. for logging applications, etc.).

<Req id="56567">

<Subscribe url="EngineSpeed" timeStamp="true"/> </Req>

Results in the following <Dat/>:

<Dat url="EngineSpeed"

timestamp="2012-09-13T10:46:23.155+00:00"> <Abs "EngineSpeed" val="3223.2"/>

</Dat> Example for an object subscription:

<Req id="56567">

<Subscribe url="EngineSpeed"/> </Req>

Reply from the server to acknowledge the <Subscribe/> command:

<Rsp {id="nr"} {status="[ok|error|internalError|syntaxError| noMatchingUrl| subscriptionLimitReached| accessViolation]"} {msg="text"}/> Response attributes and elements:

Attribute Description

status _{Optional attribute that returns the processing status of the request. The ok and} error status values apply as described in section 3.3.3.

• noMatchingUrl: The server shall return this status code if no data object in the active configuration of the server matches the given url. Data objects that are not accessible, due to a missing authorization (see <Authenticate/> command) are treated as not present.

• subscriptionLimitReached: The service server shall return this status code to signal that it cannot process any more simultaneous subscriptions

(e.g. CPU/memory limitation in the server or limit in the servers implementation).

• accessViolation: The server shall return this status code to signal the client, that the given url is valid, but the url can't be subscribed (i.e. read). This is the case when the url belongs to a function.

<Rsp status="ok" id="56567"/>

<Rsp status="noMatchingUrl" id="56568"/>