This section covers the topic-based API.
A
TemporaryTopic
is created by a
TopicSession
. A temporary topic is associated with
the connection that belongs to the TopicSession
that created it. It is only active for the duration of the
session's connection, and it is guaranteed to be unique across
all connections. Since it is temporary it can't be
durable—it lasts only as long as its associated client
connection is active. In all other respects it is just like a
"regular" topic. The TemporaryTopic
is
a subtype of the Topic
interface.
Since a temporary topic is created by a JMS client, it is unavailable
to other JMS clients unless the topic identity is transferred using
the JMSReplyTo
header. While any client may
publish messages on another client's temporary topic, only the
sessions that are associated with the JMS client connection that
created the temporary topic may subscribe to it. JMS clients can
also, of course, publish messages to their own temporary topics:
public interface TemporaryTopic extends Topic { public void delete( ) throws JMSException; }
The
Topic
is an
administered object that acts as a handle or identifier for an actual
topic, called a physical topic, on the messaging
server. A physical topic is a channel to which many clients can
subscribe and publish. When a JMS client delivers a
Message
object to a topic, all the clients
subscribed to that topic receive the Message
. The
Topic
is a subtype of the
Destination
interface:
public interface Topic extends Destination { public String getTopicName( ) throws JMSException; public String toString( ); }
The
TopicConnection
is created by the TopicConnectionFactory
. The
TopicConnection
represents a connection to the
message server. Each TopicConnection
created from
a TopicConnectionFactory
is a unique connection to
the server.[2] The
TopicConnection
is a subtype of the
Connection
interface:
public interface TopicConnection extends Connection { public TopicSession createTopicSession(boolean transacted, int acknowledgeMode) throws JMSException; public ConnectionConsumer createConnectionConsumer (Topic topic, String messageSelector, ServerSessionPool sessionPool, int maxMessages) throws JMSException; public ConnectionConsumer createDurableConnectionConsumer (Topic topic, String subscriptionName, String messageSelector, ServerSessionPool sessionPool, int maxMessages) throws JMSException; }
The
TopicConnectionFactory
is an administered object that is used to manufacture
TopicConnection
objects. The
TopicConnectionFactory
is a subtype of the
ConnectionFactory
interface:
public interface TopicConnectionFactory extends ConnectionFactory { public TopicConnection createTopicConnection( ) throws JMSException; public TopicConnection createTopicConnection(String username, String password) throws JMSException; }
A
TopicPublisher
is created by a TopicSession
, usually for a
specific Topic
. Messages that are sent by the
TopicPublisher
are copied and delivered to each
client subscribed to that topic. The
TopicPublisher
is a subtype of the
MessageProducer
interface:
public interface TopicPublisher extends MessageProducer { public Topic getTopic( ) throws JMSException; public void publish(Message message) throws JMSException; public void publish(Message message, int deliveryMode,int priority, long timeToLive) throws JMSException; public void publish(Topic topic,Message message) throws JMSException; public void publish(Topic topic, Message message, int deliveryMode, int priority,long timeToLive) throws JMSException; }
The
TopicSession
is created by the TopicConnection
. A
TopicSession
object is a factory for creating
Message
, TopicPublisher
, and
TopicSubscriber
objects. A client can create
multiple TopicSession
objects to provide more
granular control over publishers, subscribers, and their associated
transactions. The TopicSession
is a subtype of the
Session
interface:
public interface TopicSession extends Session { public Topic createTopic(java.lang.String topicName) throws JMSException; public TopicSubscriber createSubscriber(Topic topic) throws JMSException; public TopicSubscriber createSubscriber(Topic topic, String messageSelector, boolean noLocal) throws JMSException; public TopicSubscriber createDurableSubscriber(Topic topic, String name) throws JMSException; public TopicSubscriber createDurableSubscriber (Topic topic, String name, String messageSelector, boolean noLocal) throws JMSException; public TopicPublisher createPublisher(Topic topic) throws JMSException; public TemporaryTopic createTemporaryTopic( ) throws JMSException; public void unsubscribe(java.lang.String name) throws JMSException; }
The
TopicSubscriber
is created by a
TopicSession
for a specific topic. The messages
are delivered to the TopicSubscriber
as they
become available, avoiding the need to poll the topic for new
messages. The TopicSubscriber
is a subtype of the
MessageConsumer
interface:
public interface TopicSubscriber extends MessageConsumer public Topic getTopic( ) throws JMSException; public boolean getNoLocal( ) throws JMSException; }
[2] The actual physical network connection may or may not be unique, depending on the vendor. However, the connection is considered to be logically unique so authentication and connection control can be managed separately from other connections.