oracle.jms
Class AQjmsConsumer

java.lang.Object
oracle.jms.AQjmsObject
oracle.jms.AQjmsConsumer

All Implemented Interfaces:

AQjmsQueueReceiver, AQjmsTopicReceiver, AQjmsTopicSubscriber, MessageConsumer, QueueReceiver, javax.naming.Referenceable, TopicReceiver, TopicSubscriber

public class AQjmsConsumer

extends oracle.jms.AQjmsObject

implements AQjmsQueueReceiver, AQjmsTopicSubscriber, AQjmsTopicReceiver, javax.naming.Referenceable

This is an Oracle class which implements oracle.jms.AQjmsQueueReceiver, oracle.jms.AQjmsTopicSubscriber and oracle.jms.AQjmsTopicReceiver.

Method Summary

Message	bufferReceive() Receives the next message from both the in-memory and persistent portion of the queue.
Message	bufferReceive(long timeout) Receives the next message from both the in-memory and persistent portion of the queue if one is available within the specified timeout.
Message	bufferReceiveNoWait() Receives the next message from both the in-memory and persistent portion of the queue if one is immediately available.
void	close() Closes the message consumer.
MessageListener	getMessageListener() Gets this message consumer's MessageListener.
java.lang.String	getMessageSelector() Gets this message consumer's message selector expression.
int	getNavigationMode() Gets the navigation mode used for receiving messages.
boolean	getNoLocal() Gets the NoLocal attribute for this TopicSubscriber.
Queue	getQueue() Gets the queue associated with this queue receiver.
javax.naming.Reference	getReference() Creates a message consumer reference.
Topic	getTopic() Gets the topic associated with this topic subscriber.
java.lang.String	getTransformation() Gets this consumer's transformation.
Message	receive() Receives the next message.
Message	receive(long timeout) Receives the next message if one is available within the specified timeout.
void	receiveNoData() Consumes the message without returning it to the user.
void	receiveNoData(long timeout) Consumes the message without returning it to the user.
Message	receiveNoWait() Receives the next message if one is immediately available.
void	setMessageListener(MessageListener myListener) Set this message consumer's MessageListener.
void	setNavigationMode(int mode) Sets the navigation mode used for receiving messages.
void	setTransformation(java.lang.String transformation) Sets this consumer's transformation.

Methods inherited from class oracle.jms.AQjmsObject

checkClosed, children, finalize, getID, getParent, isOpen, localClose, preClose

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface oracle.jms.AQjmsTopicSubscriber

receive

Methods inherited from interface oracle.jms.AQjmsTopicReceiver

receive, receive, receiveSignature, receiveSignature

Method Detail

getMessageSelector

public java.lang.String getMessageSelector()
                                    throws JMSException

Gets this message consumer's message selector expression.

Specified by:

getMessageSelector in interface MessageConsumer

Returns:

this message consumer's message selector

Throws:

JMSException - if:

• this consumer has already been closed, or
• the message selector is not available because the consumer is a durable topic subscriber which was created via some non-JMS API or from a different JVM.

See Also:

close()

getReference

public javax.naming.Reference getReference()

Creates a message consumer reference.

Specified by:

getReference in interface javax.naming.Referenceable

Returns:

a message consumer reference with object and factory class names set

getMessageListener

public MessageListener getMessageListener()
                                   throws JMSException

Gets this message consumer's MessageListener.

Specified by:

getMessageListener in interface MessageConsumer

Returns:

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

Throws:

JMSException - if:

• this consumer has already been closed, or
• a distinguished listener has been set for this consumer's session.

See Also:

close(), AQjmsSession.setMessageListener(javax.jms.MessageListener)

setMessageListener

public void setMessageListener(MessageListener myListener)
                        throws JMSException

Set this message consumer's MessageListener. Once set, myListener's MessageListener.onMessage(javax.jms.Message) method is called when there are messages for this consumer.

Specified by:

setMessageListener in interface MessageConsumer

Parameters:

myListener - the listener to which incoming messages are to be sent

Throws:

JMSException - if:

• this consumer has already been closed,
• a distinguished listener has been set for this consumer's session, or
• a thread to process the listener can not be created/started.

See Also:

close(), AQjmsSession.setMessageListener(javax.jms.MessageListener)

receive

public Message receive()
                throws JMSException

Receives the next message.

Blocks indefinitely until a message is received or this consumer is closed.

Specified by:

receive in interface MessageConsumer

Returns:

the next message, or null if the receive was pending and was then terminated due to this consumer being closed

Throws:

JMSException - if the next message is not received due to some error.

receiveNoWait

public Message receiveNoWait()
                      throws JMSException

Receives the next message if one is immediately available.

Specified by:

receiveNoWait in interface MessageConsumer

Returns:

the next message, or null if none are immediately available

Throws:

JMSException - if the next message is not received due to some error.

receive

public Message receive(long timeout)
                throws JMSException

Receives the next message if one is available within the specified timeout.

Blocks until a message is received, the timeout expires, or this consumer is closed. A timeout of zero never expires.

Specified by:

receive in interface MessageConsumer

Parameters:

timeout - the timeout value (in milliseconds)

Returns:

the next message, or null if none are available in time

Throws:

