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.
Example 14. Observe example
<flow name="mule-coap-observe-example"> <coap-client:observe config-ref="my_CoAP_Client" path="/obs" /> <logger level="INFO" /> <byte-array-to-string-transformer /> <logger message="Got update from server: #[payload]" level="INFO" /> ... </flow>
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.
Example 15. Start observe example
<flow name="start_observe_example"> ... <coap-client:start-observe config-ref="my_CoAP_Client" path="/obs-pumping" responseHandler="my_handler"/> ... </flow>
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.
Example 16. Stop observe example
<flow name="stop_observe_example"> ... <coap-client:stop-observe config-ref="my_CoAP_Client" path="/obs-pumping"/> ... </flow>
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.
Example 17. Resource changed example
<flow name="list_observation_example"> ... <coap-client:list-observations config-ref="my_CoAP_Client"/> <foreach> <logger message="active observation uri: #[payload]" level="INFO"/> </foreach> ... </flow>