public interface Messaging extends Feature, SendOptions.Builder.Factory
other clients
can send
messages to be received using this feature.
Messaging is distinct from the publish/subscribe Topics
feature which
provides streams of topic updates.
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 provides the ability to:
Sent messages are delivered to a message handler registered with the server for that topic path. If there is no registered message handler, the message is discarded and an error is dispatched to the session error handler.
streams
to receive messages on topic paths
A client can listen to messages for a selection of topics by
adding
one or more
Messaging.MessageStream
implementations. The mapping of topic selectors to
message streams is maintained locally in the client process. Any number of
message streams for inbound messages can be added on various topic selectors.
If a message is received on a topic path that matches with no message
streams, it is passed to any fallback
message streams
that have been registered.
A typical use case for messaging is a form of request/response paradigm where a message is sent and then a reply is returned. In this case it is important to set up suitable message streams for receiving messages before sending any messages.
Streams receive an onClose
callback when
unregistered and an onError
callback if the
session is closed).
SEND_TO_MESSAGE_HANDLER
permission for the topic paths to which it sends messages. If a client sends
messages to a topic path for which it does not have permission, the message
is discarded by the server.
session
as follows:
Messaging messaging = session.feature(Messaging.class);
Modifier and Type | Interface and Description |
---|---|
static interface |
Messaging.MessageStream
Stream interface that may be registered to receive messages from this
feature.
|
static interface |
Messaging.SendCallback
Callback interface for success or failure notifications from send
operations.
|
static interface |
Messaging.SendContextCallback<C>
Contextual callback interface for success or failure notifications from
send operations.
|
Modifier and Type | Method and Description |
---|---|
void |
addFallbackMessageStream(Messaging.MessageStream stream)
Add a fallback message stream.
|
void |
addMessageStream(String topics,
Messaging.MessageStream stream)
Add a message stream for messages received from the server on topics that
match the given
TopicSelector expression. |
void |
addMessageStream(TopicSelector topics,
Messaging.MessageStream stream)
Adds a message stream for messages received from the server on topics
that match a given
TopicSelector . |
Set<Messaging.MessageStream> |
getStreamsForTopic(String topicPath)
Returns the set of message streams that would be notified for a specified
topic path.
|
void |
removeMessageStream(Messaging.MessageStream stream)
Remove a message stream.
|
<C> void |
send(String topicPath,
Bytes message,
C context,
Messaging.SendContextCallback<C> callback)
Send a message.
|
void |
send(String topicPath,
Bytes message,
Messaging.SendCallback callback)
Send a message.
|
<C> void |
send(String topicPath,
Bytes message,
SendOptions options,
C context,
Messaging.SendContextCallback<C> callback)
Send a message.
|
void |
send(String topicPath,
Bytes message,
SendOptions options,
Messaging.SendCallback callback)
Send a message.
|
<C> void |
send(String topicPath,
CharSequence message,
C context,
Messaging.SendContextCallback<C> callback)
Send a message.
|
void |
send(String topicPath,
CharSequence message,
Messaging.SendCallback callback)
Send a message.
|
getSession
sendOptionsBuilder
void send(String topicPath, CharSequence message, Messaging.SendCallback callback) throws SessionClosedException, IllegalArgumentException
This is equivalent to calling
send(String, Bytes, SendOptions, SendCallback)
with character
content and no send options.
topicPath
- the path to send tomessage
- the message to sendcallback
- the callback to receive operation status notificationsIllegalArgumentException
- if topicPath
is null,
message
is null, or callback
is nullSessionClosedException
- if the session is closedvoid send(String topicPath, Bytes message, Messaging.SendCallback callback) throws SessionClosedException, IllegalArgumentException
This is equivalent to calling
send(String, Bytes, SendOptions, SendCallback)
with no send
options.
topicPath
- the path to send tomessage
- 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 topicPath
is null,
message
is null, or callback
is nullSessionClosedException
- if the session is closedvoid send(String topicPath, Bytes message, SendOptions options, Messaging.SendCallback callback) throws SessionClosedException, IllegalArgumentException
This message will be routed to any appropriately registered control handlers for the topic path.
topicPath
- the path of the topic to send tomessage
- the message to send. This can be any subtype of
Bytes
, for example Content
, Binary
or
JSON
.options
- for sendingcallback
- the callback to receive operation status notificationsIllegalArgumentException
- if topicPath
is null,
message
is null, or callback
is nullSessionClosedException
- if the session is closed<C> void send(String topicPath, CharSequence message, C context, Messaging.SendContextCallback<C> callback) throws SessionClosedException, IllegalArgumentException
This is equivalent to calling
send(String, Bytes, SendOptions, Object, SendContextCallback)
with character content and no send options.
C
- context object typetopicPath
- the path to send tomessage
- the message to sendcontext
- context passed to the callback with the reply to allow
requests and replies to be correlated. The caller may use any
convenient object reference, including null
callback
- the callback to receive operation status notificationsIllegalArgumentException
- if topicPath
is null,
message
is null, or callback
is nullSessionClosedException
- if the session is closed<C> void send(String topicPath, Bytes message, C context, Messaging.SendContextCallback<C> callback) throws SessionClosedException, IllegalArgumentException
This is equivalent to calling
send(String, Bytes, SendOptions, Object, SendContextCallback)
with no send options.
C
- context object typetopicPath
- the path to send tomessage
- the message to send. This can be any subtype of
Bytes
, for example Content
, Binary
or
JSON
.context
- context passed to the callback with the reply to allow
requests and replies to be correlated. The caller may use any
convenient object reference, including null
callback
- the callback to receive operation status notificationsIllegalArgumentException
- if topicPath
is null,
message
is null, or callback
is nullSessionClosedException
- if the session is closed<C> void send(String topicPath, Bytes message, SendOptions options, C context, Messaging.SendContextCallback<C> callback) throws SessionClosedException, IllegalArgumentException
The message will be routed to an appropriately registered control handler for the topic path.
C
- context object typetopicPath
- the path to send tomessage
- the message to send. This can be any subtype of
Bytes
, for example Content
, Binary
or
JSON
.options
- for sendingcontext
- a context object passed to the callback with the reply to
allow requests and replies to be correlated. The caller may use
any convenient object reference, including null
callback
- the callback to receive operation status notificationsIllegalArgumentException
- if topicPath
is null,
message
is null, or callback
is nullSessionClosedException
- if the session is closedvoid addMessageStream(TopicSelector topics, Messaging.MessageStream stream) throws IllegalArgumentException, SessionClosedException
TopicSelector
.
A message stream may be registered against any number of selectors.
When a message is received, it will be passed to each message stream that
matches the message's topic path. If there is no matching topic stream,
the fallback message streams
will be
called instead.
topics
- selector of one or more topicsstream
- the stream to addIllegalArgumentException
- if either topics
or
stream
are nullSessionClosedException
- if the session is closedvoid addMessageStream(String topics, Messaging.MessageStream stream) throws IllegalArgumentException, SessionClosedException
TopicSelector
expression.
This is equivalent to calling
addMessageStream(TopicSelector, MessageStream)
with a selector
parsed from the given String
expression.
topics
- as a TopicSelector
expressionstream
- the message stream to addIllegalArgumentException
- if either topics
or
stream
is null, or topics
is not a valid selector
expressionSessionClosedException
- if the session is closedvoid addFallbackMessageStream(Messaging.MessageStream stream) throws SessionClosedException
When a message is received from the server, it will be passed on to all
message streams that have been added
with
matching selectors. If no message stream is registered with a matching
selector, the fallback message streams that have been registered using
this method will be called instead.
Zero, one, or many fallback message streams can be set. If there is no
fallback message stream, messages that match no other
Messaging.MessageStream
will be discarded.
Adding the same message stream (as determined by
equals
) more than once has no effect.
stream
- the message stream to add as a fallback streamIllegalArgumentException
- if stream
is nullSessionClosedException
- if the session is closedvoid removeMessageStream(Messaging.MessageStream stream) throws SessionClosedException, IllegalArgumentException
More formally, this method removes all message streams that compare equal
to stream
, regardless of the topic selector for which they are
registered. It will also remove any fallback stream equal to
stream
. If there are no such message streams, no changes are
made.
stream
- the message stream to removeIllegalArgumentException
- if stream
is nullSessionClosedException
- if the session is closedSet<Messaging.MessageStream> getStreamsForTopic(String topicPath)
topicPath
- a valid topic pathIllegalArgumentException
- if topicPath
is nullCopyright © 2016 Push Technology Ltd. All Rights Reserved.