JMSException - if the next message is not received due to some error.

bufferReceive

public Message bufferReceive()
                      throws JMSException

Receives the next message from both the in-memory and persistent portion of the queue. When the in-memory queue is used, the enqueue operation is required to be in immediate visibility mode. (This requirement might be removed in a later release.)

Blocks indefinitely until a message is received or this consumer is closed.

Returns:

the next message, or null if the receive was pending and was then terminated due to this consumer being closed

Throws:

JMSException - if the next message is not received due to some error.

bufferReceiveNoWait

public Message bufferReceiveNoWait()
                            throws JMSException

Receives the next message from both the in-memory and persistent portion of the queue if one is immediately available. When the in-memory queue is used, the enqueue operation is required to be in immediate visibility mode. (This requirement might be removed in a later release.)

Returns:

the next message, or null if none are immediately available

Throws:

JMSException - if the next message is not received due to some error.

bufferReceive

public Message bufferReceive(long timeout)
                      throws JMSException

Receives the next message from both the in-memory and persistent portion of the queue if one is available within the specified timeout. When the in-memory queue is used, the enqueue operation is required to be in immediate visibility mode. (This requirement might be removed in a later release.)

Blocks until a message is received, the timeout expires, or this consumer is closed. A timeout of zero never expires.

Parameters:

timeout - the timeout value (in milliseconds)

Returns:

the next message, or null if none are available in time

Throws:

JMSException - if the next message is not received due to some error.

close

public void close()
           throws JMSException

Description copied from interface: MessageConsumer

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.

Specified by:

close in interface MessageConsumer

Throws:

JMSException

getQueue

public Queue getQueue()
               throws JMSException

Gets the queue associated with this queue receiver.

Specified by:

getQueue in interface QueueReceiver

Returns:

the queue

Throws:

JMSException - if called on a topic subscriber.

getTopic

public Topic getTopic()
               throws JMSException

Gets the topic associated with this topic subscriber.

Specified by:

getTopic in interface TopicSubscriber

Returns:

the topic

Throws:

JMSException - if called on a queue receiver.

getNoLocal

public boolean getNoLocal()
                   throws JMSException

Gets the NoLocal attribute for this TopicSubscriber. The default value for this attribute is false.

Specified by:

getNoLocal in interface TopicSubscriber

Returns:

true if locally published messages are being inhibited.

Throws:

JMSException - if:

• this method is called on a queue receiver, or
• the NoLocal attribute is not available because the consumer is a durable topic subscriber which was created via some non-JMS API or from a different JVM.

getNavigationMode

public int getNavigationMode()
                      throws JMSException

Gets the navigation mode used for receiving messages. The navigation modes are:

• AQjmsConstants.NAVIGATION_FIRST_MESSAGE
• AQjmsConstants.NAVIGATION_NEXT_MESSAGE
• AQjmsConstants.NAVIGATION_NEXT_TRANSACTION

See the Oracle "Streams Advanced Queuing User's Guide and Reference" for an explanation of navigation modes.

Specified by:

getNavigationMode in interface AQjmsQueueReceiver

Returns:

this consumer's navigation mode

Throws:

JMSException - if this consumer has already been closed.

setNavigationMode

public void setNavigationMode(int mode)
                       throws JMSException

Sets the navigation mode used for receiving messages. The navigation modes are:

• AQjmsConstants.NAVIGATION_FIRST_MESSAGE
• AQjmsConstants.NAVIGATION_NEXT_MESSAGE
• AQjmsConstants.NAVIGATION_NEXT_TRANSACTION

See the Oracle "Streams Advanced Queuing User's Guide and Reference" for an explanation of navigation modes.

Specified by:

setNavigationMode in interface AQjmsQueueReceiver

Parameters:

mode - the new navigation mode for this consumer

Throws:

JMSException - if:

• this consumer has already been closed, or
• the supplied mode does not match any of the above listed navigation modes.

setTransformation

public void setTransformation(java.lang.String transformation)

Sets this consumer's transformation.

Specified by:

setTransformation in interface AQjmsQueueReceiver

Parameters:

transformation - the transformation to use when getting messages

getTransformation

public java.lang.String getTransformation()

Gets this consumer's transformation.

Specified by:

getTransformation in interface AQjmsQueueReceiver

Returns:

the transformation used when getting messages

receiveNoData

public void receiveNoData()
                   throws JMSException

Consumes the message without returning it to the user. This call will avoid the overhead of fetching the message from the database. It can be used as an optimization by jms clients who have already read the message, for example using a queue browser.

Blocks indefinitely until a message is received or this consumer is closed.

Specified by:

receiveNoData in interface AQjmsQueueReceiver

Throws:

JMSException - if the message could not be received due to some error.

receiveNoData

public void receiveNoData(long timeout)
                   throws JMSException

Consumes the message without returning it to the user. This call will avoid the overhead of fetching the message from the database. It can be used as an optimization by jms clients who have already read the message, for example using a queue browser.

Blocks until a message is received, the timeout expires, or this consumer is closed. A timeout of zero never expires.

Specified by:

receiveNoData in interface AQjmsQueueReceiver

Parameters:

timeout - the timeout value in milliseconds

Throws:

JMSException - if the message could not be received due to some error.