Oracle® C++ Call Interface Programmer's Guide 10g Release 1 (10.1) Part Number B10778-01 |
|
|
View PDF |
The Consumer
class supports dequeuing of Message
s and controls the dequeuing options.
For typical usage, please see Example 10-5, Example 10-6 and Example 10-7.
Example 10-5 Enqueuing time on the Producer
Producer myProducer(conn); Message m(env); // bytes is a Bytes object representing content of the message m.setBytes(bytes); myProducer.send( m, "QueueNmae");
Example 10-6 Dequeuing time on the Consumer
Consumer myConsumer(conn); // Name must be registered with the queue through administrative interface myConsumer.setConsumerName("ConsumerOne"); Message m = myConsumer.receive(Message::RAW); Bytes b = m.getBytes();
Example 10-7 Setting the Agent on the Consumer
Consumer myConsumer(conn); ... myConsumer.setAgent(ag); myConsumer.receive();
Table 10-11 Constants of the Consumer Class
Constant | Description |
---|---|
DEQ_BROWSE |
Read the message without acquiring a lock; equivalent to a SELECT . |
DEQ_LOCKED |
Read the message and get its write lock, which lasts s for the duration of the transaction; equivalent to a SELECT FOR UPDATE . |
DEQ_REMOVE |
Default. Read the message, and update or delete it; the message can be retained in the queue table based on the retention properties. |
DEQ_NO_DATA |
Confirm receipt of the message, but do not deliver its actual content. |
DEQ_FIRST_MSG |
Retrieves the first available message on the queue that matches the search criteria; resets the position to the beginning of the queue. |
DEQ_NEXT_MSG |
Default. Retrieves the next available message on the queue that matches the search criteria. If the previous message belongs to a message group, AQ will retrieve the next available message that matches the search criteria and belongs to the message group. |
DEQ_NEXT_TRANSACTION |
Skips the remainder of the current transaction group, if any, and retrieves the first message of the next transaction group. This option can only be used if message grouping is enabled for the current queue. |
DEQ_ON_COMMIT |
Default. The dequeue will be part of the current transaction. |
DEQ_IMMEDIATE |
The dequeued message is not part of the current transaction. It constitutes a transaction on its own. |
DEQ_NO_WAIT |
Do not wait if there are no messages on the queue. |
DEQ_WAIT_FOREVER |
The consumer will wait for the Message indefinitely |
Table 10-12 Summary of Consumer Methods
Method | Description |
---|---|
Consumer() |
Consumer class constructor. |
getConsumerName() |
Retrieves the name of the Consumer . |
getCorrelationId() |
Retrieve 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 will be dequeued. |
getQueueName() |
Gets the name of the queue used by the consumer. |
getPositionOfMessage() |
Retrieves the position of the Message that will be dequeued. |
getTransformation() |
Retrieves the transformation applied before a Message is dequeued. |
getVisibility() |
Retrieves the transactional behavior of the dequeue operation. |
getWaitTime() |
Retrieve the specified behavior of the Consumer when waiting for a Message with matching search criteria. |
isNull() |
Tests whether the Consumer object is NULL . |
receive() |
Receive and dequeue a Message |
setAgent() |
Sets the Agent 's name and address (queue name) on the consumer. |
setConsumerName() |
Sets the Consumer name. |
setCorrelationId() |
Specify the correlation identifier of the message to be dequeued. |
setDequeueMode() |
Specify 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 prior to dequeuing Message s. |
setTransformation() |
Specify transformation applied before dequeuing a Message . |
setVisibility() |
Specify if Message should be dequeued as part of the current transaction. |
setWaitTime() |
Specify wait conditions if there are no Message s with matching criteria. |
Consumer class constructor.
Syntax | Description |
---|---|
Consumer( Connection *conn); |
Creates a new Consumer object with the specified Connection handle. |
Consumer( Connection *conn Agent agent); |
Creates a new Consumer object with specified Connection handle and properties of the specified Agent . |
Consumer( Connection *conn, const string& queue); |
Creates a new Consumer object with specified Connection handle and queue. |
Parameter | Description |
---|---|
conn |
The connection in which the Consumer is created. |
queue |
Queue at which the Consumer retrieves messages. |
Retrieve the name of the Consumer
.
string getConsumerName() const;
Retrieve she correlation id of the message that is to be dequeued
string geCorrelationId() const;
Retrieve the dequeue mode of the Consumer
. These valid values for the dequeue mode are defined as constants of the Consumer
class in Table 10-11: DEQ_BROWSE
, DEQ_LOCKED
, DEQ_REMOVE
and DEQ_REMOVE_NODATA
.
DequeueMode getDequeueMode() const;
Retrieves the id of the message that will be dequeued.
Bytes getMessageToDequeue() const;
Retrieves the position of the message that will be dequeued. These valid values for the position of the message are defined as constants of the Consumer
class in Table 10-11: DEQ_FIRST_MSG
, DEQ_NEXT_MSG
and DEQ_NEXT_TRANSACTION
.
Navigation getPositionOfMessage() const;
Gets the name of the queue used by the consumer.
string getQueueName() const;
Retrieves the transformation applied before a Message
is dequeued.
string getTransformation() const;
Retrieves the transactional behavior of the dequeue operation. These valid values for visibility are defined as constants of the Consumer
class in Table 10-11: DEQ_ON_COMMIT
and DEQ_IMMEDIATE
.
Visibility getVisibility() const;
Retrieve the specified behavior of the Consumer
when waiting for a Message
with matching search criteria. These valid values for visibility are defined as constants of the Consumer
class in Table 10-11: DEQ_WAIT_FOREVER
and DEQ_NO_WAIT
.
unsigned int getWaitTime() const;
Tests whether the Consumer
object is NULL
. If the Consumer
object is NULL
, TRUE
is returned; otherwise, FALSE
is returned.
bool isNull() const;
Receives and dequeue a Message
.
Message receive( Message::PayloadType pType, const string& type="", const string& schema="");
Parameter | Description |
---|---|
pType |
The type of payload expected. Payload Type is defined as:
enum PayloadType {RAW, ANYDATA, OBJECT}; |
type |
The type of the payload; considered only when pType is OBJECT . |
schema |
The schema in which the type is defined; considered only when pType is OBJECT . |
Sets the Agent
's name and address (queue name) on the consumer.
void setAgent( const Agent& agent);
Parameter | Description |
---|---|
agent |
Name of the Agent . |
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
.
void setConsumerName( const string& name);
Parameter | Description |
---|---|
name |
Name of the Consumer . |
Specify 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.
void setCorrelationId const string& id);
Parameter | Description |
---|---|
id |
The identifier of the Message . |
Specify the locking behavior associated with dequeuing.
void setDequeueMode( DequeueMode deqMode);
Parameter | Description |
---|---|
deqMode |
Behavior of enqueuing. Valid values for the position of the message are defined as constants of the Consumer class in Table 10-11: DEQ_BROWSE , DEQ_LOCKED , DEQ_REMOVE and DEQ_REMOVE_NODATA . |
Specifies the identifier of the Message
to be dequeued.
void setMessageIdToDequeue( const Bytes& id);
Parameter | Description |
---|---|
id |
Identifier of the Message to be dequeued. |
Nullifies the Consumer
; frees the memory associated with this object.
void setNull();
Specifies position of the Message
to be retrieved.
void setPositionOfMessage( Navigation nav);
Parameter | Description |
---|---|
nav |
Position of the message. Valid values are defined as constants of the Consumer class in Table 10-11: DEQ_FIRST_MSG , DEQ_NEXT_MSG and DEQ_NEXT_TRANSACTION . |
Specifies the name of a queue prior to dequeuing Message
s. Typically used when dequeuing multiple messages from the same queue.
void setQueueName( const string& queueName);
Parameter | Description |
---|---|
queueName |
The name of a valid queue in the database. |
Specifies transformation applied before dequeuing the Message
.
void setTransformation( string &transFunction);
Parameter | Description |
---|---|
transFunction |
SQL transformation function. |
Specifies if Message
should be dequeued as part of the current transaction. Visibility parameter is ignored when in DEQ_BROWSE
mode.
void setVisibility( Visibility vis);
Parameter | Description |
---|---|
vis |
Visibility option being set. Valid values are defined as constants of the Consumer class in Table 10-11: DEQ_ON_COMMIT and DEQ_IMMEDIATE . |
Specify wait conditions if there are no Message
s with matching criteria. The waitTime
parameter is ignored if messages in the same group are being dequeued.
void setWaitTime( unsigned int waitTime);
Parameter | Description |
---|---|
vwaitTime |
Waiting conditions. Valid values are defined as constants of the Consumer class in Table 10-11: DEQ_WAIT_FOREVER and DEQ_NO_WAIT . |