Sending messages to sessions

Required permissions: view_session, send_to_session

A client session can send a message to any known client session on any topic path, regardless of whether a topic is bound to that topic path. The messages are delivered to other client sessions through the Messaging feature or through the topic listener mechanism.

The client requires the session identifier of the client session it is sending to. Use the ClientControl feature to get the identifiers for connected client sessions. A client session can also send messages back to client sessions from which it receives messages through a message handler.

The body of the message that is sent is represented as bytes. Any of the builder features can be used to build a message as content, JSON, or binary. With messaging you can also send an empty message.

Filtering message recipients using session properties

Required permissions: view_session

When sending a message, a client session can specify a filter for the recipients of that message. The filter is a query expression on the values of session properties.

The client session defines a filter and sends a message on a topic path with the filter associated. The Diffusion server evaluates the query and sends the message on to connected client sessions whose session properties match the filter.

Registering message handlers

Required permissions: register_handler

A client session can add a message handler for any branch of the topic tree. This handler receives messages sent from client sessions on any topic in that branch unless overridden by a handler registered for a more specific branch.

Each client session can register only a single handler for any branch in the topic tree. To change the handler for a particular branch, the previous handler must be closed.

A message received by a message handler comprises content and message context which can include headers. The content can be empty. The client interprets the content of messages. If a topic is bound to the topic path that the message is sent on, message content is not required to match the content definition of that topic.

Requesting session properties with messages

Required permissions: register_handler,view_session

When registering a message handler, a client can specify session properties that it is interested in receiving with the handled messages.

Messages received by this message handler include the current values of the requested session properties for the client session that sent the message.

The message handler can request both fixed properties and user-defined properties of the session.