public interface Topic extends TopicTreeNode
Modifier and Type | Field and Description |
---|---|
static long |
DEFAULT_LOCK_TIMEOUT
Default Lock Timeout - 5000 milliseconds.
|
NAME_DELIMITER
Modifier and Type | Method and Description |
---|---|
Topic |
addTopic(String topicName)
Add a Topic to this Topic.
|
Topic |
addTopic(String topicName,
TopicData data)
Add a Topic to this Topic.
|
Topic |
addTopic(String topicName,
TopicDefinition definition)
Add a Topic to this Topic.
|
Object |
attach(Object attachment)
Attaches the given object to this Topic.
|
Object |
attachment()
Retrieves the current attachment.
|
TopicMessage |
createDeltaMessage()
Creates an empty delta message for the Topic.
|
TopicMessage |
createDeltaMessage(int capacity)
Creates an empty delta message for the Topic.
|
AttachableTopicMessage |
createDeltaMessage(int capacity,
Object attachment)
Creates an empty delta message for the Topic with an attachment.
|
AttachableTopicMessage |
createDeltaMessage(Object attachment)
Creates an empty delta message for the Topic with an attachment.
|
TopicMessage |
createLoadMessage()
Creates an empty Topic Load message for the Topic
|
TopicMessage |
createLoadMessage(int capacity)
Creates an empty Topic Load message for the Topic.
|
List<TopicClient> |
getClients()
Returns a list of all of the client sessions that are directly subscribed
to the topic.
|
long |
getCreationTimeMillis()
Returns the time that the Topic was created (in milliseconds).
|
int |
getCurrentNumberOfSubscribers()
Returns the number of clients currently subscribed to the topic.
|
TopicData |
getData()
Returns the Topic Data associated with the Topic (if any).
|
TopicDataType |
getDataType()
Returns the type of
TopicData attached to the Topic. |
int |
getDefaultDeltaMessageCapacity()
Returns the default capacity for delta Messages in bytes created using
this Topic.
|
int |
getDefaultLoadMessageCapacity()
Returns the default capacity for load Messages created using this Topic.
|
TopicDefinition |
getDefinition()
Returns a new definition object representing the Topic.
|
byte |
getIntrospectionMask()
Returns the value of the Topic introspection mask.
|
long |
getLockTimeout()
Deprecated.
since 5.6
All API topic locking methods are deprecated and will be
removed in a future release, see |
String |
getName()
Returns the Topic name.
|
PagedTopicData |
getPagedData()
Deprecated.
since 5.9
This topic type will be removed in a future release |
PublishingTopicData |
getPublishingData()
Returns the Publishing Topic Data associated with the Topic (if any).
|
String |
getReference()
Returns the Topic reference.
|
Topic |
getRootTopic()
Returns the Topic at the top of this Topic's hierarchy.
|
RoutingTopicData |
getRoutingData()
Returns the Routing Topic Data associated with the Topic (if any).
|
TopicStatistics |
getStatistics()
Return the statistics for this topic.
|
TopicStatus |
getStatus()
Returns the Topic status.
|
TopicSubscriptionHandler |
getSubscriptionHandler()
Deprecated.
since 5.5
Consider using routing topics instead. |
TopicProvider |
getTopicProvider()
Returns the Topic Provider that owns this topic.
|
boolean |
hasCommandData()
Deprecated.
since 5.9
All command topics will be removed in a future release |
boolean |
hasData()
Indicates whether the Topic has
data . |
boolean |
hasPagedData()
Deprecated.
since 5.9
This topic type will be removed in a future release |
boolean |
hasPublishingData()
Indicates whether the Topic has data of type
PublishingTopicData . |
boolean |
hasRoutingData()
Indicates whether the Topic has data of type
RoutingTopicData . |
boolean |
hasSubscribers()
Indicates whether the Topic currently has subscribers.
|
boolean |
isLockable()
Deprecated.
since 5.6
All API topic locking methods are deprecated and will be
removed in a future release, see |
boolean |
isLockedByCurrentThread()
Deprecated.
since 5.6
All API topic locking methods are deprecated and will be
removed in a future release, see |
boolean |
isStatisticsEnabled()
Indicates whether Statistics reporting for this Topic is enabled or not.
|
boolean |
isTopicAliasing()
Deprecated.
since 5.5
|
void |
lock()
Deprecated.
since 5.6
All API topic locking methods are deprecated and will be removed in a future release.
In previous releases it was necessary to lock a stateless
topic before |
void |
publishDeltaMessage(Record... records)
This is a convenience method to create a delta message for the topic
populated with the specified records and then publish it.
|
void |
publishDeltaMessage(String... fields)
This is a convenience method to create a delta message for the topic
populated with the specified fields and then publish it.
|
void |
publishExclusiveMessage(TopicMessage message,
TopicClient client)
A variant of
publishMessage(TopicMessage) that publishes a
message to all but one client. |
void |
publishExclusiveMessage(TopicMessage message,
TopicClient client,
MessagePriority priority)
A variant of
publishMessage(TopicMessage) that publishes a
message to all but one client and allows the message priority to be
specified. |
void |
publishMessage(TopicMessage message)
Publish a message to all clients that are subscribed to the topic of the
message.
|
void |
publishMessage(TopicMessage message,
MessagePriority priority)
A variant of
publishMessage(TopicMessage) that allows the
message priority to be specified. |
void |
setDefaultDeltaMessageCapacity(int capacity)
Sets the default capacity for delta Messages in bytes created using the
createDeltaMessage() method. |
void |
setDefaultLoadMessageCapacity(int capacity)
Sets the default capacity for load Messages in bytes created using the
createLoadMessage() method. |
void |
setIntrospectionMask(byte mask)
This may be used to set the Introspection capabilities of the Topic.
|
void |
setLockTimeout(long timeout)
Deprecated.
since 5.6. All API topic locking methods are deprecated and
will be removed in a future release, see
lock() for
details. |
void |
setReference(String reference)
Sets a user reference for the Topic.
|
void |
setTidyOnUnsubscribe(boolean tidy)
Allows the 'Tidy on Unsubscribe' option to be set for the Topic.
|
void |
startStatistics()
Starts the collection of this Topic's statistics.
|
void |
stopStatistics()
Stops the collection of this Topic's statistics.
|
void |
subscribe(TopicClient client)
Subscribe a client to this topic.
|
void |
subscribeClients()
Subscribe all currently connected clients to the topic.
|
void |
subscribeClients(boolean force)
Deprecated.
since 5.5
|
boolean |
tidyOnUnsubscribe()
Indicates whether the 'Tidy on unsubscribe' option is set for the Topic.
|
void |
unlock()
Deprecated.
since 5.6
All API topic locking methods are deprecated and will be
removed in a future release, see |
equals, getAllTopics, getLevel, getNodeName, getParent, getRoot, getTopic, getTopics, getTopics, getTopics, getTopics, getTopics, hashCode, hasTopic, hasTopics, isAutoSubscribing, isRoot, isTopic, remove, removeTopic, setAutoSubscribe
static final long DEFAULT_LOCK_TIMEOUT
String getName()
This is the full hierarchic name of the Topic.
TopicDefinition getDefinition()
long getCreationTimeMillis()
TopicProvider getTopicProvider()
Topic addTopic(String topicName) throws TopicInvalidException
When adding a Topic using this method the owner of the subordinate Topic will be set to parents owner.
topicName
- the name of the Topic. If the name is a hierarchic name
and the intermediate level Topics do not exist then they will also
be created.TopicInvalidException
- if unable to create a Topic of the given
name, possibly because one already exists.Topic addTopic(String topicName, TopicData data) throws TopicInvalidException, APIException
When adding a Topic using this method the owner of the subordinate Topic will be set to parents owner.
topicName
- the name of the Topic. If the name is a hierarchic name
and the intermediate level Topics do not exist then they will also
be created.data
- the Topic Data.TopicInvalidException
- if topic name is invalid.APIException
- if unable to add the data to the TopicTopic addTopic(String topicName, TopicDefinition definition) throws TopicInvalidException, APIException
When adding a Topic using this method the owner of the subordinate Topic will be set to parents owner.
topicName
- the name of the Topic. If the name is a hierarchic name
and the intermediate level Topics do not exist then they will also
be created.definition
- the Topic definitionTopicInvalidException
- if topic name is invalid.APIException
- if unable to add the data to the TopicTopicDataType getDataType()
TopicData
attached to the Topic.TopicDataType.NONE
is returned.boolean hasData()
TopicData getData()
boolean hasPublishingData()
PublishingTopicData
.
For convenience the data may be obtained using
getPublishingData()
.
PublishingTopicData getPublishingData()
PublishingTopicData
.boolean hasRoutingData()
RoutingTopicData
.
For convenience the data may be obtained using getRoutingData()
.
RoutingTopicData getRoutingData()
RoutingTopicData
.@Deprecated boolean hasCommandData()
All command topics will be removed in a future release
CommandTopicData
.
Other methods can be used to determine which type of command data it is,
for example hasPagedData()
.
@Deprecated boolean hasPagedData()
This topic type will be removed in a future release
PagedTopicData
.
For convenience the data may be obtained using getPagedData()
.
@Deprecated PagedTopicData getPagedData()
This topic type will be removed in a future release
PagedTopicData
.void setReference(String reference)
When short Topic names then the user may set a more meaningful reference for the Topic.
reference
- a free format Topic reference.String getReference()
This returns the Topic reference.
Object attach(Object attachment)
An attached object may later be retrieved via the attachment
method. Only one object may be attached at a time; invoking
this method causes any previous attachment to be discarded. The current
attachment may be discarded by attaching null.
attachment
- The object to be attached. Specifying null has
the effect of removing any current attachment.Object attachment()
int getCurrentNumberOfSubscribers()
Each server subscribed to the topic through the topic replication or fan-out features is counted as a subscriber.
Since 5.5, the behavior has changed. The returned value includes indirect
subscriptions through routing or slave topics. This differs from the
topic statistics
,
which only include direct subscriptions to the topic.
boolean hasSubscribers()
Since 5.5, the behavior has changed. This method will return true if the topic has subscribers, or if there are indirect subscribers via slave topic data or routing topic data topics.
TopicStatistics getStatistics()
The returned TopicStatistics
will become stale if statistics
recording is disabled (for example, if stopStatistics()
is
called). If topic statistics recording is disabled when this method is
called, the TopicStatistics
will return -1
for each
statistic value.
TopicStatus getStatus()
int getDefaultDeltaMessageCapacity()
If a value has been set using
setDefaultDeltaMessageCapacity(int)
then this is what will be
returned otherwise the value as indicated by
RootConfig#getDefaultDeltaMessageCapacity()
will be returned.
This is the value that will be used by the createDeltaMessage()
method.
void setDefaultDeltaMessageCapacity(int capacity) throws APIException
createDeltaMessage()
method.
If not explicitly set then the value is assumed to be as
RootConfig#getDefaultDeltaMessageCapacity()
.
capacity
- the default capacityAPIException
- if capacity is invalid.int getDefaultLoadMessageCapacity()
If a value has been set using setDefaultLoadMessageCapacity(int)
then this is what will be returned otherwise the value as indicated by
RootConfig#getDefaultLoadMessageCapacity()
will be returned.
This is the value that will be used by the createLoadMessage()
method.
void setDefaultLoadMessageCapacity(int capacity) throws APIException
createLoadMessage()
method.
If not explicitly set then the value is assumed to be as
RootConfig#getDefaultLoadMessageCapacity()
.
capacity
- the default Message capacity.APIException
- if the specified capacity is invalid.TopicMessage createLoadMessage(int capacity) throws MessageException
capacity
- the initial capacity of the message in bytes which should
be sufficient to hold the data and any user headers. If more is
written to the message than this then it will automatically be
extended, however there is an overhead to such extensions so for
maximum efficiency a suitable capacity should be chosen.MessageException
- if unable to create a message.TopicMessage createLoadMessage() throws MessageException
The message will be created with a capacity as indicated by
getDefaultLoadMessageCapacity()
.
MessageException
- if unable to create a message.TopicMessage createDeltaMessage(int capacity) throws MessageException
capacity
- the initial capacity of the message in bytes which should
be sufficient to hold the data and any user headers. If more is
written to the message than this then it will automatically be
extended, however there is an overhead to such extensions so for
maximum efficiency a suitable capacity should be chosen.MessageException
- if unable to create a new message.TopicMessage createDeltaMessage() throws MessageException
The message will be created with a capacity as indicated by
getDefaultDeltaMessageCapacity()
.
MessageException
- if unable to create a new message.AttachableTopicMessage createDeltaMessage(int capacity, Object attachment) throws MessageException
capacity
- the initial capacity of the message in bytes which should
be sufficient to hold the data and any user headers. If more is
written to the message than this then it will automatically be
extended, however there is an overhead to such extensions so for
maximum efficiency a suitable capacity should be chosen.attachment
- an attachment which will be accessible within the same
VM but will not form part of the serialized message.MessageException
- if unable to create a new message.AttachableTopicMessage createDeltaMessage(Object attachment) throws MessageException
The message will be created with a capacity as indicated by
getDefaultDeltaMessageCapacity()
.
attachment
- an attachment which will be accessible within the same
VM but will not form part of the serialized message.MessageException
- if unable to create a new message.void publishMessage(TopicMessage message) throws APIException
Once a message is published it is locked and may no longer be changed.
This method should only be used for topics that have no topic data. That
is, topics for which getDataType()
returns
TopicDataType.NONE
. Use
PublishingTopicData.publishMessage(TopicMessage)
to broadcast
messages to topics with topic data.
From release 5.6, an error message will be logged the first time that this method is called for a topic that has topic data. In future releases, an exception will be thrown if the topic has topic data.
message
- the message to publish.APIException
- if unable to publish the message, for example if the
topic is deletedvoid publishExclusiveMessage(TopicMessage message, TopicClient client) throws APIException
publishMessage(TopicMessage)
that publishes a
message to all but one client.
This method should only be used for topics that have no topic data, see
publishMessage(TopicMessage)
.
message
- the message to publish.client
- the client not to send the message to.APIException
- if unable to publish the message, for example if the
topic is deletedvoid publishMessage(TopicMessage message, MessagePriority priority) throws APIException
publishMessage(TopicMessage)
that allows the
message priority to be specified.
This method should only be used for topics that have no topic data, see
publishMessage(TopicMessage)
.
message
- the message to publish.priority
- the message priorityAPIException
- if unable to publish the message, for example if the
topic is deletedvoid publishDeltaMessage(String... fields) throws APIException
This method should only be used for topics that have no topic data, see
publishMessage(TopicMessage)
.
fields
- if not specified then an empty message would be published.APIException
- if unable to create or publish the messagevoid publishDeltaMessage(Record... records) throws APIException
This method should only be used for topics that have no topic data, see
publishMessage(TopicMessage)
.
records
- if not specified then an empty message would be published.APIException
- if unable to create or publish the message.void publishExclusiveMessage(TopicMessage message, TopicClient client, MessagePriority priority) throws APIException
publishMessage(TopicMessage)
that publishes a
message to all but one client and allows the message priority to be
specified.
This method should only be used for topics that have no topic data, see
publishMessage(TopicMessage)
.
message
- the message to publish.client
- the client not to send the message to.priority
- the message priorityAPIException
- if unable to publish the message, for example if the
topic is deletedList<TopicClient> getClients()
ClientConnection.isConnected()
.void subscribe(TopicClient client) throws APIException
The client's topic selections are not updated. If this topic is deleted and a new topic with the same path is created, unless there is another matching selection, the client will not be re-subscribed.
Diffusion 5.6
changed the way that subscriptions are evaluated
. When this method
returns, the new subscription might not have yet been completed.
From Diffusion 5.6, the subscription will fail if the client is not authorized to access to the topic. In previous releases, this method bypassed access control checks.
From Diffusion 5.6, this method can be used to subscribe to topics with
routing topic data
. In earlier releases, this
was disallowed and resulted in an APIException.
client
- the client to subscribeAPIException
- from Diffusion 5.6, subscription is completed
asynchronously and this method will not throw APIException@Deprecated TopicSubscriptionHandler getSubscriptionHandler()
Consider using routing topics instead.
void subscribeClients()
Diffusion 5.6 has
changed the way that subscriptions are evaluated
. When this method
returns, the new subscriptions may not have yet been completed.
@Deprecated void subscribeClients(boolean force)
auto subscription
is
always enabled so setting force=false has no effect. Prefer
subscribeClients()
instead.
Passing true
for the force
parameter has the same effect
as subscribeClients()
.
In previous releases, automatic
subscription
of clients to new topics was optional. Calling this method
with a false
value for the force
parameter would cause
the clients' subscriptions to be re-evaluated against the topic. Since
5.5, automatic subscription cannot be disabled, and calling this method
with force=false has no effect.
Diffusion 5.6 has
changed the way that subscriptions are evaluated
. When this method
returns, the new subscriptions may not have yet been completed.
force
- see abovevoid setTidyOnUnsubscribe(boolean tidy)
By default, if a Client unsubscribes from a Topic then it may still receive Messages that are already queued for it on that Topic.
If this option is set then when a Client unsubscribes from a Topic then any Messages for that Topic that are still queued for the Client are removed. There can be a performance overhead to using this option as the Client queue must be locked whilst Messages are removed, however it may prove useful for preventing unwanted Messages being sent to Clients.
tidy
- true if tidy on subscribe requiredboolean tidyOnUnsubscribe()
setTidyOnUnsubscribe(boolean)
void setIntrospectionMask(byte mask)
For example to allow the Topic's data to be updated:
setIntrospectionMask(TopicIntrospection.UPDATE);
By default a topic will have no Introspection capabilities.
mask
- the mask value. The mask value constants on
TopicIntrospection
can be 'or'd to produce a mask. A value
of -1 (or TopicIntrospection.FULL
) would allow full
introspection capabilities.byte getIntrospectionMask()
setIntrospectionMask(byte)
.@Deprecated boolean isLockable()
All API topic locking methods are deprecated and will be
removed in a future release, see lock()
for details.
Since 5.9, a;; topics are lockable therefore this will always
return true.
@Deprecated void lock() throws TimeoutException
All API topic locking methods are deprecated and will be removed in a future release.
In previous releases it was necessary to lock a stateless
topic before broadcasting a message
to prevent a race condition where the message could be
delivered to a new subscriber before topic load messages sent
by a publisher. From release 5.6, this locking is no longer
necessary. The server will ensure messages published to a new
subscriber from a Publisher.subscription() notification will
be delivered to the subscriber before subsequent broadcasts.
If the Topic is locked by another thread then this will block until the lock is released or the specified timeout period has elapsed.
This method should not be used on Topics that use
TopicData
where all locking is handled automatically.
When a lock is acquired for updating the Topic state then it is important
that the calling thread always releases the lock (using unlock()
) in order to prevent the blocking of other threads. It is strongly
recommended that the following code pattern is used to ensure this:
topic.lock(); try { // Update the Topic State and publish deltas } finally { topic.unlock() }
TimeoutException
- if the lock could not be acquired within the
given timeout period.@Deprecated void unlock()
All API topic locking methods are deprecated and will be
removed in a future release, see lock()
for details.
lock
on the Topic
then this will release it.
If this is called when the current thread does not own the lock then there is no effect.
@Deprecated boolean isLockedByCurrentThread()
All API topic locking methods are deprecated and will be
removed in a future release, see lock()
for details.
@Deprecated void setLockTimeout(long timeout) throws APIException
lock()
for
details.DEFAULT_LOCK_TIMEOUT
.
The lock timeout is the amount of time in milliseconds that a call to
lock()
will block for if another thread has locked the Topic.
Once the method has blocked for the given timeout period then a
TimeoutException
will be thrown.
timeout
- the timeout value in millisecondsAPIException
- if a non positive timeout is specified.@Deprecated long getLockTimeout()
All API topic locking methods are deprecated and will be
removed in a future release, see lock()
for details.
setLockTimeout(long)
Topic getRootTopic()
@Deprecated boolean isTopicAliasing()
By default this will be determined by the Publisher but can be overridden
if the Topic is created using a TopicDefinition
.
void startStatistics()
If Statistics reporting is enabled, this will start the collection of statistics specific to this Topic's if they are not already running.
void stopStatistics()
If statistics collection for this Topic has been enabled, this will discard the statistics and stop further values from being recorded.
boolean isStatisticsEnabled()
By default this will be false, unless '
Copyright © 2016 Push Technology Ltd. All Rights Reserved.