TIBCO EMS .NET API 8.5
TIBCO EMS .NET API 8.5
TIBCO.EMS.UFO.MessageConsumer Class Reference

A client uses a MessageConsumer object to receive messages from a destination. More...

Inheritance diagram for TIBCO.EMS.UFO.MessageConsumer:
TIBCO.EMS.UFO.QueueReceiver TIBCO.EMS.UFO.TopicSubscriber

Public Member Functions

Message Receive ()
 Receives the next message produced for this message consumer. More...
 
Message Receive (long timeout)
 Receives the next message that arrives within the specified timeout interval. More...
 
Message ReceiveNoWait ()
 Receives the next message if one is immediately available. More...
 
void Close ()
 Closes the message consumer More...
 
override string ToString ()
 return a string representation of the message consumer More...
 

Properties

string MessageSelector [get]
 Gets this message consumer's message selector expression. More...
 
IMessageListener MessageListener [get, set]
 Get and set the asynchronous message listener More...
 
EMSMessageHandler MessageHandler
 The message event handler for asynchronous message consumption. More...
 

Detailed Description

A client uses a MessageConsumer object to receive messages from a destination.

MessageConsumer is the parent interface for all message consumers.

A MessageConsumer object is created by passing a Destination object to a message-consumer creation method supplied by a session. A message consumer can be created with a message selector that 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.

Consumers can receive messages asynchronously in either of two idioms. Programmers may select either idiom - but not both (which would cause duplicate message processing, with undefined behavior).

  • MessageHandler - see EMSMessageHandler for more information. The client library raises an event when a message arrives at the destination. The program implements a handler delegate to processes it asynchronously, and registers the delegate here.
  • MessageListener - see IMessageListener for more information. A client can register a MessageListener object with a message consumer. When a message arrives, the client library calls this listener's onMessage method with the message as its argument. The program implements the message listener interface, and registers a message listener object by setting this property. The MessageListener mimics the way in which JMS provides similar functionality in a Java programming idiom

A message selector restricts the set of messages that the consumer receives to those that match the selector. Programs can set this property only when creating the consumer object; see Session.CreateConsumer.

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

Member Function Documentation

void TIBCO.EMS.UFO.MessageConsumer.Close ( )
inline

Closes the message consumer

The Close method stops the message consumer from receiving messages and reclaims resources.

If a receive call or a message listener is in progress, then Close waits until that call returns.

Message consumers rely on resources outside the client program. To reclaim these resources in a timely manner, a client should explicitly close message consumer objects (rather than waiting for garbage collection).

Message TIBCO.EMS.UFO.MessageConsumer.Receive ( )
inline

Receives the next message produced for this message consumer.

This method consumes the next message from the destination (synchronously). When the destination does not have any messages ready, this method blocks:

  • If a message arrives at the destination, this call immediately returns that message.
  • If another thread closes the consumer, this call returns null.

When calling receive within a transaction, the consumer retains the message until transaction commits.

Returns
the next message produced for this message consumer, or null if this message consumer is concurrently closed
Message TIBCO.EMS.UFO.MessageConsumer.Receive ( long  timeout)
inline

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

This method consumes the next message from the destination (synchronously). When the destination does not have any messages ready, this method blocks:

  • If a message arrives at the destination, this call immediately returns that message.
  • If the (non-zero) timeout elapses before a message arrives, this call returns null.
  • If another thread closes the consumer, this call returns null.

When calling receive within a transaction, the consumer retains the message until transaction commits.

Parameters
timeoutWait no longer than this interval (in milliseconds) for a message to arrive. Zero is a special value, which specifies no timeout (block indefinitely).
Returns
the next message produced for this message consumer, or null if this message consumer is concurrently closed
Message TIBCO.EMS.UFO.MessageConsumer.ReceiveNoWait ( )
inline

Receives the next message if one is immediately available.

This method receives a message synchronously without blocking.

When the destination has at least one message ready, this method immediately returns the next message. When the destination does not have any messages ready, this method immediately returns null. When calling receive within a transaction, the consumer retains the message until transaction commits.

Returns
the next message produced for this message consumer, or null if one is not available
override string TIBCO.EMS.UFO.MessageConsumer.ToString ( )
inline

return a string representation of the message consumer

Returns
a string representation of the message consumer

Property Documentation

EMSMessageHandler TIBCO.EMS.UFO.MessageConsumer.MessageHandler
addremove

The message event handler for asynchronous message consumption.

The client library raises an event when a message arrives at the destination. The program implements a handler delegate to processes it asynchronously.

The delegate declaration for message event handler is as follows:

public delegate void EMSMessageHandler(object sender, EMSMessageEventArgs args);


sender: The source of the event. It can be either the MessageConsumer object or the Session object depending on to which object is the message handler registered.
args: The event argument, EMSMessageEventArgs
Example of using the message event handler:

...
consumer.MessageHandler += new EMSMessageHandler(handleMsg);
...
private void handleMsg(object sender, EMSMessageEventArgs arg)
{
Message m = arg.Message;
Console.WriteLine("Received message: " + m);
}
...

User should either use MessageHandler or MessageListener to handle asynchronous message consumptions, but not both. Setting up both will cause the message to be handled more than once which can result in undefined behavior

Exceptions
TIBCO.EMS.IllegalStateExceptionIf the consumer is closed
IMessageListener TIBCO.EMS.UFO.MessageConsumer.MessageListener
getset

Get and set the asynchronous message listener

The client implements the MessageListener interface and registers a MessageListener object by setting this property. When a message arrives, the client library calls this MessageListener's onMessage method with the message as its argument.

A client can use either MessageHandler or MessageListener to handle asynchronous message consumptions, but not both. Setting up both will cause the message to be handled more than once which can result in undefined behavior.

Exceptions
TIBCO.EMS.IllegalStateExceptionIf the consumer is closed
string TIBCO.EMS.UFO.MessageConsumer.MessageSelector
get

Gets this message consumer's message selector expression.

A message selector restricts the set of messages that the consumer receives to those that match the selector.

A client sets this property when calling Session.CreateConsumer to create the consumer object.

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).

Copyright © Cloud Software Group, Inc. All rights reserved.