public interface MessagingControl extends Feature, SendOptions.Builder.Factory
A 'message' comprises some Content
and/or some headers and may be
sent with a specified priority.
Messages are sent and received for a particular topic path. The path provides a hierarchical context for the recipient. A topic with the path need not exist on the server; if one does exist, it is unaffected by messaging. An application can use the topic path to associate messages with topics, or an arbitrary path can be chosen. The path is also used for access control.
This feature can also be used to register handlers to receive messages sent from other clients. Different handlers may be registered to handle messages received on paths in different parts of the topic tree. Messages received from clients are delivered to the handler registered for the most specific topic path. If there multiple handlers are registered with the same path, a single one is chosen. If there are no matching handlers, the message is discarded.
A message sent directly to another session will be discarded if the receiving session is no longer connected or does not have a stream that matches the message's topic path - an error will also be dispatched to the sending session error handler in this case.
When registering handlers to receive messages it is also possible to indicate
that certain session properties (see Session
for a full description
of session properties) should be delivered with each message from a client
session. The current values of the named properties for the originating
session will be delivered within the ReceiveContext
delivered with
the message.
A typical use case for messaging is a form of request/response paradigm where a client sends a message to a path and it is delivered to a suitable handler which then sends a response to the originating client. Similarly, messages may be sent to clients to which responses are expected, in which case it is important to set up suitable handlers for the response before sending any messages.
Messages may also be sent using 'filters' (see Session
for a full
description of session filters), where the message will be delivered to all
sessions that satisfy a particular filter expression.
SEND_TO_SESSION
permission for
specified topic paths.
In order to add a message handler the control client session needs to have
REGISTER_HANDLER
permissions and if
registering to receive session property values it must also have
VIEW_SESSION
permissions.
session
as follows:
MessagingControl messagingControl = session.feature(MessagingControl.class);
Modifier and Type | Interface and Description |
---|---|
static interface |
MessagingControl.MessageHandler
Handler interface for receiving messages from clients, with associated
content and other optional information.
|
static interface |
MessagingControl.SendCallback
Callback interface for send operation notifications.
|
static interface |
MessagingControl.SendContextCallback<C>
Contextual callback interface for send operation notifications.
|
static interface |
MessagingControl.SendToFilterCallback
Callback interface for filtered send operation notifications.
|
static interface |
MessagingControl.SendToFilterContextCallback<C>
Callback interface for filtered send operation notifications that have an
associated context.
|
Modifier and Type | Method and Description |
---|---|
void |
addMessageHandler(String topicPath,
MessagingControl.MessageHandler handler,
String... sessionProperties)
Register a message handler to handle messages received from other client
sessions for a branch of the topic tree.
|
<C> void |
send(SessionId sessionId,
String topicPath,
Bytes message,
C context,
MessagingControl.SendContextCallback<C> callback)
Send a message to a session via a specific topic.
|
void |
send(SessionId sessionId,
String topicPath,
Bytes message,
MessagingControl.SendCallback callback)
Send a message to a session via a specific topic.
|
<C> void |
send(SessionId sessionId,
String topicPath,
Bytes message,
SendOptions options,
C context,
MessagingControl.SendContextCallback<C> callback)
Send message to a session via a specific topic.
|
void |
send(SessionId sessionId,
String topicPath,
Bytes message,
SendOptions options,
MessagingControl.SendCallback callback)
Send a message to a session via a specific topic.
|
<C> void |
send(SessionId sessionId,
String topicPath,
CharSequence message,
C context,
MessagingControl.SendContextCallback<C> callback)
Send message to a session via a specific topic.
|
void |
send(SessionId sessionId,
String topicPath,
CharSequence message,
MessagingControl.SendCallback callback)
Send a message to a session via a specific topic.
|
<C> void |
sendToFilter(String filter,
String topicPath,
Bytes message,
C context,
MessagingControl.SendToFilterContextCallback<C> callback)
Send a message to all sessions that satisfy a given session filter.
|
void |
sendToFilter(String filter,
String topicPath,
Bytes message,
MessagingControl.SendToFilterCallback callback)
Send a message to all sessions that satisfy a given session filter.
|
<C> void |
sendToFilter(String filter,
String topicPath,
Bytes message,
SendOptions options,
C context,
MessagingControl.SendToFilterContextCallback<C> callback)
Send a message to all sessions that satisfy a given session filter.
|
void |
sendToFilter(String filter,
String topicPath,
Bytes message,
SendOptions options,
MessagingControl.SendToFilterCallback callback)
Send a message to all sessions that satisfy a given session filter.
|
<C> void |
sendToFilter(String filter,
String topicPath,
CharSequence message,
C context,
MessagingControl.SendToFilterContextCallback<C> callback)
Send a message to all sessions that satisfy a given session filter.
|
void |
sendToFilter(String filter,
String topicPath,
CharSequence message,
MessagingControl.SendToFilterCallback callback)
Send a message to all sessions that satisfy a given session filter.
|
getSession
sendOptionsBuilder
void send(SessionId sessionId, String topicPath, Bytes message, SendOptions options, MessagingControl.SendCallback callback) throws IllegalArgumentException, SessionClosedException
sessionId
- identifies the session to which the message will be senttopicPath
- the topic path that the message is to be associated withmessage
- the message to send. This can be any subtype of
Bytes
, for example Content
, Binary
or
JSON
.options
- message options, including headers and prioritycallback
- the callback to receive operation status notificationsIllegalArgumentException
- if any parameter is nullSessionClosedException
- if the local session is closedvoid send(SessionId sessionId, String topicPath, Bytes message, MessagingControl.SendCallback callback) throws IllegalArgumentException, SessionClosedException
This is equivalent to calling
send(SessionId, String, Bytes, SendOptions, SendCallback)
with
default options
.
sessionId
- identifies the session to send the message totopicPath
- the topic path that the message is to be associated withmessage
- the message to send. This can be any subtype of
Bytes
, for example Content
, Binary
or
JSON
.callback
- the callback to receive operation status notificationsIllegalArgumentException
- if any parameter is nullSessionClosedException
- if the local session is closedvoid send(SessionId sessionId, String topicPath, CharSequence message, MessagingControl.SendCallback callback) throws IllegalArgumentException, SessionClosedException
This is equivalent to calling
send(SessionId, String, Bytes, SendCallback)
with character
content.
sessionId
- identifies the session to send the message totopicPath
- the topic path that the message is to be associated withmessage
- the message to sendcallback
- the callback to receive operation status notificationsIllegalArgumentException
- if any parameter is nullSessionClosedException
- if the local session is closed<C> void send(SessionId sessionId, String topicPath, Bytes message, SendOptions options, C context, MessagingControl.SendContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
C
- the context typesessionId
- identifies the session to which the message will be senttopicPath
- the topic path that the message is to be associated withmessage
- the message to send. This can be any subtype of
Bytes
, for example Content
, Binary
or
JSON
.options
- message options, including headers and prioritycontext
- the context to pass to the callback. This can be null.callback
- the callback to receive operation status notificationsIllegalArgumentException
- if sessionId
, topicPath
,
message
, options
, or callback
is nullSessionClosedException
- if the local session is closed<C> void send(SessionId sessionId, String topicPath, Bytes message, C context, MessagingControl.SendContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
This is equivalent to calling
send(SessionId, String, Bytes, SendOptions, Object, SendContextCallback)
with default options
.
C
- the context typesessionId
- identifies the session to send the message totopicPath
- the topic path that the message is to be associated withmessage
- the message to send. This can be any subtype of
Bytes
, for example Content
, Binary
or
JSON
.context
- the context to pass to the callback. This can be null.callback
- the callback to receive operation status notificationsIllegalArgumentException
- if sessionId
, topicPath
,
message
or callback
is nullSessionClosedException
- if the local session is closed<C> void send(SessionId sessionId, String topicPath, CharSequence message, C context, MessagingControl.SendContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
This is equivalent to calling
send(SessionId, String, Bytes, SendOptions, Object, SendContextCallback)
with character content and default options
.
C
- the context typesessionId
- identifies the session to send the message totopicPath
- the topic path that the message is to be associated withmessage
- the message to sendcontext
- the context to pass to the callbackcallback
- the callback to receive operation status notificationsIllegalArgumentException
- if sessionId
, topicPath
,
message
or callback
is nullSessionClosedException
- if the local session is closedvoid addMessageHandler(String topicPath, MessagingControl.MessageHandler handler, String... sessionProperties) throws IllegalArgumentException, SessionClosedException
The handler will be invoked for topics below the specified path to which
messages have been sent. This will only receive messages sent from a
client (e.g. by one of the send methods in the Topics
feature)
and not any topic updates.
Each control session may register a single handler for a branch (See
onActive
).
When the handler is no longer required, it may be closed using
RegisteredHandler.close()
. In order to change the handler for a
particular branch the previous handler must first be closed.
topicPath
- identifies a branch in the topic treehandler
- specifies the handler for all messages sent on topics
beneath the specified branch (unless overridden by a handler
registered against a more specific branch)sessionProperties
- a list of required property keys. See
Session
for a full list of available fixed property keys.
To request no properties supply an empty list. To request all
fixed properties include Session.ALL_FIXED_PROPERTIES
as a
key. In this case any other fixed property keys would be ignored.
To request all user properties include
Session.ALL_USER_PROPERTIES
as a key. In this case any
other user properties are ignored.IllegalArgumentException
- if either topicPath
or
handler
is nullSessionClosedException
- if session is closedvoid sendToFilter(String filter, String topicPath, Bytes message, SendOptions options, MessagingControl.SendToFilterCallback callback) throws IllegalArgumentException, SessionClosedException
See Session
for a full description of filter expressions.
filter
- the session filter expressiontopicPath
- the topic path that the message is to be associated withmessage
- the message to send. This can be any subtype of
Bytes
, for example Content
, Binary
or
JSON
.options
- message options, including headers and prioritycallback
- the callback to receive operation status notificationsIllegalArgumentException
- if any parameter is nullSessionClosedException
- if the local session is closedvoid sendToFilter(String filter, String topicPath, Bytes message, MessagingControl.SendToFilterCallback callback) throws IllegalArgumentException, SessionClosedException
This is equivalent to calling
sendToFilter(String, String, Bytes, SendOptions, SendToFilterCallback)
with default options
.
filter
- the session filter expressiontopicPath
- the topic path that the message is to be associated withmessage
- the message to send. This can be any subtype of
Bytes
, for example Content
, Binary
or
JSON
.callback
- the callback to receive operation status notificationsIllegalArgumentException
- if any parameter is nullSessionClosedException
- if the local session is closedvoid sendToFilter(String filter, String topicPath, CharSequence message, MessagingControl.SendToFilterCallback callback) throws IllegalArgumentException, SessionClosedException
This is equivalent to calling
sendToFilter(String, String, Bytes, SendOptions, SendToFilterCallback)
with character content and default options
.
filter
- the session filter expressiontopicPath
- the topic path that the message is to be associated withmessage
- the message to sendcallback
- the callback to receive operation status notificationsIllegalArgumentException
- if any parameter is nullSessionClosedException
- if the local session is closed<C> void sendToFilter(String filter, String topicPath, Bytes message, SendOptions options, C context, MessagingControl.SendToFilterContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
C
- the context typefilter
- the session filter expressiontopicPath
- the topic path that the message is to be associated withmessage
- the message to send. This can be any subtype of
Bytes
, for example Content
, Binary
or
JSON
.options
- message options, including headers and prioritycontext
- the context to pass to the callbackcallback
- the callback to receive operation status notificationsIllegalArgumentException
- if filter
, topicPath
,
message
, options
, or callback
is nullSessionClosedException
- if the local session is closed<C> void sendToFilter(String filter, String topicPath, Bytes message, C context, MessagingControl.SendToFilterContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
This is equivalent to calling
sendToFilter(String, String, Bytes, SendOptions, SendToFilterCallback)
with default options
.
C
- the context typefilter
- the session filtertopicPath
- the topic path that the message is to be associated withmessage
- the message to send. This can be any subtype of
Bytes
, for example Content
, Binary
or
JSON
.context
- the context to pass to the callbackcallback
- the callback to receive operation status notificationsIllegalArgumentException
- if filter
, topicPath
,
message
or callback
is nullSessionClosedException
- if the local session is closed<C> void sendToFilter(String filter, String topicPath, CharSequence message, C context, MessagingControl.SendToFilterContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
This is equivalent to calling
sendToFilter(String, String, Bytes, SendOptions, SendToFilterCallback)
with no options
.
C
- the context typefilter
- the session filter expressiontopicPath
- the topic path that the message is to be associated withmessage
- the message to sendcontext
- the context to pass to the callbackcallback
- the callback to receive operation status notificationsIllegalArgumentException
- if filter
, topicPath
,
message
or callback
is nullSessionClosedException
- if the local session is closedCopyright © 2016 Push Technology Ltd. All Rights Reserved.