MessageProducer (Java EE 5)

Java EE API

previous page next page
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.jms Interface MessageProducer

All Known Subinterfaces:
QueueSender, TopicPublisher
public interface MessageProducer

Implemented by: QueueSender, TopicPublisher

客户端使用 MessageProducer 对象将消息发送到目的地。通过将 Destination 对象传递到会话提供的消息-生成方创建方法，即可创建 MessageProducer 对象。

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

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

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

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

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

version
en
1.1 - February 2, 2002
See also javax.jms.TopicPublisher, javax.jms.QueueSender, createProducer

英文文档：

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)

Method Summary
 void close()
          Closes the message producer.
 int getDeliveryMode()
          Gets the producer's default delivery mode.
 Destination getDestination()
          Gets the destination associated with this MessageProducer.
 boolean getDisableMessageID()
          Gets an indication of whether message IDs are disabled.
 boolean getDisableMessageTimestamp()
          Gets an indication of whether message timestamps are disabled.
 int getPriority()
          Gets the producer's default priority.
 long getTimeToLive()
          Gets the default length of time in milliseconds from its dispatch time that a produced message should be retained by the message system.
 void send(Destination destination, Message message)
          Sends a message to a destination for an unidentified message producer.
 void send(Destination destination, Message message, int deliveryMode, int priority, long timeToLive)
          Sends a message to a destination for an unidentified message producer, specifying delivery mode, priority and time to live.
 void send(Message message)
          Sends a message using the MessageProducer's default delivery mode, priority, and time to live.
 void send(Message message, int deliveryMode, int priority, long timeToLive)
          Sends a message to the destination, specifying delivery mode, priority, and time to live.
 void setDeliveryMode(int deliveryMode)
          Sets the producer's default delivery mode.
 void setDisableMessageID(boolean value)
          Sets whether message IDs are disabled.
 void setDisableMessageTimestamp(boolean value)
          Sets whether message timestamps are disabled.
 void setPriority(int defaultPriority)
          Sets the producer's default priority.
 void setTimeToLive(long timeToLive)
          Sets the default length of time in milliseconds from its dispatch time that a produced message should be retained by the message system.
 

Method Detail

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

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

默认情况下启用消息 ID。

value 指示是否禁用消息 ID
ThrowsJMSException: 如果 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 的指示
ThrowsJMSException: 如果 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 指示是否禁用消息时间戳
ThrowsJMSException: 如果 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 是否禁用消息时间戳的指示
ThrowsJMSException: 如果 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
ThrowsJMSException: 如果 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 此消息生成方的消息传送模式
ThrowsJMSException: 如果 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 之间的值
ThrowsJMSException: 如果 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 此消息生成方的消息优先级
ThrowsJMSException: 如果 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 表示生存时间未限定
ThrowsJMSException: 如果 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 表示生存时间未限定
ThrowsJMSException: 如果 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/
ThrowsJMSException: 如果 JMS 提供者由于某个内部错误无法获取此 MessageProduce 的目的地。
since1.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 分配一些资源，因此不需要时客户端应该关闭这些资源。依赖于垃圾收集最终回收这些资源可能不够及时。

ThrowsJMSException: 如果 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 要发送的消息
ThrowsJMSException: 如果 JMS 提供者由于某个内部错误无法发送消息。
ThrowsMessageFormatException: 如果指定了无效的消息。
ThrowsInvalidDestinationException: 如果客户端使用此方法，而其 MessageProducer 带有无效目的地。
ThrowsUnsupportedOperationException: 如果客户端使用此方法，而其 MessageProducer 在创建时没有指定目的地。
since1.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 消息的生命周期（以毫秒为单位）
ThrowsJMSException: 如果 JMS 提供者由于某个内部错误无法发送消息。
ThrowsMessageFormatException: 如果指定了无效的消息。
ThrowsInvalidDestinationException: 如果客户端使用此方法，而其 MessageProducer 带有无效目的地。
ThrowsUnsupportedOperationException: 如果客户端使用此方法，而其 MessageProducer 在创建时没有指定目的地。
since1.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 要发送的消息
ThrowsJMSException: 如果 JMS 提供者由于某个内部错误无法发送消息。
ThrowsMessageFormatException: 如果指定了无效的消息。
ThrowsInvalidDestinationException: 如果客户端使用带无效目的地的此方法。
ThrowsUnsupportedOperationException: 如果客户端使用此方法，其 MessageProducer 在创建时指定了目的地。
since1.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 消息的生命周期（以毫秒为单位）
ThrowsJMSException: 如果 JMS 提供者由于某个内部错误无法发送消息。
ThrowsMessageFormatException: 如果指定了无效的消息。
ThrowsInvalidDestinationException: 如果客户端使用带无效目的地的此方法。
since1.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)
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature

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

一看就知道只有菜鸟才干这么无知的事啦。

PS : 未经我党受权你也可自由散发此文档。 如有任何错误请自行修正；若因此而造成任何损失请直接找人民主席，请勿与本人联系。谢谢！

previous page start next page