MessageProducer (Java EE 5)

MessageProducer 是所有消息生成方的父接口。

客户端还可以选择创建消息生成方时不提供目的地。在这种情况下，每次发送操作都必须提供目的地。此类消息生成方通常用于使用请求的 JMSReplyTo 目的地向请求发送应答。

客户端可以为消息生成方发送的消息指定默认传送模式、优先级和生存时间。它还可以为单个消息指定传送模式、优先级和生存时间。

客户端可以为其发送的每个消息指定以毫秒为单位的生存时间。此值将消息到期时间定义为消息的生存时间值和消息发送时（对于事务性发送，这是客户端发送消息的时间，不是提交事务的时间）的 GMT 之和。

JMS 提供者应可能精确地终止消息；但是，JMS API 不定义提供的精确度。

A client uses a MessageProducer object to send messages to a destination. A MessageProducer object is created by passing a Destination object to a message-producer creation method supplied by a session.

MessageProducer is the parent interface for all message producers.

A client also has the option of creating a message producer without supplying a destination. In this case, a destination must be provided with every send operation. A typical use for this kind of message producer is to send replies to requests using the request's JMSReplyTo destination.

A client can specify a default delivery mode, priority, and time to live for messages sent by a message producer. It can also specify the delivery mode, priority, and time to live for an individual message.

A client can specify a time-to-live value in milliseconds for each message it sends. This value defines a message expiration time that is the sum of the message's time-to-live and the GMT when it is sent (for transacted sends, this is the time the client sends the message, not the time the transaction is committed).

A JMS provider should do its best to expire messages accurately; however, the JMS API does not define the accuracy provided.

Version:

1.1 - February 2, 2002

Author:

Mark Hapner, Rich Burridge, Kate Stout

See Also:

TopicPublisher, QueueSender, Session.createProducer(javax.jms.Destination)

public void setDisableMessageID(boolean value) throws JMSException
设置是否禁用消息 ID。

由于消息 ID 会创建并增加消息的大小，因此，如果能获得应用程序无需使用消息 ID 的提示，那么一些 JMS 提供者可以优化消息开销。通过对此消息生成方调用 setDisableMessageID 方法，JMS 客户端对此消息生成方发送的所有消息实现了这一潜在的优化。如果 JMS 提供者接受此提示，则这些消息必须将消息 ID 设置为 null；如果提供者忽略该提示，则消息 ID 必须设置为唯一的普通值。

默认情况下启用消息 ID。

value	指示是否禁用消息 ID
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法将消息 ID 设置为禁用。

英文文档：

setDisableMessageID

void setDisableMessageID(boolean value)
                         throws JMSException

Sets whether message IDs are disabled.

Since message IDs take some effort to create and increase a message's size, some JMS providers may be able to optimize message overhead if they are given a hint that the message ID is not used by an application. By calling the setDisableMessageID method on this message producer, a JMS client enables this potential optimization for all messages sent by this message producer. If the JMS provider accepts this hint, these messages must have the message ID set to null; if the provider ignores the hint, the message ID must be set to its normal unique value.

Message IDs are enabled by default.

Parameters:

value - indicates if message IDs are disabled

Throws:

JMSException - if the JMS provider fails to set message ID to disabled due to some internal error.

public boolean getDisableMessageID() throws JMSException
获取是否禁用消息 ID 的指示。

return	是否禁用消息 ID 的指示
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法确定是否禁用消息 ID。

英文文档：

getDisableMessageID

boolean getDisableMessageID()
                            throws JMSException

Gets an indication of whether message IDs are disabled.

Returns:

an indication of whether message IDs are disabled

Throws:

JMSException - if the JMS provider fails to determine if message IDs are disabled due to some internal error.

public void setDisableMessageTimestamp(boolean value) throws JMSException
设置是否禁用消息时间戳。

