Consumer Class

The Consumer class supports dequeuing of Messages and controls the dequeuing options.

LNCPP20850 Table 13-14 Enumerated Values Used by Consumer Class

Attribute	Options
DequeMode	`DEQ_BROWSE` indicates that the message should be read without acquiring a lock; equivalent to a `SELECT`. `DEQ_LOCKED` indicates that the message should be read. Get its write lock, which lasts s for the duration of the transaction; equivalent to a `SELECT FOR UPDATE`. `DEQ_REMOVE` indicates that the message should be read. Update or delete it; the message can be retained in the queue table based on the retention properties. This is the default setting. `DEQ_REMOVE_NODATA` indicates that the receipt of the message should be confirmed, but its actual content should not be delivered.
Navigation	`DEQ_FIRST_MSG` indicates that the first available message on the queue that matches the search criteria must be retrieved. Resets the position to the beginning of the queue. `DEQ_NEXT_TRANSACTION` indicates that the next available message on the queue that matches the search criteria must be retrieved. If the previous message belongs to a message group, AQ retrieves the next available message that matches the search criteria and belongs to the message group. This is the default setting. `DEQ_NEXT_MSG` indicates that the remainder of the current transaction group, if any, should be skipped. The first message of the next transaction group may then be retrieved. This option can only be used if message grouping is enabled for the current queue.
Visibility	`DEQ_IMMEDIATE` indicates that the dequeued message is not part of the current transaction. It constitutes a transaction on its own. `DEQ_ON_COMMIT` indicates that the dequeue is part of the current transaction. This is the default setting.
DequeWaitOption	`DEQ_WAIT_FOREVER` indicates that the consumer waits for the `Message` indefinitely. `DEQ_NO_WAIT` indicates that there should be not wait if there are no messages on the queue.

LNCPP20851 Table 13-15 Summary of Consumer Methods

Method	Description
Consumer()	`Consumer` class constructor.
getConsumerName()	Retrieves the name of the `Consumer`.
getCorrelationId()	Retrieves she correlation id of the message that is to be dequeued.
getDequeueMode()	Retrieves the dequeue mode of the `Consumer`.
getMessageIdToDequeue()	Retrieves the id of the message that is dequeued.
getQueueName()	Gets the name of the queue used by the consumer.
getPositionOfMessage()	Retrieves the position of the Message that is dequeued.
getTransformation()	Retrieves the transformation applied before a `Message` is dequeued.
getVisibility()	Retrieves the transactional behavior of the dequeue operation.
getWaitTime()	Retrieves the specified behavior of the `Consumer` when waiting for a `Message` with matching search criteria.
isNull()	Tests whether the `Consumer` object is `NULL`.
operator=()	Assignment operator for the `Consumer` class.
receive()	Receives and dequeues a `Message`
setAgent()	Sets the `Agent`'s name and address (queue name) on the consumer.
setConsumerName()	Sets the `Consumer` name.
setCorrelationId()	Specifies the correlation identifier of the message to be dequeued.
setDequeueMode()	Specifies the locking behavior associated with dequeuing.
setMessageIdToDequeue()	Specifies the identifier of the `Message` to be dequeued.
setNull()	Nullifies the `Consumer`; frees the memory associated with this object.
setPositionOfMessage()	Specifies position of the `Message` to be retrieved.
setQueueName()	Specifies the name of a queue before dequeuing `Message`s.
setTransformation()	Specifies transformation applied before dequeuing a `Message`.
setVisibility()	Specifies if `Message` should be dequeued as part of the current transaction.
setWaitTime()	Specifies wait conditions if there are no `Message`s with matching criteria.

LNCPP20852

Consumer()

Consumer class constructor.

Syntax	Description
Consumer( const Connection *conn);	Creates a new `Consumer` object with the specified `Connection` handle.
Consumer( const Connection *conn const Agent& agent);	Creates a new `Consumer` object with specified `Connection` and properties of the specified `Agent`.
Consumer( const Connection *conn, const string& queue);	Creates a new `Consumer` object with specified `Connection` and queue.
Consumer( const Consumer& consumer);	Copy constructor.

Parameter	Description
conn	The connection in which the `Consumer` is created.
agent	Agent assigned to the `Consumer`.
queue	Queue at which the `Consumer` retrieves messages.
consumer	Original `Consumer` object.

LNCPP20853

getConsumerName()

Retrieves the name of the Consumer.

LNCPP20854Syntax

string getConsumerName() const;

LNCPP20855

getCorrelationId()

Retrieves she correlation id of the message that is to be dequeued

LNCPP20856Syntax

string geCorrelationId() const;

LNCPP20857

getDequeueMode()

Retrieves the dequeue mode of the Consumer. DequeueMode is defined in Table 13-14.

LNCPP20858Syntax

DequeueMode getDequeueMode() const;

LNCPP20859

getMessageIdToDequeue()

