@DefaultAnnotation({})

Package jmri.server.json.message

The JMRI JSON protocol message server. JMRI is capable of sending human readable messages, solicited or unsolicited, to JMRI JSON clients devices. Examples of such messages might status updates for a lengthy process that was initiated through a web service or changes in the status of a connection. This server provides mechanisms for subscribing to, and sending, such messages within the JSON streaming service. JSON HTTP clients are not supported.

This server subscribes a client for client-specific messages if the client key is included in the data element of a hello message or client message with a put or post method. A client can cancel its subscription by sending a client message with the client data key of the remove type. A single client can subscribe as many times as it wants to by sending different values for the client key each time (note that such a client will receive multiple messages for every message broadcast to all clients).

A client can request that JMRI create a client code on its behalf by sending a client message with a get method (no data object is required). If requesting a JMRI-generated code, JMRI provides an existing client-generated code, if one is already subscribed, or generates a UUID on behalf of the requester. JMRI will return the same UUID for a single connection until that UUID is subscription is canceled by the client.

Examples:

  • {"type": "client", "data": {"client": "42"}, "method": "put"} to subscribe
  • {"type": "client", "data": {"client": "42"}, "method": "delete"} to cancel a subscription
  • {"type": "client", "method": "get"} to request a JMRI-generated client identity

Messages sent by this server include the following properties in the JSON data object:

context
An JSON object, previously sent by the client as part of some other transaction to be included with the message so the client knows why it received the message. This is null if no context was sent by the client, or if the context sent was not a JSON object.
message
The message text.
type
One of JsonMessage.TYPE.INFO, JsonMessage.TYPE.SUCCESS, JsonMessage.TYPE.WARNING, or JsonMessage.TYPE.ERROR
locale
The message locale, which may differ from both the client's locale and the JMRI server's locale.