由于时间戳会创建并增加消息的大小，因此，如果能获得应用程序无需使用时间戳的提示，那么一些 JMS 提供者可以优化消息开销。通过对此消息生成方调用 setDisableMessageTimestamp 方法，JMS 客户端对此消息生成方发送的所有消息实现了这一潜在的优化。如果 JMS 提供者接受此提示，这些消息必须将时间戳设置为 0；如果提供者忽略该提示，则时间戳必须设置为普通值。

默认情况下启用消息时间戳。

value	指示是否禁用消息时间戳
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法将时间戳设置为禁用。

英文文档：

setDisableMessageTimestamp

void setDisableMessageTimestamp(boolean value)
                                throws JMSException

Sets whether message timestamps are disabled.

Since timestamps take some effort to create and increase a message's size, some JMS providers may be able to optimize message overhead if they are given a hint that the timestamp is not used by an application. By calling the setDisableMessageTimestamp method on this message producer, a JMS client enables this potential optimization for all messages sent by this message producer. If the JMS provider accepts this hint, these messages must have the timestamp set to zero; if the provider ignores the hint, the timestamp must be set to its normal value.

Message timestamps are enabled by default.

Parameters:

value - indicates if message timestamps are disabled

Throws:

JMSException - if the JMS provider fails to set timestamps to disabled due to some internal error.

public boolean getDisableMessageTimestamp() throws JMSException
获取是否禁用消息时间戳的指示。

return	是否禁用消息时间戳的指示
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法确定是否禁用时间戳。

英文文档：

getDisableMessageTimestamp

boolean getDisableMessageTimestamp()
                                   throws JMSException

Gets an indication of whether message timestamps are disabled.

Returns:

an indication of whether message timestamps are disabled

Throws:

JMSException - if the JMS provider fails to determine if timestamps are disabled due to some internal error.

public void setDeliveryMode(int deliveryMode) throws JMSException
设置生成方的默认传送模式。

默认情况下传送模式设置为 PERSISTENT。

deliveryMode	此消息生成方的消息传送模式；合法值有 DeliveryMode.NON_PERSISTENT 和 DeliveryMode.PERSISTENT
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法设置传送模式。
See also	getDeliveryMode, NON_PERSISTENT, PERSISTENT, DEFAULT_DELIVERY_MODE

英文文档：

setDeliveryMode

void setDeliveryMode(int deliveryMode)
                     throws JMSException

Sets the producer's default delivery mode.

Delivery mode is set to PERSISTENT by default.

Parameters:

deliveryMode - the message delivery mode for this message producer; legal values are DeliveryMode.NON_PERSISTENT and DeliveryMode.PERSISTENT

Throws:

JMSException - if the JMS provider fails to set the delivery mode due to some internal error.

See Also:

getDeliveryMode(), DeliveryMode.NON_PERSISTENT, DeliveryMode.PERSISTENT, Message.DEFAULT_DELIVERY_MODE

public int getDeliveryMode() throws JMSException
获取生成方的默认传送模式。

return	此消息生成方的消息传送模式
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法获取传送模式。
See also	setDeliveryMode

英文文档：

getDeliveryMode

int getDeliveryMode()
                    throws JMSException

Gets the producer's default delivery mode.

Returns:

the message delivery mode for this message producer

Throws:

JMSException - if the JMS provider fails to get the delivery mode due to some internal error.

See Also:

setDeliveryMode(int)

public void setPriority(int defaultPriority) throws JMSException
设置生成方的默认优先级。

JMS API 定义 10 个优先级值，0 表示最低优先级，9 表示最高优先级。客户端应考虑将优先级 0-4 作为正常优先级等级，将优先级 5-9 作为加速优先级等级。默认情况下优先级设置为 4。

defaultPriority	此消息生成方的消息优先级；必须是介于 0 和 9 之间的值
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法设置优先级。
See also	getPriority, DEFAULT_PRIORITY

英文文档：

setPriority

void setPriority(int defaultPriority)
                 throws JMSException

Sets the producer's default priority.

The JMS API defines ten levels of priority value, with 0 as the lowest priority and 9 as the highest. Clients should consider priorities 0-4 as gradations of normal priority and priorities 5-9 as gradations of expedited priority. Priority is set to 4 by default.