Retrieves the id of the message that is dequeued.

LNCPP20860Syntax

Bytes getMessageToDequeue() const;

LNCPP20861

getPositionOfMessage()

Retrieves the position, or navigation, of the message that is dequeued. Navigation is defined in Table 13-14.

LNCPP20862Syntax

Navigation getPositionOfMessage() const;

LNCPP20863

getQueueName()

Gets the name of the queue used by the consumer.

LNCPP20864Syntax

string getQueueName() const;

LNCPP20865

getTransformation()

Retrieves the transformation applied before a Message is dequeued.

LNCPP20866Syntax

string getTransformation() const;

LNCPP20867

getVisibility()

Retrieves the transactional behavior of the dequeue operation, or visibility. Visibility is defined in Table 13-14.

LNCPP20868Syntax

Visibility getVisibility() const;

LNCPP20869

getWaitTime()

Retrieves the specified behavior of the Consumer when waiting for a Message with matching search criteria. DequeWaitOption is defined in Table 13-14.

LNCPP20870Syntax

DequeWaitOption getWaitTime() const;

LNCPP20871

isNull()

Tests whether the Consumer object is NULL. If the Consumer object is NULL, TRUE is returned; otherwise, FALSE is returned.

LNCPP20872Syntax

bool isNull() const;

LNCPP20873

operator=()

Assignment operator for Consumer class.

LNCPP20874Syntax

void operator=(
   const Consumer& consumer);

Parameter	Description
consumer	The original `Consumer`.

LNCPP20875

receive()

Receives and dequeues a Message.

LNCPP20876Syntax

Message receive(
   Message::PayloadType pType,
   const string& type="",
   const string& schema="");

Parameter	Description
pType	The type of payload expected. Payload Type is defined in Table 13-14.
type	The type of the payload when `type` is `OBJECT`.
schema	The schema in which the type is defined when `pType` is `OBJECT`.

LNCPP20877

setAgent()

Sets the Agent's name and address (queue name) on the consumer.

LNCPP20878Syntax

void setAgent(
   const Agent& agent);

Parameter	Description
agent	Name of the `Agent`.

LNCPP20879

setConsumerName()

Sets the Consumer name. Only messages with matching consumer name can be accessed. If a queue is not set up for multiple consumer, this option should be set to NULL.

LNCPP20880Syntax

void setConsumerName(
   const string& name);

Parameter	Description
name	Name of the `Consumer`.

LNCPP20881

setCorrelationId()

Specifies the correlation identifier of the message to be dequeued. Special pattern matching characters, such as the percent sign (%) and the underscore(_) can be used. If several messages satisfy the pattern, the order of dequeuing is undetermined.

LNCPP20882Syntax

void setCorrelationId
   const string& id);

Parameter	Description
id	The identifier of the `Message`.

LNCPP20883

setDequeueMode()

Specifies the locking behavior associated with dequeuing.

LNCPP20884Syntax

void setDequeueMode(
   DequeueMode mode);

Parameter	Description
mode	Behavior of enqueuing. `DequeMode` is defined in Table 13-14.

LNCPP20885

setMessageIdToDequeue()

Specifies the identifier of the Message to be dequeued.

LNCPP20886Syntax

void setMessageIdToDequeue(
   const Bytes& msgid);

Parameter	Description
msgid	Identifier of the `Message` to be dequeued.

LNCPP20887

setNull()

Nullifies the Consumer; frees the memory associated with this object.

LNCPP20888Syntax

void setNull();

LNCPP20889

setPositionOfMessage()

Specifies position of the Message to be retrieved.

LNCPP20890Syntax

void setPositionOfMessage(
   Navigation pos);

Parameter	Description
pos	Position of the message, `Navigation`, is defined in Table 13-14.

LNCPP20891

setQueueName()

Specifies the name of a queue before dequeuing Messages. Typically used when dequeuing multiple messages from the same queue.

LNCPP20892Syntax

void setQueueName(
   const string& queue);

Parameter	Description
queue	The name of a valid queue in the database.

LNCPP20893

setTransformation()

Specifies transformation applied before dequeuing the Message.

LNCPP20894Syntax

void setTransformation(
   string &fName);

Parameter	Description
fName	SQL transformation function.

LNCPP20895

setVisibility()

Specifies if Message should be dequeued as part of the current transaction. Visibility parameter is ignored when in DEQ_BROWSE mode.

LNCPP20896Syntax

void setVisibility(
   Visibility option);

Parameter	Description
option	Visibility option being set, defined in Table 13-14.

LNCPP20897

setWaitTime()

Specifies wait conditions if there are no Messages with matching criteria. The wait parameter is ignored if messages in the same group are being dequeued.

LNCPP20898Syntax

void setWaitTime(
   DequeWaitOption wait);

Parameter	Description
wait	Waiting conditions. `DequeWaitOption` is defined in Table 13-14.