TIBCO EMS .NET API 8.5 TIBCO EMS .NET API 8.5

- Main Page
- Related Pages
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Member Functions | Properties | List of all members
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:

## 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

  timeout | Wait 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
| add remove

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.IllegalStateException | If the consumer is closed

IMessageListener TIBCO.EMS.UFO.MessageConsumer.MessageListener
| get set

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