javax.jms
Interface TopicSubscriber

public interface TopicSubscriber

extends MessageConsumer

A client uses a TopicSubscriber for receiving messages that have been published to a topic. TopicSubscriber is the Pub/Sub variant of a JMS message consumer.

A topic session allows the creation of multiple topic subscriber's per Destination, it will deliver each message for a Destination to each topic subscriber eligible to receive it. Each copy of the message is treated as a completely separate message. Work done on one copy has no affect on the other; acknowledging one does not acknowledge the other; one message may be delivered immediately while another waits for its consumer to process messages ahead of it.

Regular TopicSubscriber's are not durable. They only receive messages that are published while they are active.

Messages filtered out by a subscriber's message selector will never be delivered to the subscriber. From the subscriber's perspective they simply don't exist.

In some cases, a connection may both publish and subscribe to a topic. The subscriber NoLocal attribute allows a subscriber to inhibit the delivery of messages published by its own connection.

If a client needs to receive all the messages published on a topic including the ones published while the subscriber is inactive, it uses a durable TopicSubscriber. JMS retains a record of this durable subscription and insures that all messages from the topic's publishers are retained until they are either acknowledged by this durable subscriber or they have expired.

Sessions with durable subscribers must always provide the same client identifier. In addition, each client must specify a name which uniquely identifies (within client identifier) each durable subscription it creates. Only one session at a time can have a TopicSubscriber for a particular durable subscription.

A client can change an existing durable subscription by creating a durable TopicSubscriber with the same name and a new topic and/or message selector. Changing a durable subscription is equivalent to deleting and recreating it.

TopicSessions provide the unsubscribe method for deleting a durable subscription created by their client. This deletes the state being maintained on behalf of the subscriber by its provider.

Version:

1.0 - 7 August 1998

Author:

Mark Hapner, Rich Burridge

See Also:

TopicSession, TopicSession.createSubscriber(Topic), TopicSession.createSubscriber(Topic, String, boolean), TopicSession.createDurableSubscriber(Topic, String), TopicSession.createDurableSubscriber(Topic, String, String, boolean), MessageConsumer

Method Summary

boolean	getNoLocal() Get the NoLocal attribute for this TopicSubscriber.
Topic	getTopic() Get the topic associated with this subscriber.

Methods inherited from interface javax.jms.MessageConsumer

close, getMessageListener, getMessageSelector, receive, receive, receiveNoWait, setMessageListener

Method Detail

getTopic

public Topic getTopic()
               throws JMSException

Get the topic associated with this subscriber.

Returns:

this subscriber's topic

Throws:

JMSException - if JMS fails to get topic for this topic subscriber due to some internal error.

getNoLocal

public boolean getNoLocal()
                   throws JMSException

Get the NoLocal attribute for this TopicSubscriber. The default value for this attribute is false.

Returns:

set to true if locally published messages are being inhibited.

Throws:

JMSException - if JMS fails to get noLocal attribute for this topic subscriber due to some internal error.