public interface Topics extends Feature
Specifically, the feature provides the ability to:
A session can issue requests to subscribe to topics at any time, even if the
topics do not exist at the server. Topic selectors
are
used on subscription to match against topics at the server. The session will
become subscribed to any topics that exist at the server that match the
selector (unless they are already subscribed, or the session has insufficient
permission). The subscription request is also retained at the server so that
if any newly created topics match the selector, the session will then become
subscribed to it (unless a subsequent unsubscription cancels it).
Sessions receive notifications from topics that they are subscribed to via subscription streams (see below). When a session is subscribed to a topic, all matching streams will first receive a subscription notification that provides details about the topic. If the server has a value for the topic, the value will be delivered to the streams before any other notifications.
When a stream is added it will immediately be notified of any topics that are
already subscribed to that would be selected for the stream. For certain
topic types (JSON
, BINARY
,
and SINGLE_VALUE
) the subscription
notification will be followed by the latest known value. Other topic types do
not support the local caching of values. To ensure that a value is received
first, streams must be added before subscription.
A session can request unsubscription from a topic or topics at any time. This
is also specified using topic selectors. On unsubscription, matching streams
will be notified via the onUnsubscription
notification. This
notification will give the reason for unsubscription (e.g. by request of the
session, request of the server, or topic removal).
Subscriptions and unsubscriptions can occur for reasons other than requests
from the session. A session can be subscribed to or unsubscribed from a topic
by another session using the SubscriptionControl
feature, or by a
publisher component hosted on the server. The removal of a topic also
automatically causes unsubscription for subscribed sessions.
Subscription requests are subject to authorization checks. The session must
have SELECT_TOPIC
permission for the
topic selector used to subscribe. Matching topics will be further filtered to
those for which the session has READ_TOPIC
permission.
A session can listen to subscription events and updates for a selection of topics by adding one or more streams. A stream is registered using a selector which specifies the topics that the stream applies to. When an update is received for a topic then it will be routed to every stream that matches both the topic selector and the stream's data type. If more than one stream matches, all will receive the update; the order in which they are notified is not defined.
A stream can be added several times for different selectors. If the same
stream (determined by equals
) is registered for
several selectors that match an event, the stream will only be notified of
the event once. The mapping of topic selectors to streams is maintained
locally in the client process.
A stream will receive an
onClose
callback when unregistered and an
onError(SESSION_CLOSED)
callback if the session is closed.
It is also possible to add one or more fallback streams which will
receive updates that do not match any stream registered with a selector. This
is useful for default processing or simply to catch unprocessed updates. A
fallback stream can be added using addFallbackStream
or addFallbackTopicStream
.
Zero, one, or more fallback streams may be assigned. If no fallback stream is
specified, any updates that are not routed to any other stream will simply be
discarded.
There are two types of subscription stream, value streams and topic streams as outlined below:
A ValueStream
will receive values for matching topics as
and when updates are received from the server. Value streams are typed to a
specified value type and only values for topics that maintain locally cached
values matching the type will be routed to the stream. Delta updates from the
server are automatically applied to locally cached values so that the stream
always receives values.
This is the preferred stream type as it is the simplest to use; however it is not supported for all topic types. The following table shows how the value class specified when adding the stream maps to actual topic types that will be routed to the stream:
Value Type | Topic Types |
JSON |
JSON |
Binary |
BINARY |
Bytes |
SINGLE_VALUE JSON BINARY |
Content |
SINGLE_VALUE JSON BINARY |
One or more such stream implementations can be added using
addStream
.
TopicStream
will receive both
value and delta updates for all topic types.
The server initially sends the current value of a topic when a session
subscribes to the topic but after that, if it is more efficient to do so, the
server will just send the changes (deltas). This type of stream provides the
value and the deltas but relies upon the application to apply the deltas to a
session-maintained current value. A topic stream is therefore not as
convenient as a ValueStream
but is currently the only
option available for some topic types (such as TopicType.RECORD
).
One or more such stream implementations can be added using
addTopicStream
.
A session can issue a request to fetch the state of a topic or topics
(subject to authorization) at any time. Fetch requests use
topic selectors
to select the topics to fetch and
because such a request could result in the fetching of many topics, a
stream
type callback is used.
Topics.FetchStream.onFetchReply(String, Content)
will be called for each
selected topic that has a value.
Fetch requests are subject to authorization checks. The session must have
SELECT_TOPIC
permission for the topic
selector used to fetch. Matching topics will be further filtered to those for
which the session has READ_TOPIC
permission.
A session must have SELECT_TOPIC
permission for the path prefix of the topic selector used to
subscribe
or
fetch
. The topics that result from
a subscription or fetch request are further filtered using the
READ_TOPIC
permission.
The READ_TOPIC
permission is required to
retrieve the topic details
.
No access control restrictions are applied to
unsubscription
.
This feature can be obtained from a session
as follows:
Topics topics = session.feature(Topics.class);
Modifier and Type | Interface and Description |
---|---|
static interface |
Topics.CompletionCallback
Callback interface for success or failure notifications from subscription
and unsubscription operations.
|
static interface |
Topics.CompletionContextCallback<C>
Contextual callback interface for success or failure notifications from
subscription operations.
|
static interface |
Topics.FetchContextStream<C>
Contextual callback interface for fetch requests.
|
static interface |
Topics.FetchStream
Callback interface for fetch requests.
|
static interface |
Topics.SubscriberStream
Base subscriber stream interface.
|
static interface |
Topics.TopicDetailsCallback
Callback interface for replies to requests for topic details.
|
static interface |
Topics.TopicDetailsContextCallback<C>
Contextual callback interface for replies to requests for topic details.
|
static interface |
Topics.TopicStream
Generic stream interface that can be registered to receive topic
subscription, value and delta events.
|
static class |
Topics.UnsubscribeReason
The reason that an unsubscription occurred.
|
static interface |
Topics.ValueStream<V>
Stream interface that can be registered to receive subscription and value
events whenever an update is received from the server.
|
Modifier and Type | Method and Description |
---|---|
<V> void |
addFallbackStream(Class<V> valueClass,
Topics.ValueStream<V> stream)
Add a fallback value stream.
|
void |
addFallbackTopicStream(Topics.TopicStream stream)
Add a fallback topic stream.
|
<V> void |
addStream(String topics,
Class<V> valueClass,
Topics.ValueStream<V> stream)
Add a value stream to receive topic events for topics that match a given
TopicSelector expression and have a value type that matches a
specified type. |
<V> void |
addStream(TopicSelector topics,
Class<V> valueClass,
Topics.ValueStream<V> stream)
Add a value stream to receive topic events for topics that match a given
TopicSelector and have a value type that matches a specified
type. |
void |
addTopicStream(String topics,
Topics.TopicStream stream)
Add a topic stream to receive topic events for all topics that match a
given
TopicSelector expression. |
void |
addTopicStream(TopicSelector topics,
Topics.TopicStream stream)
Add a topic stream to receive topic events for all topics that match a
given
TopicSelector . |
<C> void |
fetch(String topics,
C context,
Topics.FetchContextStream<C> callback)
Fetch the current state of topics.
|
void |
fetch(String topics,
Topics.FetchStream callback)
Fetch the current state of topics.
|
<C> void |
fetch(TopicSelector topics,
C context,
Topics.FetchContextStream<C> callback)
Fetch the current state of topics.
|
void |
fetch(TopicSelector topics,
Topics.FetchStream callback)
Fetch the current state of topics.
|
<C> void |
getTopicDetails(String topicPath,
TopicDetails.Level level,
C context,
Topics.TopicDetailsContextCallback<C> callback)
Get the details of a given topic.
|
void |
getTopicDetails(String topicPath,
TopicDetails.Level level,
Topics.TopicDetailsCallback callback)
Get the details of a given topic.
|
void |
removeStream(Stream stream)
Remove a stream.
|
void |
removeTopicStream(Topics.TopicStream stream)
Deprecated.
since 5.7 use
removeStream . |
<C> void |
subscribe(String topics,
C context,
Topics.CompletionContextCallback<C> callback)
Request subscription to topics.
|
void |
subscribe(String topics,
Topics.CompletionCallback callback)
Request subscription to topics.
|
<C> void |
subscribe(TopicSelector topics,
C context,
Topics.CompletionContextCallback<C> callback)
Request subscription to topics.
|
void |
subscribe(TopicSelector topics,
Topics.CompletionCallback callback)
Request subscription to topics.
|
<C> void |
unsubscribe(String topics,
C context,
Topics.CompletionContextCallback<C> callback)
Unsubscribe from topics.
|
void |
unsubscribe(String topics,
Topics.CompletionCallback callback)
Unsubscribe from topics.
|
<C> void |
unsubscribe(TopicSelector topics,
C context,
Topics.CompletionContextCallback<C> callback)
Unsubscribe from topics.
|
void |
unsubscribe(TopicSelector topics,
Topics.CompletionCallback callback)
Unsubscribe from topics.
|
getSession
void addTopicStream(TopicSelector topics, Topics.TopicStream stream) throws IllegalArgumentException, SessionClosedException
TopicSelector
.topics
- selector of one or more topicsstream
- the stream to addIllegalArgumentException
- if either topics
or
stream
is nullSessionClosedException
- if the session is closedvoid addTopicStream(String topics, Topics.TopicStream stream) throws IllegalArgumentException, SessionClosedException
TopicSelector
expression.
This is equivalent to calling
addTopicStream(TopicSelector, TopicStream)
with a selector
parsed from the given String
expression.
topics
- as a TopicSelector
expressionstream
- the topic stream to addIllegalArgumentException
- if either topics
or
stream
is null, or topics
is not a valid selector
expressionSessionClosedException
- if the session is closed<V> void addStream(TopicSelector topics, Class<V> valueClass, Topics.ValueStream<V> stream) throws IllegalArgumentException, SessionClosedException
TopicSelector
and have a value type that matches a specified
type.
See Topics
class documentation for full details of the use of
value streams.
V
- the value type classtopics
- selector of one or more topicsvalueClass
- the class of value that the stream is typed tostream
- the stream to addIllegalArgumentException
- if any parameter is null, or the
valueClass
is not supported.SessionClosedException
- if the session is closed<V> void addStream(String topics, Class<V> valueClass, Topics.ValueStream<V> stream) throws IllegalArgumentException, SessionClosedException
TopicSelector
expression and have a value type that matches a
specified type.
See Topics
class documentation for full details of the use of
value streams.
V
- the value type classtopics
- as a TopicSelector
expressionvalueClass
- the class of value that the stream is typed tostream
- the stream to addIllegalArgumentException
- if any parameter is null, or the
valueClass
is not supported.SessionClosedException
- if the session is closedvoid addFallbackTopicStream(Topics.TopicStream stream) throws SessionClosedException
See Topics
class documentation for full details regarding the use
of fallback streams.
stream
- the topic stream to add as a fallback streamIllegalArgumentException
- if stream
is nullSessionClosedException
- if the session is closed<V> void addFallbackStream(Class<V> valueClass, Topics.ValueStream<V> stream) throws IllegalArgumentException, SessionClosedException
See Topics
class documentation for full details regarding the use
of fallback streams.
valueClass
- the class of value that the stream is typed tostream
- the stream to addIllegalArgumentException
- if valueClass
or stream
is nullSessionClosedException
- if the session is closed@Deprecated void removeTopicStream(Topics.TopicStream stream) throws SessionClosedException, IllegalArgumentException
removeStream
.
More formally, this method removes all topic 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 topic streams, no changes are made.
stream
- the topic stream to removeIllegalArgumentException
- if stream
is nullSessionClosedException
- if the session is closedvoid removeStream(Stream stream) throws IllegalArgumentException, SessionClosedException
More formally, this method removes all 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 streams, no changes are made.
stream
- the value stream to removeIllegalArgumentException
- if either parameter is nullSessionClosedException
- if the session is closedvoid subscribe(TopicSelector topics, Topics.CompletionCallback callback) throws SessionClosedException, IllegalArgumentException
topics
- specifies of the topics to request subscription tocallback
- the callback object to receive status notifications for
this operationIllegalArgumentException
- if topics
or callback
is
nullSessionClosedException
- if the session is closedvoid subscribe(String topics, Topics.CompletionCallback callback) throws SessionClosedException, IllegalArgumentException
This is equivalent to calling
subscribe(TopicSelector, CompletionCallback)
with a selector
parsed using TopicSelectors.parse(String)
.
topics
- a TopicSelector
expression specifying the topics to
request subscription tocallback
- the callback object to receive status notifications for
this operationIllegalArgumentException
- if topics
or callback
is
null or topics
cannot be parsed as a TopicSelectorSessionClosedException
- if the session is closed<C> void subscribe(TopicSelector topics, C context, Topics.CompletionContextCallback<C> callback) throws SessionClosedException, IllegalArgumentException
C
- context object typetopics
- specifies of the topics to request subscription tocontext
- an object passed to the callback with the reply to allow
requests and replies to be correlated. The caller can use any
convenient object reference, including null
callback
- the callback object to receive status notifications for
this operationIllegalArgumentException
- if topics
or callback
is
nullSessionClosedException
- if the session is closed<C> void subscribe(String topics, C context, Topics.CompletionContextCallback<C> callback) throws SessionClosedException, IllegalArgumentException
This is equivalent to calling
subscribe(TopicSelector, Object, CompletionContextCallback)
with
a selector parsed using TopicSelectors.parse(String)
.
C
- context object typetopics
- a TopicSelector
expression specifying the topics to
request subscription tocontext
- an object passed to the callback with the reply to allow
requests and replies to be correlated. The caller can use any
convenient object reference, including null
callback
- the callback object to receive status notifications for
this operationIllegalArgumentException
- if topics
or callback
is
null or topics
cannot be parsed as a TopicSelectorSessionClosedException
- if the session is closedvoid unsubscribe(TopicSelector topics, Topics.CompletionCallback callback) throws SessionClosedException, IllegalArgumentException
This can be used at any time whilst connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests.
topics
- the topics to unsubscribe fromcallback
- the callback handler for status notifications of this
operationIllegalArgumentException
- if topics
or callback
is
nullSessionClosedException
- if the session is closedvoid unsubscribe(String topics, Topics.CompletionCallback callback) throws SessionClosedException, IllegalArgumentException
This is equivalent to calling
unsubscribe(TopicSelector, CompletionCallback)
with a selector
parsed using TopicSelectors.parse(String)
.
topics
- the topics to unsubscribe fromcallback
- the callback handler for status notifications of this
operationIllegalArgumentException
- if topics
or callback
is
null or topics
cannot be parsed as a selectorSessionClosedException
- if the session is closed<C> void unsubscribe(TopicSelector topics, C context, Topics.CompletionContextCallback<C> callback) throws SessionClosedException, IllegalArgumentException
This can be used at any time whilst connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests.
C
- context object typetopics
- the topics to unsubscribe fromcontext
- an object passed to the callback with the reply to allow
requests and replies to be correlated. The caller can use any
convenient object reference, including null
callback
- the callback handler for status notifications of this
operationIllegalArgumentException
- if topics
or callback
is
nullSessionClosedException
- if the session is closed<C> void unsubscribe(String topics, C context, Topics.CompletionContextCallback<C> callback) throws SessionClosedException, IllegalArgumentException
This is equivalent to calling
unsubscribe(TopicSelector, Object, CompletionContextCallback)
with a selector parsed using TopicSelectors.parse(String)
.
C
- context object typetopics
- the topics to unsubscribe fromcontext
- an object passed to the callback with the reply to allow
requests and replies to be correlated. The caller can use any
convenient object reference, including null
callback
- the callback handler for status notifications of this
operationIllegalArgumentException
- if topics
or callback
is
null or topics
cannot be parsed as a selectorSessionClosedException
- if the session is closedvoid fetch(TopicSelector topics, Topics.FetchStream callback) throws IllegalArgumentException, SessionClosedException
The stream callback's onFetchReply
method will be called for each topic that matches
topics
for which a fetch request can be satisfied, followed by
onClose
.
topics
- the topics to fetchcallback
- called with content for each matching topic that could be
fetchedIllegalArgumentException
- if topics
or callback
is
nullSessionClosedException
- if the session is closedvoid fetch(String topics, Topics.FetchStream callback) throws IllegalArgumentException, SessionClosedException
This is equivalent to calling fetch(TopicSelector, FetchStream)
with a selector parsed using TopicSelectors.parse(String)
.
topics
- the topics to fetch, specified as a selector expression
callback
- called with content for each matching topicIllegalArgumentException
- if topics
is invalid or null, or
callback
is nullSessionClosedException
- if the session is closed<C> void fetch(TopicSelector topics, C context, Topics.FetchContextStream<C> callback) throws IllegalArgumentException, SessionClosedException
The stream callback's
onFetchReply
method will be called for each topic that matches
topics
for which a fetch request can be satisfied, followed by
onClose
.
C
- context object typetopics
- the topics to fetchcontext
- an object passed to the callback with the reply to allow
requests and replies to be correlated. The caller can use any
convenient object reference, including null
callback
- called with content for each matching topicIllegalArgumentException
- if topics
or callback
is
nullSessionClosedException
- if the session is closed<C> void fetch(String topics, C context, Topics.FetchContextStream<C> callback) throws IllegalArgumentException, SessionClosedException
This is equivalent to calling
fetch(TopicSelector, Object, FetchContextStream)
with a selector
parsed using TopicSelectors.parse(String)
.
C
- context object typetopics
- the topics to fetch, specified as a selector expression
context
- an object passed to the callback with the reply to allow
requests and replies to be correlated. The caller can use any
convenient object reference, including null
callback
- called with content for each matching topicIllegalArgumentException
- if topics
is invalid or null, or
callback
is nullSessionClosedException
- if the session is closedvoid getTopicDetails(String topicPath, TopicDetails.Level level, Topics.TopicDetailsCallback callback) throws IllegalArgumentException, SessionClosedException
The onTopicDetails
callback method will be called with the result.
topicPath
- the full path of the topiclevel
- specifies the level of detail requiredcallback
- called with the requested detailsIllegalArgumentException
- if topicPath
, level
or
callback
is nullSessionClosedException
- if the session is closed<C> void getTopicDetails(String topicPath, TopicDetails.Level level, C context, Topics.TopicDetailsContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
The
onTopicDetails
callback method will be called with the result.
C
- context object typetopicPath
- the full path of the topiclevel
- specifies the level of detail requiredcontext
- passed to the callback with the reply to allow requests
and replies to be correlated. The caller can use any convenient
object reference, including null
callback
- called with the requested detailsIllegalArgumentException
- if topicPath
, level
or
callback
is nullSessionClosedException
- if the session is closedCopyright © 2016 Push Technology Ltd. All Rights Reserved.