Long Poll Event Handlers

The JSON-RPC Long Poll Event Handlers provide means of subscribing to topics and retrieving events information through Long Polling.

JSON-RPC Remote Events Details

The URI for the JSON remote events is http(s)://<host>:<port>/remote/json-rpc. To subscribe for remote events a POST request must be made.

Such requests are being sent with a JSON object as body. After parsing the JSON object, a specific corresponding OSGi service handles those requests and sends back the corresponding events as an answer to the made HTTP POST request. There are two available OSGi services for remote events – with service.pids 'EA' and 'RE'.

There are two service.pids for the Remote Events mechanism:

•     EA –- it is the old identifier (Event Admin), used for backward compatibility. Supported methods are "EA/subscribe", "EA/unsubscribe", "EA/poll", and "EA/unsubscribeAll".
•     RE – the new identifier (Remote Exported), it is part of the remote.exported.methods property, which can include a star ( * ) for all methods, otherwise all method names have to be included. Supported methods are "RE/subscribe", "RE/unsubscribe", "RE/poll", and "RE/unsubscribeAll".

Below is provided an example of the JSON request :

{jsonrpc: "2.0", //current JSON-RPC version ,constant

id:0, //unused

method: "RE/subscribe", // <service.pid> / <method> , for example "EA/subscribe" can also be used

params: []} //parameters as an array

The JSON-RPC version is always 2.0, the ID is not important because its value is generated by the JSON-RPC. The method service.pid is always either 'RE' or 'EA'. The 'params' field contains the parameters of the method mentioned in the JSON object (in this case, subscribe).

An LDAP filter or several 'topic' parameters can be used to subscribe for different events, which is the usual practice. Multiple JSON Requests can also be made for this. This is not advisory, but possible.

{jsonrpc: "2.0", //current JSON-RPC version ,constant

id:0, //unused

method: "RE/subscribe", // <service.pid> / <method> , for example "EA/subscribe" can also be used

params: ["topic1","topic2","topic3"]} //or LDAP filter

A specific Remote Events Servlet is registered. It has active service tracking for the services with 'RE' and 'EA' service.pids. Depending on the JSON object content, it invokes the corresponding method described in the sent JSON object, while supplying the parameters given there. The method is called using a remote service invoker. The remote service invoker interface is implemented by the PolicyInvoker class. If there is no remote service invoker service present, the remote service is called directly.

Long Poll Events Security

The BOSCH IoT Gateway Software has to be started with a 'security' parameter for this to come in action.

The PolicyInvoker works in the following way (in the com.prosyst.mbs.webservices.jsonrpc.invoker.policy bundle):

• With this invoker, security is handled - the user is extracted from the HTTP session and using the Policy Admin it is checked if it has permissions to call the method.
• The invoker creates an AccessControlContext using the Policy Admin and invokes the remote method using a doPrivileged block, using this user; this way the permission checks consider the permissions of the user.

Note that this example is purely for informational purposes and it comes from another module, which is not part of the JSON-RPC Remote Events architecture.

Example: a HDM remote method, which lists all devices. The following checks are made:
    1.Whether permissions for the method are at all available.
    2.For each device individually - whether the caller can get the specific device

• The invoker associates the current thread with the user from the HTTP session using the ACCAdmin. It has a method getCurrentId(String securityId) - it associates it with this string.

Note that this example is purely for informational purposes and it comes from another module, which is not part of the JSON-RPC Remote Events architecture.

Whenever devices for HDM are listed for example, everything is in one thread. In the other case the ACC is saved and allows another thread to check permissions for it.
Technically, one thread initiates, and other threads asynchronously execute with the proper permissions.

Whenever someone wants to subscribe for JSON-RPC Remote Events, it registers an EventHandler interface implementation; this service creates a subscription and re-sends events stored in the EventAdmin service. A registration property of the EventHandler is this security ID property from the ACCAdmin service.

Whenever the EventAdmin is required to send an Event to this EventHandler, it checks whether the EventHandler has permissions to receive this event. It does that by getting the securityId from the EventHandler registration properties, gets the AccessControlContext from the ACCAdmin service,and calls checkPermission with it. If the checkPermission method returns 'false', the event is not received.

Required Bundles

To be able to use Long Polling Event Handlers the following bundles must be installed:

• com.prosyst.mbs.webservices.jsonrpc.handler.event.jar
• com.prosyst.mbs.webservices.jsonrpc.core.jar

For integration with the Policy Admin the following bundle is required:

• JSON-RPC Policy Admin Invoker Bundle - com.prosyst.mbs.webservices.jsonrpc.invoker.policy.jar

Target URL

The target JSON-RPC Long Poll use the following URL's:

• Using the Remote Events Application Handler
  • Subscribe:

    http://<osgi_host>:<port>/remote/json-rpc/RE/subscribe

  • Poll:

    http://<osgi_host>:<port>/remote/json-rpc/RE/poll

  • Long poll:

    http://<osgi_host>:<port>/remote/json-rpc/RE/longPoll

  • Unsubscribe:

    http://<osgi_host>:<port>/remote/json-rpc/RE/unsubscribe

The JSON-RPC Long Poll use the same port as the HTTP server.