Parameters:

defaultPriority - the message priority for this message producer; must be a value between 0 and 9

Throws:

JMSException - if the JMS provider fails to set the priority due to some internal error.

See Also:

getPriority(), Message.DEFAULT_PRIORITY

public int getPriority() throws JMSException
获取生成方的默认优先级。

return	此消息生成方的消息优先级
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法获取优先级。
See also	setPriority

英文文档：

getPriority

int getPriority()
                throws JMSException

Gets the producer's default priority.

Returns:

the message priority for this message producer

Throws:

JMSException - if the JMS provider fails to get the priority due to some internal error.

See Also:

setPriority(int)

public void setTimeToLive(long timeToLive) throws JMSException
设置从消息指派时间算起消息系统应该保留已生产消息的默认时间长度（以毫秒为单位）。

默认情况下生存时间设置为 0。

timeToLive	消息生存时间（以毫秒为单位）；0 表示生存时间未限定
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法设置生存时间。
See also	getTimeToLive, DEFAULT_TIME_TO_LIVE

英文文档：

setTimeToLive

void setTimeToLive(long timeToLive)
                   throws JMSException

Sets the default length of time in milliseconds from its dispatch time that a produced message should be retained by the message system.

Time to live is set to zero by default.

Parameters:

timeToLive - the message time to live in milliseconds; zero is unlimited

Throws:

JMSException - if the JMS provider fails to set the time to live due to some internal error.

See Also:

getTimeToLive(), Message.DEFAULT_TIME_TO_LIVE

public long getTimeToLive() throws JMSException
获取从消息指派时间算起消息系统应该保留已生产消息的默认时间长度（以毫秒为单位）。

return	消息生存时间（以毫秒为单位）；0 表示生存时间未限定
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法获取生存时间。
See also	setTimeToLive

英文文档：

getTimeToLive

long getTimeToLive()
                   throws JMSException

Gets the default length of time in milliseconds from its dispatch time that a produced message should be retained by the message system.

Returns:

the message time to live in milliseconds; zero is unlimited

Throws:

JMSException - if the JMS provider fails to get the time to live due to some internal error.

See Also:

setTimeToLive(long)

public Destination getDestination() throws JMSException
获取与此 MessageProducer 关联的目的地。

return	此生成方的 Destination/
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法获取此 MessageProduce 的目的地。
since	1.1

英文文档：

getDestination

Destination getDestination()
                           throws JMSException

Gets the destination associated with this MessageProducer.

Returns:

this producer's Destination/

Throws:

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

Since:

1.1

public void close() throws JMSException
关闭消息生成方。

由于提供者可以在 Java 虚拟机外部为 MessageProducer 分配一些资源，因此不需要时客户端应该关闭这些资源。依赖于垃圾收集最终回收这些资源可能不够及时。

Throws

JMSException: 如果 JMS 提供者由于某个内部错误无法关闭生成方。

英文文档：

close

void close()
           throws JMSException

Closes the message producer.

Since a provider may allocate some resources on behalf of a MessageProducer outside the Java virtual machine, clients should close them when they are not needed. Relying on garbage collection to eventually reclaim these resources may not be timely enough.

Throws:

JMSException - if the JMS provider fails to close the producer due to some internal error.

public void send(Message message) throws JMSException
使用 MessageProducer 的默认传送模式、优先级和生存时间发送消息。

message	要发送的消息
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法发送消息。
Throws	MessageFormatException: 如果指定了无效的消息。
Throws	InvalidDestinationException: 如果客户端使用此方法，而其 MessageProducer 带有无效目的地。
Throws	UnsupportedOperationException: 如果客户端使用此方法，而其 MessageProducer 在创建时没有指定目的地。
since	1.1
See also	createProducer, javax.jms.MessageProducer

英文文档：

send

void send(Message message)
          throws JMSException

Sends a message using the MessageProducer's default delivery mode, priority, and time to live.

