-
- All Superinterfaces:
AutoCloseable
,MessageProducer
public interface TopicPublisher extends MessageProducer
A client uses aTopicPublisher
object to publish messages on a topic. ATopicPublisher
object is the publish-subscribe form of a message producer.Normally, the
Topic
is specified when aTopicPublisher
is created. In this case, an attempt to use thepublish
methods for an unidentifiedTopicPublisher
will throw ajava.lang.UnsupportedOperationException
.If the
TopicPublisher
is created with an unidentifiedTopic
, an attempt to use thepublish
methods that assume that theTopic
has been identified will throw ajava.lang.UnsupportedOperationException
.During the execution of its
publish
method, a message must not be changed by other threads within the client. If the message is modified, the result of thepublish
is undefined.After publishing a message, a client may retain and modify it without affecting the message that has been published. The same message object may be published multiple times.
The following message headers are set as part of publishing a message:
JMSDestination
,JMSDeliveryMode
,JMSExpiration
,JMSPriority
,JMSMessageID
andJMSTimeStamp
. When the message is published, the values of these headers are ignored. After completion of thepublish
, the headers hold the values specified by the method publishing the message. It is possible for thepublish
method not to setJMSMessageID
andJMSTimeStamp
if the setting of these headers is explicitly disabled by theMessageProducer.setDisableMessageID
orMessageProducer.setDisableMessageTimestamp
method.Creating a
MessageProducer
provides the same features as creating aTopicPublisher
. AMessageProducer
object is recommended when creating new code. TheTopicPublisher
is provided to support existing code.Because
TopicPublisher
inherits fromMessageProducer
, it inherits thesend
methods that are a part of theMessageProducer
interface. Using thesend
methods will have the same effect as using thepublish
methods: they are functionally the same.- Since:
- JMS 1.0
- Version:
- Jakarta Messaging 2.0
- See Also:
Session.createProducer(Destination)
,TopicSession.createPublisher(Topic)
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description Topic
getTopic()
Gets the topic associated with thisTopicPublisher
.void
publish(Message message)
Publishes a message to the topic.void
publish(Message message, int deliveryMode, int priority, long timeToLive)
Publishes a message to the topic, specifying delivery mode, priority, and time to live.void
publish(Topic topic, Message message)
Publishes a message to a topic for an unidentified message producer.void
publish(Topic topic, Message message, int deliveryMode, int priority, long timeToLive)
Publishes a message to a topic for an unidentified message producer, specifying delivery mode, priority and time to live.-
Methods inherited from interface jakarta.jms.MessageProducer
close, getDeliveryDelay, getDeliveryMode, getDestination, getDisableMessageID, getDisableMessageTimestamp, getPriority, getTimeToLive, send, send, send, send, send, send, send, send, setDeliveryDelay, setDeliveryMode, setDisableMessageID, setDisableMessageTimestamp, setPriority, setTimeToLive
-
-
-
-
Method Detail
-
getTopic
Topic getTopic() throws JMSException
Gets the topic associated with thisTopicPublisher
.- Returns:
- this publisher's topic
- Throws:
JMSException
- if the Jakarta Messaging provider fails to get the topic for thisTopicPublisher
due to some internal error.
-
publish
void publish(Message message) throws JMSException
Publishes a message to the topic. Uses theTopicPublisher
's default delivery mode, priority, and time to live.- Parameters:
message
- the message to publish- Throws:
JMSException
- if the Jakarta Messaging provider fails to publish the message due to some internal error.MessageFormatException
- if an invalid message is specified.InvalidDestinationException
- if a client uses this method with aTopicPublisher
with an invalid topic.UnsupportedOperationException
- if a client uses this method with aTopicPublisher
that did not specify a topic at creation time.- See Also:
MessageProducer.getDeliveryMode()
,MessageProducer.getTimeToLive()
,MessageProducer.getPriority()
-
publish
void publish(Message message, int deliveryMode, int priority, long timeToLive) throws JMSException
Publishes a message to the topic, specifying delivery mode, priority, and time to live.- Parameters:
message
- the message to publishdeliveryMode
- the delivery mode to usepriority
- the priority for this messagetimeToLive
- the message's lifetime (in milliseconds)- Throws:
JMSException
- if the Jakarta Messaging provider fails to publish the message due to some internal error.MessageFormatException
- if an invalid message is specified.InvalidDestinationException
- if a client uses this method with aTopicPublisher
with an invalid topic.UnsupportedOperationException
- if a client uses this method with aTopicPublisher
that did not specify a topic at creation time.
-
publish
void publish(Topic topic, Message message) throws JMSException
Publishes a message to a topic for an unidentified message producer. Uses theTopicPublisher
's default delivery mode, priority, and time to live.Typically, a message producer is assigned a topic at creation time; however, the Jakarta Messaging API also supports unidentified message producers, which require that the topic be supplied every time a message is published.
- Parameters:
topic
- the topic to publish this message tomessage
- the message to publish- Throws:
JMSException
- if the Jakarta Messaging provider fails to publish the message due to some internal error.MessageFormatException
- if an invalid message is specified.InvalidDestinationException
- if a client uses this method with an invalid topic.- See Also:
MessageProducer.getDeliveryMode()
,MessageProducer.getTimeToLive()
,MessageProducer.getPriority()
-
publish
void publish(Topic topic, Message message, int deliveryMode, int priority, long timeToLive) throws JMSException
Publishes a message to a topic for an unidentified message producer, specifying delivery mode, priority and time to live.Typically, a message producer is assigned a topic at creation time; however, the Jakarta Messaging API also supports unidentified message producers, which require that the topic be supplied every time a message is published.
- Parameters:
topic
- the topic to publish this message tomessage
- the message to publishdeliveryMode
- the delivery mode to usepriority
- the priority for this messagetimeToLive
- the message's lifetime (in milliseconds)- Throws:
JMSException
- if the Jakarta Messaging provider fails to publish the message due to some internal error.MessageFormatException
- if an invalid message is specified.InvalidDestinationException
- if a client uses this method with an invalid topic.
-
-