public interface TopicProvider
The Topic Provider that creates a Topic owns that Topic. Only the owning Topic Provider of a Topic can add subordinate Topics. A Topic Provider has support for creating and publishing messages.
Modifier and Type | Method and Description |
---|---|
Topic |
addTopic(String topicName)
Add a Topic to the root of the Topic tree.
|
Topic |
addTopic(String topicName,
TopicData data)
Add a Topic to the root of the Topic tree.
|
Topic |
addTopic(String topicName,
TopicDefinition definition)
Add a Topic to the root of the Topic tree.
|
Topic |
addTopic(String topicName,
TopicTreeNode parent)
Adds a Topic to a specified parent Topic.
|
Topic |
addTopic(String topicName,
TopicTreeNode parent,
TopicData data)
Adds a Topic to a specified parent Topic.
|
Topic |
addTopic(String topicName,
TopicTreeNode parent,
TopicDefinition definition)
Adds a Topic to a specified parent Topic.
|
void |
addTopicLoader(TopicLoader topicLoader,
String topicPattern)
Adds a new Topic Loader.
|
void |
addTopics(TopicSet topics)
Add a set of Topics.
|
void |
addTopics(TopicSet topics,
TopicTreeNode parent)
Add a set of Topics to a specified parent node.
|
ClientGroup |
createClientGroup(String groupName)
Create a new client group.
|
TopicMessage |
createDeltaMessage(String topicName)
Creates an empty delta message.
|
TopicMessage |
createDeltaMessage(String topicName,
int capacity)
Creates an empty delta message.
|
TopicMessage |
createLoadMessage(String topicName)
Creates an empty Topic Load message.
|
TopicMessage |
createLoadMessage(String topicName,
int capacity)
Creates an empty Topic Load message.
|
long |
getAckTimeout()
Returns the default ACK timeout value for the provider.
|
ClientGroup |
getClientGroup(String groupName)
Gets a named client group.
|
List<String> |
getClientGroupMembership(TopicClient client)
Gets a list of group names that a specified client currently belongs to.
|
int |
getNumberOfTopics()
Returns the current number of Topics.
|
Topic |
getTopic(String topicName)
Returns a named Topic of the provider.
|
Topic |
getTopic(TopicMessage message)
Returns the Topic belonging to the provider that matches a given Message.
|
TopicLoader |
getTopicLoader(String topicName)
Returns the Topic loader for a given Topic name.
|
List<Topic> |
getTopics()
Returns a list of the provider's Topics.
|
TopicTree |
getTopicTree()
Returns the provider's Topic Tree.
|
boolean |
isTopicAliasing()
Indicates whether Topic aliasing is turned on for the Topic provider.
|
void |
publishExclusiveMessage(TopicMessage message,
TopicClient client)
Deprecated.
since 5.6. See
publishMessage(TopicMessage) for
details. |
void |
publishExclusiveMessage(TopicMessage message,
TopicClient client,
MessagePriority priority)
Deprecated.
since 5.6. See
publishMessage(TopicMessage) for
details. |
void |
publishMessage(TopicMessage message)
Deprecated.
since 5.6.
The methods that publish messages to topics have been deprecated and will be removed in a future release. Use one of the following options instead.
|
void |
publishMessage(TopicMessage message,
MessagePriority priority)
Deprecated.
since 5.6. See
publishMessage(TopicMessage) for
details. |
boolean |
removeClientGroup(String groupName)
Removes a client group.
|
boolean |
removeTopic(String topicName)
Removes a named topic from the provider.
|
boolean |
removeTopicLoader(TopicLoader topicLoader)
Removes a Topic Loader.
|
TopicSet |
removeTopics(TopicSet topics)
Removes a set of Topics from the provider.
|
void |
setAckTimeout(long timeout)
Sets the (default) ACK timeout value for messages that require
Acknowledgment.
|
void |
subscribeClients(Topic topic)
Subscribe all connected clients to a specified topic.
|
void |
subscribeClients(Topic topic,
boolean force)
Deprecated.
since 5.5.
auto subscription is always enabled so setting force=false
has no effect. Prefer subscribeClients(Topic)
instead. |
TopicTree getTopicTree()
Topic addTopic(String topicName) throws TopicInvalidException
topicName
- the name of the Topic. If the name is a hierarchical
name and the intermediate level Topics do not exist then they will
also be created. Topic names may contain any UTF-8 compatible
characters except ',' and any character used as a metacharacter in
a regular expression Pattern
.TopicInvalidException
- if unable to create a Topic of the given
name, possibly because one already exists or a parent Topic is
owned by a different Topic Provider.Topic addTopic(String topicName, TopicTreeNode parent) throws TopicInvalidException
topicName
- the name of the Topic within its parent. The actual
Topic name will become the hierarchic name of the parent plus this
name (e.g. parent/name). If the name is a hierarchical name and
the intermediate level Topics do not exist then they will also be
created. Topic names may contain any UTF-8 compatible characters
except ',' and any character used as a metacharacter in a regular
expression Pattern
.parent
- the parent node within the Topic tree. If this is specified
as null then it is same as calling addTopic(String)
.TopicInvalidException
- if unable to create a Topic of the given
name within the specified parent node, possibly because the name
is invalid or a Topic with the same name already exists or a
parent Topic is owned by a different Topic Provider.Topic addTopic(String topicName, TopicDefinition definition) throws TopicInvalidException, APIException
This version specifies a definition object and may be used when it is required to set some or all attributes of the Topic when it is constructed. For example, the definition can fully specify the Topic Data required.
topicName
- the name of the Topic. If the name is a hierarchical
name and the intermediate level Topics do not exist then they will
also be created. Topic names may contain any UTF-8 compatible
characters except ',' and any character used as a metacharacter in
a regular expression Pattern
.definition
- the definition of the TopicTopicInvalidException
- if the specified topic name is invalidAPIException
- if unable to create a Topic possibly because one
already exists or some aspect of the definition is invalid.Topic addTopic(String topicName, TopicTreeNode parent, TopicDefinition definition) throws TopicInvalidException, APIException
This version specifies a definition object and may be used when it is required to some or all attributes of the Topic when it is constructed. For example, the Topic Data required can be specified by the definition.
topicName
- the name of the Topic within its parent. The actual
Topic name will become the hierarchic name of the parent plus this
name (e.g. parent/name). If the name is a hierarchical name and
the intermediate level Topics do not exist then they will also be
created. Topic names may contain any UTF-8 compatible characters
except ',' and any character used as a metacharacter in a regular
expression Pattern
.parent
- the parent node within the Topic tree. If this is specified
as null then it is same as calling addTopic(String)
.definition
- the Topic definitionTopicInvalidException
- if the specified topic name is invalidAPIException
- if unable to create a Topic possibly because one
already exists or some aspect of the definition is invalid.Topic addTopic(String topicName, TopicData data) throws TopicInvalidException, APIException
topicName
- the name of the Topic. If the name is a hierarchical
name and the intermediate level Topics do not exist then they will
also be created. Topic names may contain any UTF-8 compatible
characters except ',' and any character used as a metacharacter in
a regular expression Pattern
.data
- the Topic Data.TopicInvalidException
- if topic name is invalid.APIException
- if unable to add the data to the TopicTopic addTopic(String topicName, TopicTreeNode parent, TopicData data) throws TopicInvalidException, APIException
topicName
- the name of the Topic within its parent. The actual
Topic name will become the hierarchic name of the parent plus this
name (e.g. parent/name). If the name is a hierarchical name and
the intermediate level Topics do not exist then they will also be
created. Topic names may contain any UTF-8 compatible characters
except ',' and any character used as a metacharacter in a regular
expression Pattern
.parent
- the parent node within the Topic tree. If this is specified
as null then it is same as calling addTopic(String)
.data
- the Topic Data.TopicInvalidException
- if topic name is invalid.APIException
- if unable to add the Topic.void addTopics(TopicSet topics, TopicTreeNode parent) throws TopicInvalidException
This is the same as repeatedly calling
addTopic(String, TopicTreeNode)
for each Topic name within the
set except all Topic names are validated before any are added. Duplicates
are ignored.
topics
- a set of Topic names to add.parent
- the parent node.TopicInvalidException
- if unable to add Topics.void addTopics(TopicSet topics) throws TopicInvalidException
This is the same as repeatedly calling addTopic(String)
for each
Topic name within the set except all Topic names are validated before any
are added. Duplicates are ignored.
topics
- a set of Topic names to add.TopicInvalidException
- if unable to add Topics.int getNumberOfTopics()
Topic getTopic(String topicName)
topicName
- the Topic nameTopic getTopic(TopicMessage message)
message
- the message.boolean removeTopic(String topicName)
If the named topic also has subordinate topics then they will also be removed.
topicName
- the full hierarchic Topic name.TopicSet removeTopics(TopicSet topics)
topics
- a set of Topics.void addTopicLoader(TopicLoader topicLoader, String topicPattern) throws TopicInvalidException
If Topic Loaders are used then when a Client subscribes to a Topic and there is a Topic Loader for the Topic in question then it will be used to perform Topic load processing before notifying the provider of subscription.
A Topic Loader can be declared for each Topic or a loader can apply to
more than one Topic by using TopicSelector
patterns.
The order in which Topic loaders are declared is significant in that when searching for a suitable loader for a Topic they are searched in the order they were declared.
Topic Loaders may be added for Topics at any time, even before the Topic itself is added.
topicLoader
- the Topic Loader to add.topicPattern
- the Topic name or selector pattern that indicates
which Topics the Topic Loader applies to.TopicInvalidException
- if the supplied topicPattern is not a valid
Topic name or selector pattern.boolean removeTopicLoader(TopicLoader topicLoader)
topicLoader
- the Topic Loader to remove.TopicLoader getTopicLoader(String topicName)
topicName
- the Topic name.boolean isTopicAliasing()
This feature allows short Topic aliases to be transmitted in Messages rather than full Topic names.
This requirement is configurable for a Publisher. See
PublisherConfig#setTopicAliasing(boolean)
.
void subscribeClients(Topic topic)
topic
- the topic.@Deprecated void subscribeClients(Topic topic, boolean force)
auto subscription
is always enabled so setting force=false
has no effect. Prefer subscribeClients(Topic)
instead.
Passing true
for the force
parameter has the same effect
as subscribeClients(Topic)
.
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 client 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.
topic
- the topic.force
- see above.ClientGroup createClientGroup(String groupName) throws APIException
groupName
- the client group name which must be unique for the topic
provider.APIException
- if there is already a client group for the provider
with the given name.ClientGroup getClientGroup(String groupName)
groupName
- the name of a client group within the provider.List<String> getClientGroupMembership(TopicClient client)
client
- the client to enquire upon.boolean removeClientGroup(String groupName)
groupName
- the client group name.TopicMessage createLoadMessage(String topicName) throws MessageException
This is a convenience method equivalent to calling
Topic.createLoadMessage()
on an existing Topic. This can also be
used to create a message for a Topic that does not exist as it is
permitted to send fetch replies for non existent Topics.
topicName
- the topic name.MessageException
- if unable to create a message.TopicMessage createLoadMessage(String topicName, int capacity) throws MessageException
This is a convenience method equivalent to calling
Topic.createLoadMessage(int)
on a existing Topic. This can also
be used to create a message for a Topic that does not exist as it is
permitted to send fetch replies for non existent Topics.
topicName
- the topic name.capacity
- the initial capacity of the message 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 createDeltaMessage(String topicName) throws MessageException
This is a convenience method equivalent to calling
Topic.createDeltaMessage()
on the Topic.
topicName
- the topic name.MessageException
- if unable to create a new message.TopicMessage createDeltaMessage(String topicName, int capacity) throws MessageException
This is a convenience method equivalent to calling
Topic.createDeltaMessage(int)
on the Topic.
topicName
- the topic name.capacity
- the initial capacity of the message 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.@Deprecated void publishMessage(TopicMessage message) throws APIException
The methods that publish messages to topics have been deprecated and will be removed in a future release. Use one of the following options instead.
Topic
methods such as
Topic.publishMessage(TopicMessage)
. Use
getTopic(TopicMessage)
to lookup the topic if
necessary.
PublishingTopicData#publishMessage()
.
Once a message is published it is locked and may no longer be changed.
message
- the message to publish.APIException
- if unable to publish the message.@Deprecated void publishExclusiveMessage(TopicMessage message, TopicClient client) throws APIException
publishMessage(TopicMessage)
for
details.publishMessage(TopicMessage)
that publishes a
message to all but one client.message
- the message to publish.client
- the client not to send the message to.APIException
- if unable to publish the message.@Deprecated void publishMessage(TopicMessage message, MessagePriority priority) throws APIException
publishMessage(TopicMessage)
for
details.publishMessage(TopicMessage)
that allows the
message priority to be specified.message
- the message to publish.priority
- the priorityAPIException
- if unable to publish the message.@Deprecated void publishExclusiveMessage(TopicMessage message, TopicClient client, MessagePriority priority) throws APIException
publishMessage(TopicMessage)
for
details.publishMessage(TopicMessage)
that publishes a
message to all but one client and allows the message priority to be
specified.message
- the message to publish.client
- the client not to send the message to.priority
- the priorityAPIException
- if unable to publish the message.void setAckTimeout(long timeout)
The ACK timeout is the number of milliseconds allowed between sending a
message with acknowledgment required (see
TopicMessage.setAckRequired()
) and acknowledgment being received
by the provider. If acknowledgment is not received within this time then
the provider will be notified via the ClientAckListener
interface.
This value is used if the timeout value is not explicitly set for the
message using TopicMessage.setAckTimeout(long)
.
If no value is explicitly specified for a provider then a default value is assumed.
timeout
- the default ACK timeout value in milliseconds.long getAckTimeout()
Copyright © 2016 Push Technology Ltd. All Rights Reserved.