Parameters:

message - the message to send

Throws:

JMSException - if the JMS provider fails to send the message due to some internal error.

MessageFormatException - if an invalid message is specified.

InvalidDestinationException - if a client uses this method with a MessageProducer with an invalid destination.

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

Since:

1.1

See Also:

Session.createProducer(javax.jms.Destination), MessageProducer

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

message	要发送的消息
deliveryMode	要使用的传送模式
priority	此消息的优先级
timeToLive	消息的生命周期（以毫秒为单位）
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法发送消息。
Throws	MessageFormatException: 如果指定了无效的消息。
Throws	InvalidDestinationException: 如果客户端使用此方法，而其 MessageProducer 带有无效目的地。
Throws	UnsupportedOperationException: 如果客户端使用此方法，而其 MessageProducer 在创建时没有指定目的地。
since	1.1
See also	createProducer

英文文档：

send

void send(Message message,
          int deliveryMode,
          int priority,
          long timeToLive)
          throws JMSException

Sends a message to the destination, specifying delivery mode, priority, and time to live.

Parameters:

message - the message to send

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 send the message due to some internal error.

MessageFormatException - if an invalid message is specified.

InvalidDestinationException - if a client uses this method with a MessageProducer with an invalid destination.

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

Since:

1.1

See Also:

Session.createProducer(javax.jms.Destination)

public void send(Destination destination, Message message) throws JMSException
为未标识的消息生成方将消息发送到目的地。使用 MessageProducer 的默认传送模式、优先级和生存时间。

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

destination	此消息要发送到的目的地
message	要发送的消息
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法发送消息。
Throws	MessageFormatException: 如果指定了无效的消息。
Throws	InvalidDestinationException: 如果客户端使用带无效目的地的此方法。
Throws	UnsupportedOperationException: 如果客户端使用此方法，其 MessageProducer 在创建时指定了目的地。
since	1.1
See also	createProducer, javax.jms.MessageProducer

英文文档：

send

void send(Destination destination,
          Message message)
          throws JMSException

Sends a message to a destination for an unidentified message producer. Uses the MessageProducer's default delivery mode, priority, and time to live.

Typically, a message producer is assigned a destination at creation time; however, the JMS API also supports unidentified message producers, which require that the destination be supplied every time a message is sent.

Parameters:

destination - the destination to send this message to

message - the message to send

Throws:

JMSException - if the JMS provider fails to send the message due to some internal error.

MessageFormatException - if an invalid message is specified.

InvalidDestinationException - if a client uses this method with an invalid destination.

UnsupportedOperationException - if a client uses this method with a MessageProducer that specified a destination at creation time.

Since:

1.1

See Also:

Session.createProducer(javax.jms.Destination), MessageProducer

public void send(Destination destination, Message message, int deliveryMode, int priority, long timeToLive) throws JMSException
为未标识的消息生成方将消息发送到目的地，同时指定传送模式、优先级和生存时间。

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

destination	此消息要发送到的目的地
message	要发送的消息
deliveryMode	要使用的传送模式
priority	此消息的优先级
timeToLive	消息的生命周期（以毫秒为单位）
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法发送消息。
Throws	MessageFormatException: 如果指定了无效的消息。
Throws	InvalidDestinationException: 如果客户端使用带无效目的地的此方法。
since	1.1
See also	createProducer

英文文档：

send

void send(Destination destination,
          Message message,
          int deliveryMode,
          int priority,
          long timeToLive)
          throws JMSException

Sends a message to a destination for an unidentified message producer, specifying delivery mode, priority and time to live.

Typically, a message producer is assigned a destination at creation time; however, the JMS API also supports unidentified message producers, which require that the destination be supplied every time a message is sent.

Parameters:

destination - the destination to send this message to

message - the message to send

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 send the message due to some internal error.

MessageFormatException - if an invalid message is specified.

InvalidDestinationException - if a client uses this method with an invalid destination.

Since:

1.1

See Also:

Session.createProducer(javax.jms.Destination)

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