MessageConsumer (Java EE 5)

MessageConsumer 是所有消息使用方的父接口。

可以使用消息选择器创建消息使用方。消息选择器使客户端能够将传送到消息使用方的消息限定为匹配该选择器的消息。

客户端可以同步接收消息使用方的消息或让使用方异步传送到达的消息。

对于同步接收，客户端可以使用其 receive 方法之一请求消息使用方的下一消息。有几种不同的 receive 方法可允许客户端轮询或等待下一消息。

对于异步传送，客户端可以向消息使用方注册一个 MessageListener 对象。当消息到达消息使用方时，它通过调用 MessageListener 的 onMessage 方法来传送消息。

如果 MessageListener 抛出异常，则是一个客户端编程错误。

A client uses a MessageConsumer object to receive messages from a destination. A MessageConsumer object is created by passing a Destination object to a message-consumer creation method supplied by a session.

MessageConsumer is the parent interface for all message consumers.

A message consumer can be created with a message selector. A message selector allows the client to restrict the messages delivered to the message consumer to those that match the selector.

A client may either synchronously receive a message consumer's messages or have the consumer asynchronously deliver them as they arrive.

For synchronous receipt, a client can request the next message from a message consumer using one of its receive methods. There are several variations of receive that allow a client to poll or wait for the next message.

For asynchronous delivery, a client can register a MessageListener object with a message consumer. As messages arrive at the message consumer, it delivers them by calling the MessageListener's onMessage method.

It is a client programming error for a MessageListener to throw an exception.

Version:

1.0 - 13 March 1998

Author:

Mark Hapner, Rich Burridge

See Also:

QueueReceiver, TopicSubscriber, Session

public String getMessageSelector() throws JMSException
获取此消息使用方的消息选择器表达式。

return	此消息使用方的消息选择器；如果消息使用方的消息选择器不存在（即如果没有设置消息选择器，或者设置为 null 或空字符串），则返回 null
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法获取消息选择器。

英文文档：

getMessageSelector

String getMessageSelector()
                          throws JMSException

Gets this message consumer's message selector expression.

Returns:

this message consumer's message selector, or null if no message selector exists for the message consumer (that is, if the message selector was not set or was set to null or the empty string)

Throws:

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

public MessageListener getMessageListener() throws JMSException
获取消息使用方的 MessageListener。

return	消息使用方的侦听器；如果没有设置侦听器，则返回 null
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法获取消息侦听器。
See also	setMessageListener

英文文档：

getMessageListener

MessageListener getMessageListener()
                                   throws JMSException

Gets the message consumer's MessageListener.

Returns:

the listener for the message consumer, or null if no listener is set

Throws:

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

See Also:

setMessageListener(javax.jms.MessageListener)

public void setMessageListener(MessageListener listener) throws JMSException
设置消息使用方的 MessageListener。

将消息侦听器设置为 null 等效于取消为消息使用方设置的消息侦听器。

当现有侦听器正在使用消息或使用方正用于同步使用消息时，调用 MessageConsumer.setMessageListener 的效果是不确定的。

listener	要接收消息的侦听器
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法设置消息侦听器。
See also	getMessageListener

英文文档：

setMessageListener

void setMessageListener(MessageListener listener)
                        throws JMSException

Sets the message consumer's MessageListener.

Setting the message listener to null is the equivalent of unsetting the message listener for the message consumer.

The effect of calling MessageConsumer.setMessageListener while messages are being consumed by an existing listener or the consumer is being used to consume messages synchronously is undefined.

Parameters:

listener - the listener to which the messages are to be delivered

Throws:

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

See Also:

getMessageListener()

public Message receive() throws JMSException
接收为此消息使用方生成的下一个消息。

在消息生成或此消息使用方关闭之前，将无限期地阻塞此调用。

如果在事务内完成了此 receive，则在事务提交之前使用方会一直保留该消息。

return	为此消息使用方生成的下一个消息；如果此消息使用方已经同时关闭，则返回 null
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法接收文本消息。

英文文档：

receive

Message receive()
                throws JMSException

Receives the next message produced for this message consumer.

This call blocks indefinitely until a message is produced or until this message consumer is closed.

If this receive is done within a transaction, the consumer retains the message until the transaction commits.

Returns:

the next message produced for this message consumer, or null if this message consumer is concurrently closed

Throws:

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

public Message receive(long timeout) throws JMSException
接收在指定超时间隔内到达的下一个消息。

在消息到达、超时期满或此消息使用方关闭之前，将一直阻塞此调用。timeout 为 0 表示永远不会到期，将无限期地阻塞该调用。

timeout	超时值（以毫秒为单位）
return	为此消息使用方生成的下一个消息；如果超时期满或此消息使用方已经同时关闭，则返回 null
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法接收文本消息。

英文文档：

receive

Message receive(long timeout)
                throws JMSException

Receives the next message that arrives within the specified timeout interval.

This call blocks until a message arrives, the timeout expires, or this message consumer is closed. A timeout of zero never expires, and the call blocks indefinitely.

Parameters:

timeout - the timeout value (in milliseconds)

Returns:

the next message produced for this message consumer, or null if the timeout expires or this message consumer is concurrently closed

Throws:

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

public Message receiveNoWait() throws JMSException
接收立即可用的下一个消息。

return	为此消息使用方生成的下一个消息；如果没有消息可用，则返回 null
Throws	JMSException: 如果 JMS 提供者由于某个内部错误无法接收文本消息。

英文文档：

receiveNoWait

Message receiveNoWait()
                      throws JMSException

Receives the next message if one is immediately available.

Returns:

the next message produced for this message consumer, or null if one is not available

Throws:

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

public void close() throws JMSException
关闭消息使用方。

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

在正在进行的 receive 或消息侦听器完成前，此调用将一直阻塞。当此消息使用方关闭时，阻塞的消息使用方 receive 调用返回 null。

Throws

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

英文文档：

close

void close()
           throws JMSException

Closes the message consumer.

Since a provider may allocate some resources on behalf of a MessageConsumer 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.

This call blocks until a receive or message listener in progress has completed. A blocked message consumer receive call returns null when this message consumer is closed.

Throws:

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

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