TopicPublisher (Java EE 5)

通常，Topic 是在创建 TopicPublisher 时指定的。在这种情况下，尝试使用未标识的 TopicPublisher 的 publish 方法将抛出 java.lang.UnsupportedOperationException。

如果使用未标识的 Topic 创建 TopicPublisher，则尝试使用假定 Topic 已标识的 publish 方法将抛出 java.lang.UnsupportedOperationException。

在执行其 publish 方法期间，客户端内的其他线程不得更改消息。如果修改了消息，则 publish 的结果是不确定的。

消息发布后，客户端可以保留并修改它，而不会影响已经发布的消息。同一个消息对象可以被发布多次。

以下消息头作为发布消息的一部分设置：JMSDestination、JMSDeliveryMode、JMSExpiration、JMSPriority、JMSMessageID 和 JMSTimeStamp。发布消息时，忽略这些消息头的值。publish 完成后，这些消息头保持发布该消息的方法指定的值。如果通过 MessageProducer.setDisableMessageID 或 MessageProducer.setDisableMessageTimestamp 方法显式禁用了这些消息头的该设置，则 publish 方法可以不设置 JMSMessageID 和 JMSTimeStamp。

创建 MessageProducer 所提供的功能与创建 TopicPublisher 所提供的功能相同。创建新代码时建议使用 MessageProducer 对象。提供 TopicPublisher 的目的是支持现有代码。

因为 TopicPublisher 继承自 MessageProducer，所以它继承作为 MessageProducer 接口一部分的 send 方法。使用 send 方法与使用 publish 方法的效果相同：它们在功能上相同。

A client uses a TopicPublisher object to publish messages on a topic. A TopicPublisher object is the publish-subscribe form of a message producer.

Normally, the Topic is specified when a TopicPublisher is created. In this case, an attempt to use the publish methods for an unidentified TopicPublisher will throw a java.lang.UnsupportedOperationException.

If the TopicPublisher is created with an unidentified Topic, an attempt to use the publish methods that assume that the Topic has been identified will throw a java.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 the publish 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 and JMSTimeStamp. When the message is published, the values of these headers are ignored. After completion of the publish, the headers hold the values specified by the method publishing the message. It is possible for the publish method not to set JMSMessageID and JMSTimeStamp if the setting of these headers is explicitly disabled by the MessageProducer.setDisableMessageID or MessageProducer.setDisableMessageTimestamp method.

Creating a MessageProducer provides the same features as creating a TopicPublisher. A MessageProducer object is recommended when creating new code. The TopicPublisher is provided to support existing code.

Because TopicPublisher inherits from MessageProducer, it inherits the send methods that are a part of the MessageProducer interface. Using the send methods will have the same effect as using the publish methods: they are functionally the same.

Version:

1.1 February 2, 2002

Author:

Mark Hapner, Rich Burridge, Kate Stout

See Also:

Session.createProducer(Destination), TopicSession.createPublisher(Topic)

public Topic getTopic() throws JMSException
获取与此 TopicPublisher 相关的主题。

return	此发布者的主题
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法获取此 TopicPublisher 的主题。

英文文档：

getTopic

Topic getTopic()
               throws JMSException

Gets the topic associated with this TopicPublisher.

Returns:

this publisher's topic

Throws:

JMSException - if the JMS provider fails to get the topic for this TopicPublisher due to some internal error.

public void publish(Message message) throws JMSException
将消息发布到主题。使用 TopicPublisher 的默认传送模式、优先级和生存时间。

message	要发布的消息
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法发布消息。
Throws	MessageFormatException: 如果指定了无效的消息。
Throws	InvalidDestinationException: 如果客户端将此方法与带有无效主题的 TopicPublisher 一起使用。
Throws	UnsupportedOperationException: 如果客户端将此方法与在创建时未指定主题的 TopicPublisher 一起使用。
See also	getDeliveryMode(), getTimeToLive(), getPriority()

英文文档：

publish

void publish(Message message)
             throws JMSException

Publishes a message to the topic. Uses the TopicPublisher's default delivery mode, priority, and time to live.

Parameters:

message - the message to publish

Throws:

JMSException - if the JMS 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 a TopicPublisher with an invalid topic.

UnsupportedOperationException - if a client uses this method with a TopicPublisher that did not specify a topic at creation time.

See Also:

MessageProducer.getDeliveryMode(), MessageProducer.getTimeToLive(), MessageProducer.getPriority()

public void publish(Message message, int deliveryMode, int priority, long timeToLive) throws JMSException
将消息发布到主题，指定传送模式、优先级和生存时间。

message	要发布的消息
deliveryMode	要使用的传送模式
priority	此消息的优先级
timeToLive	消息的生命周期（以毫秒为单位）
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法发布消息。
Throws	MessageFormatException: 如果指定了无效的消息。
Throws	InvalidDestinationException: 如果客户端将此方法与带有无效主题的 TopicPublisher 一起使用。
Throws	UnsupportedOperationException: 如果客户端将此方法与在创建时未指定主题的 TopicPublisher 一起使用。

英文文档：

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 publish

deliveryMode - the delivery mode to use

priority - the priority for this message

timeToLive - the message's lifetime (in milliseconds)

Throws:

JMSException - if the JMS 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 a TopicPublisher with an invalid topic.

UnsupportedOperationException - if a client uses this method with a TopicPublisher that did not specify a topic at creation time.

public void publish(Topic topic, Message message) throws JMSException
将消息发布到未标识的消息生成方的主题。使用 TopicPublisher 的默认传送模式、优先级和生存时间。

通常，在创建时为消息生成方分配一个主题；但是，JMS API 也支持未标识的消息生成方，这需要在每次发布消息时提供主题。

topic	要将此消息发布到的主题
message	要发布的消息
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法发布消息。
Throws	MessageFormatException: 如果指定了无效的消息。
Throws	InvalidDestinationException: 如果客户端将此方法与无效主题一起使用。
See also	getDeliveryMode(), getTimeToLive(), getPriority()

英文文档：

publish

void publish(Topic topic,
             Message message)
             throws JMSException

Publishes a message to a topic for an unidentified message producer. Uses the TopicPublisher's default delivery mode, priority, and time to live.

Typically, a message producer is assigned a topic at creation time; however, the JMS 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 to

message - the message to publish

Throws:

JMSException - if the JMS 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()

public void publish(Topic topic, Message message, int deliveryMode, int priority, long timeToLive) throws JMSException
将消息发布到未标识的消息生成方的主题，指定传送模式、优先级和生存时间。

通常，在创建时为消息生成方分配一个主题；但是，JMS API 也支持未标识的消息生成方，这需要在每次发布消息时提供主题。

topic	要将此消息发布到的主题
message	要发布的消息
deliveryMode	要使用的传送模式
priority	此消息的优先级
timeToLive	消息的生命周期（以毫秒为单位）
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法发布消息。
Throws	MessageFormatException: 如果指定了无效的消息。
Throws	InvalidDestinationException: 如果客户端将此方法与无效主题一起使用。

英文文档：

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 JMS 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 to

message - the message to publish

deliveryMode - the delivery mode to use

priority - the priority for this message

timeToLive - the message's lifetime (in milliseconds)

Throws:

JMSException - if the JMS 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.

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.