public interface TopicControl extends Feature
1) Adding and removing topics.
2) Listening for requests to subscribe to (or fetch) topics that do not exist
thus allowing dynamic topic creation on demand.
3) Listening for topic events, such as the number of subscribers to a topic
changing from zero to greater than zero or from greater than zero to zero.
4) Flagging topics to be removed from the server when the client session
closes.
addTopicFromValue(String, Object, AddCallback)
method. The
topic type, metadata (if applicable) and initial value are derived from a
supplied value as described below:
Value Type | Topic Type | Metadata | Initial Value |
JSON |
JSON |
Not applicable | The supplied value. |
Binary |
BINARY |
Not applicable | The supplied value. |
Content built using RecordContentBuilder |
RECORD |
MContent derived from records and values in the content. Numeric
values will assume type MIntegerString . Numeric values containing a
'.' will assume type MDecimalString with a scale equal to the number
of digits after the decimal point and all other values will assume
MString . This means that if you intend a field to be a string you
cannot give it an initial value that can be parsed as a number.It is not possible to derive repeating records or fields from content, each record or field in the content will get a separate metadata definition. If you want to use repeating records or fields, build the details manually. |
The supplied content. |
Content not built using RecordContentBuilder |
SINGLE_VALUE |
MString |
The supplied content as a string. |
Integer, Long, Short, Byte, BigInteger, AtomicInteger, AtomicLong | SINGLE_VALUE |
MIntegerString |
derived from the string representation of the value supplied. |
BigDecimal | SINGLE_VALUE |
MDecimalString with scale from value |
derived from the string representation of the value supplied. Note that
when constructing a BigDecimal do not use the double constructor (e.g.
new BigDecimal(47.486) ) as this will lead to unexpected values and
scales due to the nature of floating point precision. The String constructor
(e.g. new BigDecimal("47.486") ) will give the expected result (i.e.
scale 3). |
Double, Float | SINGLE_VALUE |
MDecimalString with scale 2 |
Use of floating point numbers is not recommended but if supplied, the
number is converted to a decimal value with half
up rounding. |
Other | SINGLE_VALUE |
MString |
For all types other than those above the initial content is obtained from
the toString method of the supplied object. |
For example, a topic could be added as follows:
topicControl.addTopicFromValue("MyTopic", new BigDecimal("0.000"), addCallback);
The above call would create a single value topic with a scale 3 decimal value
initialized to "0.000".
Alternatively a single value string topic initialized to a zero length string could be added as follows:
topicControl.addTopicFromValue("MyTopic", "", addCallback);
The actual TopicDetails
used to create the topic will be returned.
These are generated by the call if required, or if there are already suitable
details from a previous call, they will have been used.
addTopic(String, TopicType, AddCallback)
specifying the type of
topic to create. This will create a topic of the specified type with default
properties. For example:
topicControl.addTopic("foo", TopicType.JSON, callback);
In some cases there may be a need to specify some additional properties. This
may be done using addTopic(String, TopicSpecification, AddCallback)
where the specification is created using newSpecification(TopicType)
. For example:
topicControl.addTopic(
"foo",
topicControl.newSpecification(TopicType.JSON).withProperty(TopicSpecification.PUBLISH_VALUES_ONLY, "true"),
callback);
Variants of these methods allow an initial value to be supplied for the
topic. If a topic is not given an initial value, some topic types will assume
a default initial value, whereas others may simply not have an initial value.
This method does not work for all topic types as some have complex
requirements which need to be specified using TopicDetails
.
record
topics would need to specify metadata. For such topics it is
necessary to supply topic details which fully describe the type of topic and
any other properties required for its creation. These details may be created
using a
builder
of the correct type. In order to create a builder of the correct
type it is necessary to supply the builder type to the
newDetailsBuilder(Class)
method. For example:
RecordTopicDetails.Builder builder = topicControl.newDetailsBuilder(RecordTopicDetails.Builder.class);
After setting properties as required on the builder, it can be used to build
immutable details
which can then be used to add topics.
For example:
TopicDetails details = builder.build();
topicControl.addTopic("foo", details, callback);
If many topics are to be created with the same definition, it is recommended
to use the same details instance as the feature is optimized to only transmit
the details to the server once in this situation.
A/B/foo
even though there are no topics with path A
or A/B
:
topicControl.addTopic("A/B/foo", TopicType.JSON, callback);
Similarly topics at path A
or A/B
can be created later.
Topics can be removed from any path without affecting the topics subordinate
to them in the topic tree using remove(java.lang.String, com.pushtechnology.diffusion.client.features.control.topics.TopicControl.RemovalCallback)
. However, by using the //
qualifier it is possible to also remove descendant topics (i.e remove topic
tree branches).
MODIFY_TOPIC
permission to the branch of
the topic tree being updated. If a session removes a topic (requiring
MODIFY_TOPIC
permission for the topic path), descendant topics will
also be removed regardless of the permissions at lower levels of the topic
tree.
To register a missing topic handler
the client session needs
REGISTER_HANDLER
permission.
session
as follows:
TopicControl topicControl = session.feature(TopicControl.class);
Modifier and Type | Interface and Description |
---|---|
static interface |
TopicControl.AddCallback
Callback interface for adding topics when no context is provided.
|
static interface |
TopicControl.AddContextCallback<C>
Contextual callback interface for adding topics.
|
static interface |
TopicControl.MissingTopicHandler
Handler called when a client session subscribes or fetches using a topic
selector that matches no topics.
|
static interface |
TopicControl.MissingTopicNotification
Notification that a session has made a request using a selector that does
not match any topics.
|
static interface |
TopicControl.RemovalCallback
Callback interface for
remove requests when
no context is used. |
static interface |
TopicControl.RemovalContextCallback<C>
Contextual callback interface for
remove requests. |
static interface |
TopicControl.RemoveCallback
Deprecated.
since 5.9 use of the
remove(String, RemovalCallback)
interface is preferred. |
static interface |
TopicControl.RemoveContextCallback<C>
Deprecated.
since 5.9 use of the
remove(String, Object, RemovalContextCallback)
interface is preferred. |
static interface |
TopicControl.TopicEventListener
Listener for topic events from the server.
|
Modifier and Type | Method and Description |
---|---|
void |
addMissingTopicHandler(String topicPath,
TopicControl.MissingTopicHandler handler)
Register a
TopicControl.MissingTopicHandler to handle requests for a branch of
the topic tree. |
<C> void |
addTopic(String topicPath,
TopicDetails details,
Bytes value,
C context,
TopicControl.AddContextCallback<C> callback)
Version of
addTopic(String, TopicDetails, Bytes, AddCallback)
that allows a user defined context to be provided. |
void |
addTopic(String topicPath,
TopicDetails details,
Bytes value,
TopicControl.AddCallback callback)
Send a request to the server to add a topic, specifying its initial
value.
|
<C> void |
addTopic(String topicPath,
TopicDetails details,
C context,
TopicControl.AddContextCallback<C> callback)
Version of
addTopic(String, TopicDetails, AddCallback) that
allows a user defined context to be provided. |
void |
addTopic(String topicPath,
TopicDetails details,
TopicControl.AddCallback callback)
Send a request to the server to add a topic.
|
<C> void |
addTopic(String topicPath,
TopicSpecification specification,
Bytes value,
C context,
TopicControl.AddContextCallback<C> callback)
Version of
addTopic(String, TopicSpecification, Bytes, AddCallback) that
allows a user defined context to be provided. |
void |
addTopic(String topicPath,
TopicSpecification specification,
Bytes value,
TopicControl.AddCallback callback)
Send a request to the server to add a topic, specifying its initial
value.
|
<C> void |
addTopic(String topicPath,
TopicSpecification specification,
C context,
TopicControl.AddContextCallback<C> callback)
Version of
addTopic(String, TopicSpecification, AddCallback)
that allows a user defined context to be provided. |
void |
addTopic(String topicPath,
TopicSpecification specification,
TopicControl.AddCallback callback)
Send a request to the server to add a topic.
|
<C> TopicDetails |
addTopic(String topicPath,
TopicType topicType,
Bytes value,
C context,
TopicControl.AddContextCallback<C> callback)
Version of
addTopic(String, TopicType, Bytes, AddCallback) that
allows a user defined context to be provided. |
TopicDetails |
addTopic(String topicPath,
TopicType topicType,
Bytes value,
TopicControl.AddCallback callback)
Send a request to the server to add a topic.
|
<C> TopicDetails |
addTopic(String topicPath,
TopicType topicType,
C context,
TopicControl.AddContextCallback<C> callback)
Version of
addTopic(String, TopicType, AddCallback) that allows
a user defined context to be provided. |
TopicDetails |
addTopic(String topicPath,
TopicType topicType,
TopicControl.AddCallback callback)
Send a request to the server to add a topic.
|
void |
addTopicEventListener(String topicPath,
TopicControl.TopicEventListener listener)
Register a
TopicControl.TopicEventListener to receive topic events for a
branch of the topic tree. |
<T,C> TopicDetails |
addTopicFromValue(String topicPath,
T value,
C context,
TopicControl.AddContextCallback<C> callback)
Version of
addTopicFromValue(String, Object, AddCallback) that
allows a user defined context to be provided. |
<T> TopicDetails |
addTopicFromValue(String topicPath,
T value,
TopicControl.AddCallback callback)
Send a request to the server to add a topic where the type and initial
value for the topic are derived from a provided value object.
|
TopicDetails |
newDetails(TopicType topicType)
Returns new topic details of the given type set with all default
settings.
|
<D extends TopicDetails,B extends TopicDetails.Builder<B,D>> |
newDetailsBuilder(Class<B> builderType)
Create a new topic details builder to create
TopicDetails of a
type corresponding to a given builder type. |
TopicSpecification |
newSpecification(TopicType topicType)
Create a new
TopicSpecification s for a given topic type. |
<C> void |
remove(String topicSelector,
C context,
TopicControl.RemovalContextCallback<C> callback)
Version of
remove(String, RemovalCallback) that allows a user
defined context to be provided. |
void |
remove(String topicSelector,
TopicControl.RemovalCallback callback)
Send a request to remove one or more topics at the server.
|
<C> void |
removeTopics(String topicSelector,
C context,
TopicControl.RemoveContextCallback<C> callback)
Deprecated.
since 5.9
using |
void |
removeTopics(String topicSelector,
TopicControl.RemoveCallback callback)
Deprecated.
since 5.9
using |
void |
removeTopicsWithSession(String topicPath,
TopicTreeHandler registrationHandler)
Register a deferred action to remove a branch of the topic tree.
|
getSession
TopicSpecification newSpecification(TopicType topicType) throws IllegalArgumentException
TopicSpecification
s for a given topic type.topicType
- the topic typewithProperty
or
withProperties
methods of the provided specification.IllegalArgumentException
- if topicType
is null<D extends TopicDetails,B extends TopicDetails.Builder<B,D>> B newDetailsBuilder(Class<B> builderType) throws IllegalArgumentException, UnsupportedOperationException
TopicDetails
of a
type corresponding to a given builder type.D
- topic details typeB
- topic details builder typebuilderType
- the builder typebuilderType
IllegalArgumentException
- if builderType
is nullUnsupportedOperationException
- if there is no available builder
for the type specified in builderType
TopicDetails newDetails(TopicType topicType) throws IllegalArgumentException, IllegalStateException, UnsupportedOperationException
This provides a simpler mechanism than creating a builder where all of the builder's default values are suitable and there are no mandatory properties.
If using this mechanism it is important to understand what the default
details for the topic type would be. The documentation of the relevant
TopicDetails.Builder
subtype should be consulted.
topicType
- the topic typetopicType
IllegalArgumentException
- if topicType
is nullIllegalStateException
- if the specified type requires mandatory
properties and thus a builder
must be usedUnsupportedOperationException
- if there is no builder
implementation for the given type<C> void addTopic(String topicPath, TopicDetails details, C context, TopicControl.AddContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
addTopic(String, TopicDetails, AddCallback)
that
allows a user defined context to be provided.C
- the context object typetopicPath
- the full path of the topic to be createddetails
- defines the topic to be createdcontext
- an 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
- called with the resultIllegalArgumentException
- if topicPath
, details
or
callback
is null
SessionClosedException
- if the session is closed<C> void addTopic(String topicPath, TopicDetails details, Bytes value, C context, TopicControl.AddContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
addTopic(String, TopicDetails, Bytes, AddCallback)
that allows a user defined context to be provided.C
- the context object typetopicPath
- the full path of the topic to be createddetails
- defines the topic to be createdvalue
- - the initial value. If this is specified as null, the
effect is the same as calling
addTopic(String, TopicDetails, Object, AddContextCallback)
. A value may only be supplied for a topic that is
stateful
. An instance of
Content
may be supplied as a value.context
- an 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
- called with the resultIllegalArgumentException
- if topicPath
, details
or
callback
is null
OR if value
has been
supplied for a topic type that is not statefulSessionClosedException
- if the session is closedvoid addTopic(String topicPath, TopicDetails details, TopicControl.AddCallback callback) throws IllegalArgumentException, SessionClosedException
topicPath
- the full path of the topic to be createddetails
- defines the topic to be createdcallback
- called with the resultIllegalArgumentException
- if topicPath
, details
or
callback
is null
SessionClosedException
- if the session is closedvoid addTopic(String topicPath, TopicDetails details, Bytes value, TopicControl.AddCallback callback) throws IllegalArgumentException, SessionClosedException
The topic will be initialized with the given value during creation and
therefore the value must be compatible with the topic
type
otherwise an error
will
be returned.
topicPath
- the full path of the topic to be createddetails
- defines the topic to be createdvalue
- - the initial value. If this is specified as null, the
effect is the same as calling
addTopic(String, TopicDetails, AddCallback)
. A value may
only be supplied for a topic that is stateful
. An instance of Content
may be supplied as a
value.callback
- called with the resultIllegalArgumentException
- if topicPath
, details
or
callback
is null
OR if value
has been
supplied for a topic type that is not statefulSessionClosedException
- if the session is closedTopicDetails addTopic(String topicPath, TopicType topicType, TopicControl.AddCallback callback) throws IllegalArgumentException, IllegalStateException, SessionClosedException
This is a convenience method which is equivalent to a call to
addTopic(String, TopicDetails, AddCallback)
with the details
generated from newDetails(TopicType)
allowing a topic to be
added with default details.
The details generated are returned and may be used to pass to other calls
of addTopic
.
topicPath
- the full path of the topic to be createdtopicType
- the type of topic to be createdcallback
- called with the resultIllegalArgumentException
- if topicPath
, topicType
or callback
is null
IllegalStateException
- if the type can not be created with default
details and must be specified using a details builderSessionClosedException
- if the session is closedTopicDetails addTopic(String topicPath, TopicType topicType, Bytes value, TopicControl.AddCallback callback) throws IllegalArgumentException, IllegalStateException, SessionClosedException
This is a convenience method which is equivalent to a call to
addTopic(String, TopicDetails, Bytes, AddCallback)
with the
details generated from newDetails(TopicType)
allowing a topic to
be added with default details.
If using this mechanism it is important to understand what the default
details for the topic type would be. The documentation of the relevant
TopicDetails.Builder
subtype should be consulted.
The details generated are returned and may be used to pass to other calls
of addTopic
.
topicPath
- the full path of the topic to be createdtopicType
- defines the type of topic to be createdvalue
- - the initial value. If this is specified as null, the
effect is the same as calling
addTopic(String, TopicType, AddCallback)
. A value may
only be supplied for a topic that is stateful
. An instance of Content
may be supplied as a
value.callback
- called with the resultIllegalArgumentException
- if topicPath
, topicType
or callback
is null
OR if value
has been
supplied for a topic type that is not statefulIllegalStateException
- if the type can not be created with default
details and must be specified using a details builderSessionClosedException
- if the session is closed<C> TopicDetails addTopic(String topicPath, TopicType topicType, C context, TopicControl.AddContextCallback<C> callback) throws IllegalArgumentException, IllegalStateException, SessionClosedException
addTopic(String, TopicType, AddCallback)
that allows
a user defined context to be provided.C
- the context object typetopicPath
- the full path of the topic to be createdtopicType
- defines the type of topic to be createdcontext
- an 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
- called with the resultIllegalArgumentException
- if topicPath
, topicType
or callback
is null
IllegalStateException
- if the type can not be created with default
details and must be specified using a details builderSessionClosedException
- if the session is closed<C> TopicDetails addTopic(String topicPath, TopicType topicType, Bytes value, C context, TopicControl.AddContextCallback<C> callback) throws IllegalArgumentException, IllegalStateException, SessionClosedException
addTopic(String, TopicType, Bytes, AddCallback)
that
allows a user defined context to be provided.C
- the context object typetopicPath
- the full path of the topic to be createdtopicType
- defines the type of the topic to be createdvalue
- - the initial value. If this is specified as null, the
effect is the same as calling
addTopic(String, TopicType, Object, AddContextCallback)
.
A value may only be supplied for a topic that is
stateful
. An instance of
Content
may be supplied as a valuecontext
- 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
- called with the resultIllegalArgumentException
- if topicPath
, details
or
callback
is null
OR if value
has been
supplied for a topic type that is not statefulIllegalStateException
- if the type can not be created with default
details and must be specified using a details builderSessionClosedException
- if the session is closed<C> void addTopic(String topicPath, TopicSpecification specification, C context, TopicControl.AddContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
addTopic(String, TopicSpecification, AddCallback)
that allows a user defined context to be provided.C
- the context object typetopicPath
- the full path of the topic to be createdspecification
- defines the topic to be created. A specification can
be created using newSpecification(TopicType)
.context
- an 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
- called with the resultIllegalArgumentException
- if topicPath
,
specification
or callback
is null
SessionClosedException
- if the session is closed<C> void addTopic(String topicPath, TopicSpecification specification, Bytes value, C context, TopicControl.AddContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
addTopic(String, TopicSpecification, Bytes, AddCallback)
that
allows a user defined context to be provided.C
- the context object typetopicPath
- the full path of the topic to be createdspecification
- defines the topic to be created. A specification can
be created using newSpecification(TopicType)
value
- - the initial value. If this is specified as null, the
effect is the same as calling
addTopic(String, TopicSpecification, Object, AddContextCallback)
. A value may only be supplied for a topic that is
stateful
. An instance of
Content
may be supplied as a value.context
- an 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
- called with the resultIllegalArgumentException
- if topicPath
,
specification
or callback
is null
OR if
value
has been supplied for a topic type that is not
statefulSessionClosedException
- if the session is closedvoid addTopic(String topicPath, TopicSpecification specification, TopicControl.AddCallback callback) throws IllegalArgumentException, SessionClosedException
topicPath
- the full path of the topic to be createdspecification
- defines the topic to be created. A specification can
be created using newSpecification(TopicType)
.callback
- called with the resultIllegalArgumentException
- if topicPath
,
specification
or callback
is null
SessionClosedException
- if the session is closedvoid addTopic(String topicPath, TopicSpecification specification, Bytes value, TopicControl.AddCallback callback) throws IllegalArgumentException, SessionClosedException
The topic will be initialized with the given value during creation and
therefore the value must be compatible with the topic
type
otherwise an error
will
be returned.
topicPath
- the full path of the topic to be createdspecification
- defines the topic to be created. A specification can
be created using newSpecification(TopicType)
.value
- - the initial value. If this is specified as null, the
effect is the same as calling
addTopic(String, TopicSpecification, AddCallback)
. A
value may only be supplied for a topic that is
stateful
. An instance of
Content
may be supplied as a value.callback
- called with the resultIllegalArgumentException
- if topicPath
,
specification
or callback
is null
OR if
value
has been supplied for a topic type that is not
statefulSessionClosedException
- if the session is closed<T> TopicDetails addTopicFromValue(String topicPath, T value, TopicControl.AddCallback callback) throws IllegalArgumentException, SessionClosedException
See class documentation
for full details of how this
method may be used.
T
- the value typetopicPath
- the full path of the topic to be createdvalue
- the value from which the topic type, metadata and initial
value are to be derivedcallback
- called with the resultIllegalArgumentException
- if any parameter is null
or if
an empty Content
value is suppliedSessionClosedException
- if the session is closed<T,C> TopicDetails addTopicFromValue(String topicPath, T value, C context, TopicControl.AddContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
addTopicFromValue(String, Object, AddCallback)
that
allows a user defined context to be provided.T
- the value typeC
- the context object typetopicPath
- the full path of the topic to be createdvalue
- the value from which the topic type, metadata and initial
value are to be derivedcontext
- an 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
- called with the resultIllegalArgumentException
- if any parameter except context
is null
or empty Content
is suppliedSessionClosedException
- if the session is closed@Deprecated void removeTopics(String topicSelector, TopicControl.RemoveCallback callback) throws IllegalArgumentException, SessionClosedException
using remove(String, RemovalCallback)
with a //
descendant qualifier on the topic selector has the same
effect
Any descendants of the matched branches will also be removed.
topicSelector
- a topic selector expression
specifying one or more topic tree branches to remove.callback
- called to notify request completedIllegalArgumentException
- if topicSelector
or
callback
is null or topicSelector
does not
specify a valid TopicSelector
SessionClosedException
- if the session is closed@Deprecated <C> void removeTopics(String topicSelector, C context, TopicControl.RemoveContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
using remove(String, Object, RemovalContextCallback)
with a // descendant qualifier on the topic selector has the
same effect
removeTopics(String, RemoveCallback)
that allows a
user defined context to be provided.C
- the context object typetopicSelector
- a topic selector expression
specifying one or more topic tree branches to removecontext
- an 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
- called to notify request completedIllegalArgumentException
- if topicSelector
or
callback
is null or if topicSelector
does not
specify a valid TopicSelector
SessionClosedException
- if the session is closedvoid remove(String topicSelector, TopicControl.RemovalCallback callback) throws IllegalArgumentException, SessionClosedException
The topics to remove will depend upon the nature of the topic selector
specified. If the selector does not have descendant
pattern qualifiers
(i.e. / or //), only those topics that exist at paths
indicated by the selector will be removed and not their descendants. If a
single / qualifier is specified, all descendants of the matching topic
paths will be removed. If // is specified, all branches of the topic tree
that match the selector (i.e topics at the selected paths and all
descendants of the selected paths) will be removed.
topicSelector
- a topic selector expression
specifying the topics to remove.callback
- called to notify request completedIllegalArgumentException
- if topicSelector
or
callback
is null or topicSelector
does not
specify a valid TopicSelector
SessionClosedException
- if the session is closed<C> void remove(String topicSelector, C context, TopicControl.RemovalContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
remove(String, RemovalCallback)
that allows a user
defined context to be provided.C
- the context object typetopicSelector
- a topic selector expression
specifying the topics to remove.context
- an 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
- called to notify request completedIllegalArgumentException
- if topicSelector
or
callback
is null or topicSelector
does not
specify a valid TopicSelector
SessionClosedException
- if the session is closedvoid removeTopicsWithSession(String topicPath, TopicTreeHandler registrationHandler) throws IllegalArgumentException, SessionClosedException
For example, suppose two client sessions both call
topicControl.removeTopicsWithSession("a/b", registrationHandler)
.
When both sessions are closed, either explicitly using
Session.close()
or by the server, the topic a/b
and all of
its descendants will be removed. This method is typically used by a
client that has added one or more topics to tidy up and remove the topics
if it is ever disconnected from the server or otherwise fails.
The server can reject a removeTopicsWithSession
call if the
topicPath
conflicts with existing registrations. Different
sessions may call this method for the same topic path, but not for topic
paths above or below existing registrations on the same branch of the
topic tree.
The following callbacks will be delivered to the provided
registrationHandler
:
onRegistered
will be called as notification that the deferred action is active. A
Registration
is provided that allows the deferred action to be
de-registered
.
onClose
will be called as
notification that the deferred action is no longer active. No further
calls will be made to the registrationHandler
.
onError
will be
called and no further calls will be made to the
registrationHandler
. In general, this is non-recoverable; the
deferred action may or may not be active and the application can do
little more than report the condition. In the specific case that
onError()
is passed
ErrorReason.TOPIC_TREE_REGISTRATION_CONFLICT
, registration has
failed due to a pre-existing registration on the same branch of the topic
tree as topicPath
.
The last session to close must have MODIFY_TOPIC
permission for topicPath
. If this is not the case,
none of the topic or its descendants will be removed.
topicPath
- this topic and its descendants will be removed if the
action is executedregistrationHandler
- called as documented aboveIllegalArgumentException
- if topicPath or registrationCallback is
invalidSessionClosedException
- if the session is closedvoid addMissingTopicHandler(String topicPath, TopicControl.MissingTopicHandler handler) throws IllegalArgumentException, SessionClosedException
TopicControl.MissingTopicHandler
to handle requests for a branch of
the topic tree.
The provided handler is called when a client subscribes or fetches using
a topic selector that matches no existing topics. This allows a control
client to intercede when another session requests a topic that does not
exist. The control client may use any of the addTopic
methods to
create the topic, take some other action, or do nothing, before allowing
the client operation to proceed by calling
proceed()
. Alternatively, the
control client can call cancel()
to discard the request.
A control client can register multiple handlers, but may only register a
single handler for a given topic path. See
onActive
.
A handler will only be called for topic selectors with a
path prefix
that starts with or is
equal to topicPath
. If the path prefix matches multiple handlers,
the one registered for the most specific (longest) topic path will be
called.
topicPath
- identifies a branch in the topic treehandler
- specifies the handler for the specified branch (unless
overridden by a handler registered against a more specific branch)IllegalArgumentException
- if {code topicPath} or handler
is nullSessionClosedException
- if session is closedvoid addTopicEventListener(String topicPath, TopicControl.TopicEventListener listener) throws IllegalArgumentException, SessionClosedException
TopicControl.TopicEventListener
to receive topic events for a
branch of the topic tree.
This allows a client to receive different events for topics. These events are emitted when a topic is subscribed to by one or more sessions after previously having no subscribers, or when a topic is no longer subscribed to by any session. These events are averaged over a small window of time to prevent rapid dispatch of events that ultimately return a topic to it's previous state.
Each control session may register a single handler for a branch. See
onRegistered
.
topicPath
- identifies a branch in the topic treelistener
- specifies the listener for the specified branch (unless
overriden by a listener registered against a more specific branch)IllegalArgumentException
- if topicPath
or listener
is nullSessionClosedException
- if session is closedCopyright © 2016 Push Technology Ltd. All Rights Reserved.