Subscribing to Updates/Events

RTUS currently support subscribing to updates/events via Server-Sent Events (SSE).

Please refer to the following for more information on SSE: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events

Receiving events from RTUS

Creating an EventSource instance

To open a connection to the RTUS to begin receiving events from it, create a new EventSource object with the URL to the RTUS SEH endpoints. For example:

const evtSource = new EventSource("http://rtus-seh.127.0.0.1.nip.io/tenants/123456/maps/gisMap", {
  withCredentials: true,
});

The withCredentials is set to true indicating that CORS should be set to include credentials. This is necessary as your Web App will different URL (origin) from RTUS and browser will not include credential, include cookies, to be sent to RTUS if this attribute is set to true.

For Map, it is possible to ask RTUS to send all key-value pairs available in the Map during initial connection. To do that, simply add init=true as query parameter in the URL. For example:

http://rtus-seh.127.0.0.1.nip.io/tenants/123456/maps/gisMap?init=true

init=true is also available for User Value Map. However, as you can only subscribe to update for specific user (key), the init=true will only return value for that user if exist.

note

The initial value will be send as a message without event field.

For Topic, it is possible to request RTUS to continue sending next event starting from specified last event id, instead of only new event from the point of subscribing. To request to start receive event from specific last event id, simply add the last event id as the query parameter. For example:

http://rtus-seh.127.0.0.1.nip.io/tenants/123456/topics/myTopic?lastEventId=5

Listening for Map and User Value Map Updates

Messages sent from RTUS for Map or User Value Map are sent as custom events with specific name.

The list of named events is:

• Added : when new key-value pair is added to the Map
• Removed : when key-value pair is removed from the Map
• Updated : when key-value pair in the Map is been updated
• Map Cleared : when the Map is being cleared, i.e., all key-value pairs removed from Map

To received message events, attach Event Listener for the required name event. For example:

evtSource.addEventListener("Added", (event) => {
	const value = event.data;
	…  
});

This code will be called whenever a new key-value pair is added to the subscribing Map. The new value been added can be obtained from event.data.

To receive initial data, attach a handler for the message event:

evtSource.onmessage = (event) => {
	const value = event.data;
	…
 };

Listening for Topic Events

Messages sent from RTUS for Topic don't have an event field and are received as message events.

To receive message events, attach a handler for the message event:

evtSource.onmessage = (event) => {
	const value = event.data;
	const id = event.id;
	…
 };

This code listens for incoming message events and retrieve the data from event.data and id from event.id.

Error Handling

When problems occur (such as a network timeout or issues pertaining to access control), an error event is generated. You can take action on this programmatically by implementing the onerror callback on the EventSource object:

evtSource.onerror = (err) => {
  console.error("EventSource failed:", err);
};

If the Map, User Value Map, and Topic are configured to be protected (see Security for more info), you will receive error when you try to connect with invalid access token or expired access token. In addition, established connection will timeout when the access token expires.