TopicSession object provides methods for creating TopicPublisher, TopicSubscriber, and
TemporaryTopic objects. It also provides a method for deleting its client's durable subscribers.
A TopicSession is used for creating Pub/Sub specific objects. In general, use the Session object, and
use TopicSession only to support existing code. Using the Session object simplifies the programming
model, and allows transactions to be used across the two messaging domains.
A TopicSession cannot be used to create objects specific to the point-to-point domain. The following methods
inherit from Session, but must throw an IllegalStateException if used from TopicSession:
createBrowser
createQueue
createTemporaryQueue
jakarta.jms.Session, jakarta.jms.Connection#createSession(boolean, int), jakarta.jms.TopicConnection#createTopicSession(boolean, int), jakarta.jms.XATopicSession#getTopicSession()
| Modifier and Type | Method and Description |
|---|---|
| public TopicSubscriber | Returns: An unshared durable subscription on the specified topic.the non-temporary topic, String Topic to subscribe tothe name used to identify this subscription name)Redeclares jakarta. Creates an unshared durable subscription on the specified topic (if one does not already exist) and creates a consumer on that durable subscription. |
| public TopicSubscriber | createDurableSubscriber(Topic
the non-temporary topic, String Topic to subscribe tothe name used to identify this subscription name, String only messages with properties matching the message selector expression are added to the
durable subscription. A value of null or an empty string indicates that there is no message selector for the durable
subscription. messageSelector, boolean if true then any messages published to the topic using this session's connection, or any other
connection with the same client identifier, will not be added to the durable subscription. noLocal)Redeclares jakarta. Creates an unshared durable subscription on the specified topic (if one does not already exist), specifying a message
selector and the |
| public TopicPublisher | Returns: A publisher for the specified topic.the topic)Topic to publish to, or null if this is an unidentified producerCreates a publisher for the specified topic. |
| public TopicSubscriber | Returns: A nondurable subscriber to the specified topic.the topic)Topic to subscribe toCreates a nondurable subscriber to the specified topic. |
| public TopicSubscriber | Returns: A nondurable subscriber to the specified topic.the topic, String Topic to subscribe toonly messages with properties matching the message selector expression are delivered. A value
of null or an empty string indicates that there is no message selector for the message consumer. messageSelector, boolean if set, inhibits the delivery of messages published by its own connection noLocal)Creates a nondurable subscriber to the specified topic, using a message selector or specifying whether messages published by its own connection should be delivered to it. |
| public TemporaryTopic | Returns: a temporary topic identityRedeclares jakarta. Creates a |
| public Topic | Returns: aTopic with the given namethe name of this topicName)TopicRedeclares jakarta. Creates a topic identity given a |
| public void | unsubscribe(String
the name used to identify this subscription name)Redeclares jakarta. Unsubscribes a durable subscription that has been created by a client. |
| createDurableSubscriber | back to summary |
|---|---|
| public TopicSubscriber createDurableSubscriber(Topic topic, String name) throws JMSException Redeclares jakarta. Creates an unshared durable subscription on the specified topic (if one does not already exist) and creates a
consumer on that durable subscription. This method creates the durable subscription without a message selector and
with a A durable subscription is used by an application which needs to receive all the messages published on a topic, including the ones published when there is no active consumer associated with it. The Jakarta Messaging provider retains a record of this durable subscription and ensures that all messages from the topic's publishers are retained until they are delivered to, and acknowledged by, a consumer on this durable subscription or until they have expired.
A durable subscription will continue to accumulate messages until it is deleted using the
This method may only be used with non-shared durable subscriptions. Any durable subscription created using this
method will be non-shared. This means that only one active (i.e. not closed) consumer on the subscription may exist
at a time. The term "consumer" here means a An unshared durable subscription is identified by a name specified by the client and by the client identifier, which must be set. An application which subsequently wishes to create a consumer on that non-shared durable subscription must use the same client identifier.
If an unshared durable subscription already exists with the same name and client identifier and the same topic and
message selector, and there is no consumer already active (i.e. not closed) on the durable subscription, and no
consumed messages from that subscription are still part of a pending transaction or are not yet acknowledged in the
session, then this method creates a
If an unshared durable subscription already exists with the same name and client identifier, and there is a consumer
already active (i.e. not closed) on the durable subscription, or consumed messages from that subscription are still
part of a pending transaction or are not yet acknowledged in the session, then a
If an unshared durable subscription already exists with the same name and client identifier but a different topic,
message selector or
A shared durable subscription and an unshared durable subscription may not have the same name and client identifier.
If a shared durable subscription already exists with the same name and client identifier then a There is no restriction on durable subscriptions and shared non-durable subscriptions having the same name and clientId. Such subscriptions would be completely separate.
This method is identical to the corresponding
| |
| createDurableSubscriber | back to summary |
|---|---|
| public TopicSubscriber createDurableSubscriber(Topic topic, String name, String messageSelector, boolean noLocal) throws JMSException Redeclares jakarta. Creates an unshared durable subscription on the specified topic (if one does not already exist), specifying a message
selector and the A durable subscription is used by an application which needs to receive all the messages published on a topic, including the ones published when there is no active consumer associated with it. The Jakarta Messaging provider retains a record of this durable subscription and ensures that all messages from the topic's publishers are retained until they are delivered to, and acknowledged by, a consumer on this durable subscription or until they have expired.
A durable subscription will continue to accumulate messages until it is deleted using the
This method may only be used with non-shared durable subscriptions. Any durable subscription created using this
method will be non-shared. This means that only one active (i.e. not closed) consumer on the subscription may exist
at a time. The term "consumer" here means a An unshared durable subscription is identified by a name specified by the client and by the client identifier, which must be set. An application which subsequently wishes to create a consumer on that non-shared durable subscription must use the same client identifier.
If an unshared durable subscription already exists with the same name and client identifier and the same topic and
message selector, and there is no consumer already active (i.e. not closed) on the durable subscription, and no
consumed messages from that subscription are still part of a pending transaction or are not yet acknowledged in the
session, then this method creates a
If an unshared durable subscription already exists with the same name and client identifier, and there is a consumer
already active (i.e. not closed) on the durable subscription, or consumed messages from that subscription are still
part of a pending transaction or are not yet acknowledged in the session, then a
If an unshared durable subscription already exists with the same name and client identifier but a different topic,
message selector or
A shared durable subscription and an unshared durable subscription may not have the same name and client identifier.
If a shared durable subscription already exists with the same name and client identifier then a
If There is no restriction on durable subscriptions and shared non-durable subscriptions having the same name and clientId. Such subscriptions would be completely separate.
This method is identical to the corresponding
| |
| createPublisher | back to summary |
|---|---|
| public TopicPublisher createPublisher(Topic topic) throws JMSException Creates a publisher for the specified topic.
A client uses a
| |
| createSubscriber | back to summary |
|---|---|
| public TopicSubscriber createSubscriber(Topic topic) throws JMSException Creates a nondurable subscriber to the specified topic.
A client uses a
Regular
In some cases, a connection may both publish and subscribe to a topic. The subscriber
| |
| createSubscriber | back to summary |
|---|---|
| public TopicSubscriber createSubscriber(Topic topic, String messageSelector, boolean noLocal) throws JMSException Creates a nondurable subscriber to the specified topic, using a message selector or specifying whether messages published by its own connection should be delivered to it.
A client uses a
Regular Messages filtered out by a subscriber's message selector will never be delivered to the subscriber. From the subscriber's perspective, they do not exist.
In some cases, a connection may both publish and subscribe to a topic. The subscriber
| |
| createTemporaryTopic | back to summary |
|---|---|
| public TemporaryTopic createTemporaryTopic() throws JMSException Redeclares jakarta. Creates a
| |
| createTopic | back to summary |
|---|---|
| public Topic createTopic(String topicName) throws JMSException Redeclares jakarta. Creates a topic identity given a This facility is provided for the rare cases where clients need to dynamically manipulate topic identity. This allows the creation of a topic identity with a provider-specific name. Clients that depend on this ability are not portable.
Note that this method is not for creating the physical topic. The physical creation of topics is an administrative
task and is not to be initiated by the Jakarta Messaging API. The one exception is the creation of temporary topics, which is
accomplished with the
| |
| unsubscribe | back to summary |
|---|---|
| public void unsubscribe(String name) throws JMSException Redeclares jakarta. Unsubscribes a durable subscription that has been created by a client. This method deletes the state being maintained on behalf of the subscriber by its provider.
It is erroneous for a client to delete a durable subscription while there is an active
| |