Observing CoAP resources

The CoAP protocol has provisions to notify clients of changes in CoAP resources. Clients can request CoAP servers to be notified. By observing a resource this way, clients keep up to date on the resources state. The CoAP server usually sets the max_age option in notifications it sends to clients, defining the period of time the notified state of the resource remains valid. Within this period new notifications should be received.

The CoapClient Connector provides two ways of observing a resource. The first is a static observe where a resource is permanently observed during the runtime of the Mule-flow. The second is a dynamic observe mechanism. Here observing is started and stopped explicitly by a Mule-flow. Specific message processors and message-sources are available for these two observe methods, described in the sections below.

The message-source <coap-client:observe/> observes a resource during the runtime of the Mule-flow. The message-source issues an observe request to the CoAP server. The response and all following notifications received are delivered to the Mule-flow that processes these as Mule-messages. The Mule-message payload is a byte array containing the CoAP payload. The response or notification details and options are passed as inbound-properties of the Mule-message. A complete list of message properties can be found in the section called “Message Properties”.

When the response or notification from the server reports failure or times out, a Mule-message is passed to the flow as well. This way the flow can take appropriate action on failure. Also the max_age on the CoAP notifications are monitored. When no responses or notifications are received in time, the observe relation with the server is reestablished by issuing a renewed observation-request to the server.

Mule-flows can dynamically start the observation of a CoAP resource. The message-processor <coap-client:start-observe/> sends an observe-request to the CoAP server for the resource to be observed. Like asynchronous requests, the handling is delegated to a handler, which must exist. See the section called “Handle Response” how to configure a response-handler.

The observation is monitored in the same way as the static observe does: upon failure the observe relation with the server will be reinitialised.

For a specific resource uri the observation can exist only once. The attempt to start an observation a second time will replace the first observation.. When an observation is stopped using the <coap-client:stop-observe/> message-processor, it can be started again.

When observation of a CoAP resource is started using the message-processor <coap-client:start-observe/>, this observation can be stopped by a flow using the <coap-client:stop-observe/> message-processor. It will send an explicit cancel request for the resource to the CoAP server. Stopping an observation that hasn't been started will be ignored silently. The resource-uri must be exactly the same as the uri used to start the observation, including host, port, path and query parameters.

Mule-flows can establish which dynamic observations are active. The message-processor <coap-client:list-observations/> returns a collection of strings containing the uri of every active observation.