Oracle9i Application Developer's Guide - Advanced Queuing
Release 1 (9.0.1)
Part Number A88890-02
Go To Documentation Library
Home		 Go To Product List
Book List		 Go To Table Of Contents
Contents		 Go To Index
Index
Master Index
Feedback

Go to previous page Go to beginning of chapter Go to next page

Internet Access to Advanced Queuing, 3 of 9

The Internet Data Access Presentation (IDAP)

The Internet Data Access Presentation (IDAP) uses the Content-Type of text/xml to specify the body of the request containing an XML-encoded method request. XML provides the presentation for IDAP request and response messages as follows:

IDAP Message Structure

IDAP structures a message request or response as follows:

The IDAP Envelope

The tag of this root element is IDAP:Envelope. IDAP defines a global attribute IDAP:encodingStyle that indicates serialization rules used instead of those described by the IDAP specification. This attribute may appear on any element and is scoped to that element and all child elements not themselves containing such an attribute. Omitting IDAP:encodingStyle means that type specification has been followed (unless overridden by a parent element).

The IDAP envelope also contains namespace declarations and additional attributes, provided they are namespace-qualified. Additional namespace-qualified subelements can follow the body.

IDAP Headers

The tag of this first element under the root is IDAP:Header. An IDAP header passes necessary information, such as the transaction ID, with the request. The header is encoded as a child of the IDAP:Envelope XML element. Headers are identified by the name element and are namespace-qualified. A header entry is encoded as an embedded element.

The IDAP Body

The IDAP body, tagged IDAP:Body, contains a first subelement whose name is the method name. This method request element contains elements for each input and output parameter. The element names are the parameter names. The body also contains IDAP: Fault, indicating information about an error.

For performing AQ operations, the IDAP body must contain an AQ XML document. The AQ XML document has the namespace http://ns.oracle.com/AQ/schemas/access

IDAP Method Invocation

A method invocation is performed by creating the request header and body and processing the returned response header and body. The request and response headers can consist of standard transport protocol-specific and extended headers.

In the case of SMTP (email), the method invocation can be done by the filter interface of the email server, which invokes a Java method with the email-message-body as argument. This results in remote invocation of the POST method on the AQ servlet. The response is emailed directly to the recipient specified in the reply of the message. The response header can contain SMTP-protocol-related headers also.

HTTP Headers

The POST method within the HTTP request header performs the IDAP method invocation. The request should include the header IDAPMethodName, whose value indicates the method to be invoked on the target. The value consists of a URI followed by a "#", followed by a method name (which must not include the "#" character), as follows: 

IDAPMethodName: http://ns.oracle.com/AQ/schemas/access#AQXmlSend

The URI used for the interface must match the implied or specified namespace qualification of the method name element in the IDAP:Body part of the payload.

Method Invocation Body

IDAP method invocation consists of a method request and optionally a method response. The IDAP method request and method response are an HTTP request and response, respectively, whose content is an XML document that consists of the root and mandatory body elements. This XML document is referred to as the IDAP payload in the rest of this chapter.

The IDAP payload is defined as follows:

At the receiving site, a request can have one of the following outcomes:

    1. The HTTP infrastructure on the receiving site is able to receive and process the request.

    2. The HTTP infrastructure on the receiving site cannot receive and process the request.

    3. The IDAP infrastructure on the receiving site is able to decode the input parameters, dispatch to an appropriate server indicated by the server address, and invoke an application-level function corresponding semantically to the method indicated in the method request.

    4. The IDAP infrastructure on the receiving site cannot decode the input parameters, dispatch to an appropriate server indicated by the server address, and invoke an application-level function corresponding semantically to the interface or method indicated in the method request.

In (a), the HTTP infrastructure passes the headers and body to the IDAP infrastructure. In (b), the result is an HTTP response containing an HTTP error in the status field and no XML body. In (c), the result of the method request consists of a response or error. In (d), the result of the method is an error that prevented the dispatching infrastructure on the receiving side from successful completion. In (c) and (d), additional message headers may for extensibility again be present in the results of the request.

Results from a Method Request

The results of the request are to be provided in the form of a request-response. The HTTP response must be of Content-Type text/xml. An IDAP result indicates success and an error indicates failure. The method response will never contain both a result and an error.

AQ XML Documents

The body of an IDAP message is an AQ XML document, which represents:

Client Requests for Enqueue

Client requests for enqueue--SEND and PUBLISH requests--use the following methods:

AQXmlSend and AQXmlPublish take the arguments and argument attributes shown in Table 17-1. Required arguments are shown in bold.

Table 17-1 Client Requests for Enqueue--Arguments and Attributes for AQXmlSend and AQXmlPublish
Argument  Attribute 

producer_options 

destination--specify the queue/topic to which messages are to be sent. The destination element has an attribute lookup_type which determines how the destination element value is interpreted

  • DATABASE (default)--destination is interpreted as schema.queue_name

  • LDAP--the LDAP server is used to resolve the destination

 

 

visibility

  • ON_COMMIT--The enqueue is part of the current transaction. The operation is complete when the transaction commits. This is the default case.

  • IMMEDIATE--effects of the enqueue are visible immediately after the request is completed. The enqueue is not part of the current transaction. The operation constitutes a transaction on its own.

 

 

transformation--the PL/SQL transformation to be invoked before the message is enqueued 

message_set--contains one or more messages.  

Each message consists of a message_header and message_payload 
  • message_header

 

message_id--unique identifier of the message, supplied during dequeue 

 

correlation--correlation identifier of the message 

 

expiration--duration in seconds that a message is available for dequeuing. This parameter is an offset from the delay. By default messages never expire.

If the message is not dequeued before it expires, then it is moved to the exception queue in the EXPIRED state 

 

delay--duration in seconds after which a message is available for processing 

 

priority--the priority of the message. A smaller number indicates higher priority. The priority can be any number, including negative numbers.  

 

sender_id--the application-specified identifier

  • agent_name, address, protocol

  • agent_alias--if specified, resolves to a name, address, protocol using LDAP

 

 

recipient_list--list of recipients; overrides the default subscriber list. Each recipient consists of:

  • agent_name, address, protocol

  • agent_alias--if specified, resolves to a name, address, protocol using LDAP

 

 

message_state-- state of the message is filled in automatically during dequeue

0: The message is ready to be processed.

1: The message delay has not yet been reached.

2: The message has been processed and is retained.

3: The message has been moved to the exception queue. 

 

exception_queue--in case of exceptions the name of the queue to which the message is moved if it cannot be processed successfully. Messages are moved in two cases: The number of unsuccessful dequeue attempts has exceeded max_retries or the message has expired. All messages in the exception queue are in the EXPIRED state.

The default is the exception queue associated with the queue table. If the exception queue specified does not exist at the time of the move, then the message is moved to the default exception queue associated with the queue table, and a warning is logged in the alert file. If the default exception queue is used, then the parameter returns a NULL value at dequeue time. 
  • message_payload

 

this can have different sub-elements based on the payload type of the destination queue/topic. The different payload types are described in the next section 

AQXmlCommit 

this is an empty element--if specified, the user transaction is committed at the end of the request 

Message Payloads

AQ supports messages of the following types:

All these types of queues can be accessed using IDAP. If the queue holds messages in RAW, Oracle object, or JMS format, XML payloads are transformed to the appropriate internal format during enqueue and stored in the queue. During dequeue, when messages are obtained from queues containing messages in any of the above formats, they are converted to XML before being sent to the client.

The message payload type depends on the type of the queue on which the operation is being performed. A discussion of the queue types follows:

RAW Queues

The contents of RAW queues are raw bytes. The user must supply the hex representation of the message payload in the XML message. For example, <raw>023f4523</raw>.

Oracle object (ADT) type queues

For ADT queues that are not JMS queues (that is, they are not type AQ$_JMS_*), the type of the payload depends on the type specified while creating the queue table that holds the queue. The XML specified here must map to the SQL type of the payload for the queue table. See the Oracle9i Application Developer's Guide - XML for more details on mapping SQL types to XML.

Example

Assume the queue is defined to be of type EMP_TYP, which has the following structure: 

create or replace type emp_typ as object (
     empno NUMBER(4),
     ename VARCHAR2(10),
     job VARCHAR2(9),
     mgr NUMBER(4),
     hiredate DATE,
     sal   NUMBER(7,2),
     comm  NUMBER(7,2)
     deptno NUMBER(2));

The corresponding XML representation is: 

              <EMP_TYP>
              	  <EMPNO>1111</EMPNO>
              	  <ENAME>Mary</ENAME>
          	      <MGR>5000</MGR>
          	      <HIREDATE>1996-01-01 0:0:0</HIREDATE>
                <SAL>10000</SAL>
                <COMM>100.12</COMM>
          	      <DEPTNO>60</DEPTNO>
          	    </EMP_TYP>
JMS Type Queues/Topics

For queues with JMS types (that is, those with payloads of type AQ$_JMS_*), there are four different XML elements, depending on the JMS type. IDAP supports queues/topics with the following JMS types: TextMessage, MapMessage, BytesMessage and ObjectMessage. JMS queues with payload type StreamMessage are not supported through IDAP.

The JMS types and XML components are shown in Table 17-2. The distinct XML element for each JMS type is shown in its respective column. Required elements are shown in bold.

Table 17-2 JMS Types and XML Components

Used for queues/topics with payload type: 

AQ$_JMS_TEXT_MESSAGE 

AQ$_JMS_MAP_MESSAGE 

AQ$_JMS_BYTES_MESSAGE 

AQ$_JMS_OBJECT_MESSAGE 
jms_text_message  jms_map_message  jms_bytes_message  jms_object_message 

oracle_jms_properties 

user_properties 

text_data--string representing the text payload 

map_data--set of name-value pairs called items, consisting of:

  • name

  • int_value or

    string_value or

    long_value or

    double_value or

    boolean_value or

    float_value or

    short_value or

    byte_value

 

bytes_data--hex representation of the payload bytes 

ser_object_data--hex representation of the serialized object 

All JMS messages consist of the following common elements:

The following examples show enqueue requests using the different message and queue types.

Enqueue Request Example--Sending an ADT Message to a Single-Consumer Queue

The queue QS.NEW_ORDER_QUE has a payload of type ORDER_TYP. 

 <?xml version="1.0"?>
   <Envelope xmlns= "http://ns.oracle.com/AQ/schemas/envelope">
      <Body>
        <AQXmlSend xmlns = "http://ns.oracle.com/AQ/schemas/access">
          <producer_options>
            <destination>QS.NEW_ORDERS_QUE</destination>
          </producer_options>
          
          <message_set>
            <message_count>1</message_count>	
          
            <message>
              <message_number>1</message_number>
          
              <message_header>
                <correlation>ORDER1</correlation>
             	   <sender_id>
          	        <agent_name>scott</agent_name>
          	      </sender_id> 
              </message_header>
          
              <message_payload>	

               <ORDER_TYP>
                     <ORDERNO>100</ORDERNO>
                     <STATUS>NEW</STATUS>
                     <ORDERTYPE>URGENT</ORDERTYPE>
                     <ORDERREGION>EAST</ORDERREGION>
                     <CUSTOMER>
                        <CUSTNO>1001233</CUSTNO>
                        <CUSTID>MA1234555623212</CUSTID>
                        <NAME>AMERICAN EXPRESS</NAME>
                        <STREET>EXPRESS STREET</STREET>
                        <CITY>REDWOOD CITY</CITY>
                        <STATE>CA</STATE>
                        <ZIP>94065</ZIP>
                        <COUNTRY>USA</COUNTRY>
                     </CUSTOMER>
                     <PAYMENTMETHOD>CREDIT</PAYMENTMETHOD>
                     <ITEMS>
                        <ITEMS_ITEM>
                           <QUANTITY>10</QUANTITY>
                           <ITEM>
                              <TITLE>Perl</TITLE>
                              <AUTHORS>Randal</AUTHORS>
                              <ISBN>ISBN20200</ISBN>
                              <PRICE>19</PRICE>
                           </ITEM>
                           <SUBTOTAL>190</SUBTOTAL>
                        </ITEMS_ITEM>
                        <ITEMS_ITEM>
                           <QUANTITY>20</QUANTITY>
                           <ITEM>
                              <TITLE>XML</TITLE>
                              <AUTHORS>Micheal</AUTHORS>
                              <ISBN>ISBN20212</ISBN>
                              <PRICE>59</PRICE>
                           </ITEM>
                           <SUBTOTAL>590</SUBTOTAL>
                        </ITEMS_ITEM>
                     </ITEMS>
                     <CCNUMBER>NUMBER01</CCNUMBER>
                     <ORDER_DATE>2000-08-23 0:0:0</ORDER_DATE>
               </ORDER_TYP>
             </message_payload>
            </message>
          </message_set>
        </AQXmlSend>  
      </Body>
</Envelope>

Enqueue Request Example--Publishing an ADT Message to a Multiconsumer Queue

The multiconsumer queue AQUSER.EMP_TOPIC has a payload of type EMP_TYP. EMP_TYP has the following structure: 

 create or replace type emp_typ as object (
     empno NUMBER(4),
     ename VARCHAR2(10),
     job VARCHAR2(9),
     mgr NUMBER(4),
     hiredate DATE,
     sal   NUMBER(7,2),
     comm  NUMBER(7,2)
     deptno NUMBER(2));

A PUBLISH request has the following format: 

<?xml version="1.0"?>   
<Envelope xmlns= "http://ns.oracle.com/AQ/schemas/envelope">

      <Body>
        <AQXmlPublish xmlns = "http://ns.oracle.com/AQ/schemas/access">
          <producer_options>
            <destination>AQUSER.EMP_TOPIC</destination>
          </producer_options>
          


          <message_set>
            <message_count>1</message_count>	
          
            <message>
              <message_number>1</message_number>
          
              <message_header>
                 <correlation>NEWEMP</correlation>
          	       <sender_id>
          	          <agent_name>scott</agent_name>
          	       </sender_id> 
              </message_header>
          
              <message_payload>	
          	    <EMP_TYP>
              	  <EMPNO>1111</EMPNO>
              	  <ENAME>Mary</ENAME>
          	      <MGR>5000</MGR>
          	      <HIREDATE>1996-01-01 0:0:0</HIREDATE>
                <SAL>10000</SAL>
                <COMM>100.12</COMM>
          	      <DEPTNO>60</DEPTNO>
          	    </EMP_TYP>
             </message_payload>
            </message>
          </message_set>
        </AQXmlPublish>  
      </Body>
</Envelope>

Enqueue Request Example--Sending a Message to a JMS Queue

The JMS queue AQUSER.JMS_TEXTQ has payload type JMS Text message (SYS.AQ$_JMS_TEXT_MESSAGE). The send request has the following format: 

<?xml version="1.0"?>
<Envelope xmlns= "http://ns.oracle.com/AQ/schemas/envelope">
      <Body>
      
        <AQXmlSend xmlns = "http://ns.oracle.com/AQ/schemas/access">
          <producer_options>
            <destination>AQUSER.JMS_TEXTQ</destination>
          </producer_options>
          
          <message_set>
            <message_count>1</message_count>	
          
            <message>
              <message_number>1</message_number>
          
              <message_header>
                <correlation>text_msg</correlation>
          	        <sender_id>
          	   	        <agent_name>john</agent_name>
          	        </sender_id>
              </message_header>
          
              <message_payload>	
          
              	<jms_text_message>	
               	 <oracle_jms_properties>
             	    <appid>AQProduct</appid>
          	       <groupid>AQ</groupid>
          	      </oracle_jms_properties>
          
              	  <user_properties>
              	    <property>
              	      <name>Country</name>
          	          <string_value>USA</string_value>
          	        </property>
          	        <property>
          	           <name>State</name>
          	          <string_value>California</string_value>
          	        </property>
          	       </user_properties>

          	       <text_data>All things bright and beautiful</text_data>
               </jms_text_message>
             </message_payload>
            </message>
          </message_set>          
        	</AQXmlSend>  
      </Body>
</Envelope>

Enqueue Request Example--Publishing a Message to a JMS Topic

The JMS topic AQUSER.JMS_MAP_TOPIC has payload type JMS Map message (SYS.AQ$_JMS_MAP_MESSAGE). The publish request has the following format: 

<?xml version="1.0"?>

<Envelope xmlns= "http://ns.oracle.com/AQ/schemas/envelope">
      <Body>
      
        <AQXmlPublish xmlns = "http://ns.oracle.com/AQ/schemas/access">

          <producer_options>
            <destination>AQUSER.JMS_MAP_TOPIC</destination>
          </producer_options>
          
          <message_set>
            <message_count>1</message_count>	
          
            <message>
              <message_number>1</message_number>
          
              <message_header>
                  	<correlation>toyota</correlation>
                  	<sender_id >
		                     <agent_name>john</agent_name>
		                  </sender_id>
                  	<recipient_list>
          	           <recipient>
          	              <agent_name>scott</agent_name>
          	           </recipient>
          	           <recipient>
          	              <agent_name>aquser</agent_name>
          	           </recipient>
          	           <recipient>
          	              <agent_name>jmsuser</agent_name>
          	           </recipient>
          	        </recipient_list>		
              </message_header>
          
              <message_payload>	
          
                	<jms_map_message>	
                	  <oracle_jms_properties>
          	          <reply_to>
		                       <agent_name>oracle</agent_name>
		                    </reply_to>
          	         <groupid>AQ</groupid>
          	       </oracle_jms_properties>
          
               	  <user_properties>
              	     <property>
              	       <name>Country</name>
          	           <string_value>USA</string_value>
          	         </property>
          	         <property>
          	           <name>State</name>
          	           <string_value>California</string_value>
          	         </property>
          	        </user_properties>
          
               	  <map_data>
              	    <item>
             	      <name>Car</name>
          	         <string_value>Toyota</string_value>
          	        </item>
          	        <item>
          	          <name>Color</name>
          	          <string_value>Blue</string_value>
             	     </item>
          	        <item>
              	      <name>Price</name>
              	      <int_value>20000</int_value>
              	    </item>
          	      </map_data>
               </jms_map_message>
             </message_payload>
            </message>
          </message_set>
         	</AQXmlPublish>  
      </Body>
</Envelope>

Enqueue Request Example--Sending a Message to a Queue with a RAW Payload

The queue AQUSER.RAW_MSGQ has a payload of type RAW. The SEND request has the following format: 

<?xml version="1.0"?>
   <Envelope  xmlns =  "http://ns.oracle.com/AQ/schemas/envelope">
   <Body>                     
      <AQXmlSend xmlns = "http://ns.oracle.com/AQ/schemas/access">
        <producer_options>
          <destination>AQUSER.RAW_MSGQ</destination>
        </producer_options>
        <message_set>
          <message_count>1</message_count>	

          <message>
             <message_number>1</message_number>

                 <message_header>
                   <correlation>TKAXAS11</correlation>
                   <sender_id>
                      <agent_name>scott</agent_name>
                   </sender_id>	
                 </message_header>
                 <message_payload>
                    
<RAW>426C6F622064617461202D20626C6F622064617461202D20626C6F62206461746120426C6F6
22064617461202D20626C6F622064617461202D20626C6F62206461746120426</RAW>
                 </message_payload>
               </message>
            </message_set>
          </AQXmlSend>
      </Body>
</Envelope>

Enqueue Request Example--Sending/Publishing and Committing the Transaction

<?xml version="1.0"?>   
<Envelope xmlns= "http://ns.oracle.com/AQ/schemas/envelope">

      <Body>
        <AQXmlPublish xmlns = "http://ns.oracle.com/AQ/schemas/access">
          <producer_options>
            <destination>AQUSER.EMP_TOPIC</destination>
          </producer_options>
          
          <message_set>
            <message_count>1</message_count>	
          
            <message>
              <message_number>1</message_number>
          
              <message_header>
          	<correlation>NEWEMP</correlation>
          	<sender_id>
          	   <agent_name>scott</agent_name>
          	</sender_id> 
              </message_header>
          
              <message_payload>	
                <EMP_TYP>
                  <EMPNO>1111</EMPNO>
              	    <ENAME>Mary</ENAME>
                  <MGR>5000</MGR>
          	        <HIREDATE>1996-01-01 0:0:0</HIREDATE>
                  <SAL>10000</SAL>
                  <COMM>100.12</COMM>
          	        <DEPTNO>60</DEPTNO>
          	     </EMP_TYP>
             </message_payload>
            </message>
          </message_set>

        <AQXmlCommit/>

        </AQXmlPublish>  
      </Body>
</Envelope>

Client Requests for Dequeue

Client requests for dequeue use the AQXmlReceive method, which takes the arguments and argument attributes shown in Table 17-3. Required arguments are shown in bold.

Table 17-3 Client Requests for Dequeue--Arguments and Attributes for AQXmlReceive
Argument  Attribute 

consumer_options 

destination--specify the queue/topic from which messages are to be received. The destination element has an attribute lookup_type which determines how the destination element value is interpreted

  • DATABASE (default)--destination is interpreted as schema.queue_name

  • LDAP--the LDAP server is used to resolve the destination

 

 

consumer_name--Name of the consumer. Only those messages matching the consumer name are accessed. If a queue is not set up for multiple consumers, then this field should not be specified 

 

wait_time--the time (in seconds) to wait if there is currently no message available which matches the search criteria 

 

selector--criteria used to select the message, specified as one of:

  • correlation--the correlation identifier of the message to be dequeued.

  • message_id-- the message identifier of the message to be dequeued

  • condition--dequeue message that satisfy this condition.

A condition is specified as a Boolean expression using syntax similar to the WHERE clause of a SQL query. This Boolean expression can include conditions on message properties, user data properties (object payloads only), and PL/SQL or SQL functions (as specified in the where clause of a SQL query). Message properties include priority, corrid and other columns in the queue table

To specify dequeue conditions on a message payload (object payload), use attributes of the object type in clauses. You must prefix each attribute with tab.user_data as a qualifier to indicate the specific column of the queue table that stores the payload. The deq_condition parameter cannot exceed 4000 characters.  

 

visibility

  • ON_COMMIT (default)--The dequeue is part of the current transaction. The operation is complete when the transaction commits.

  • IMMEDIATE--effects of the dequeue are visible immediately after the request is completed. The dequeue is not part of the current transaction. The operation constitutes a transaction on its own.

 

 

dequeue_mode--Specifies the locking behavior associated with the dequeue. The dequeue_mode can be specified as one of:

  • REMOVE (default): Read the message and update or delete it. This is the default. The message can be retained in the queue table based on the retention properties.

  • BROWSE: Read the message without acquiring any lock on the message. This is equivalent to a select statement.

  • LOCKED: Read and obtain a write lock on the message. The lock lasts for the duration of the transaction. This is equivalent to a select for update statement.

 

 

navigation_mode--Specifies the position of the message that will be retrieved. First, the position is determined. Second, the search criterion is applied. Finally, the message is retrieved. The navigation_mode can be specified as one of:

  • FIRST_MESSAGE: Retrieves the first message which is available and matches the search criteria. This resets the position to the beginning of the queue.

  • NEXT_MESSAGE (default): Retrieve the next message which is available and matches the search criteria. If the previous message belongs to a message group, then AQ retrieves the next available message which matches the search criteria and belongs to the message group. This is the default.

  • NEXT_TRANSACTION: Skip the remainder of the current transaction group (if any) and retrieve the first message of the next transaction group. This option can only be used if message grouping is enabled for the current queue.

 

 

transformation--the PL/SQL transformation to be invoked after the message is dequeued 

AQXmlCommit 

this is an empty element--if specified, the user transaction is committed at the end of the request 

The following examples show dequeue requests using different attributes of AQXmlReceive.

Dequeue Request Example--Receiving Messages from a Single-Consumer Queue

Using the single-consumer queue QS.NEW_ORDERS_QUE, the receive request has the following format: 

<?xml version="1.0"?>

<Envelope xmlns= "http://ns.oracle.com/AQ/schemas/envelope">
      <Body>
        <AQXmlReceive xmlns = "http://ns.oracle.com/AQ/schemas/access">
          <consumer_options>
            <destination>QS.NEW_ORDERS_QUE</destination>
            <wait_time>0</wait_time>
          </consumer_options>
        	</AQXmlReceive>  
      </Body>
</Envelope>

Dequeue Request Example--Receiving Messages from a Multiconsumer Queue

Using the multiconsumer queue AQUSER.EMP_TOPIC with subscriber APP1, the receive request has the following format: 

<?xml version="1.0"?>
<Envelope xmlns= "http://ns.oracle.com/AQ/schemas/envelope">
      <Body>
        <AQXmlReceive xmlns = "http://ns.oracle.com/AQ/schemas/access">
          <consumer_options>
            <destination>AQUSER.EMP_TOPIC</destination>
            <consumer_name>APP1</consumer_name>
            <wait_time>0</wait_time>
            <navigation_mode>FIRST_MESSAGE</navigation_mode> 
          </consumer_options>
        	</AQXmlReceive>  
      </Body>
</Envelope>

Dequeue Request Example--Receiving Messages from a Specific Correlation ID

Using the single consumer queue QS.NEW_ORDERS_QUE, to receive messages with correlation ID NEW, the receive request has the following format: 

<Envelope xmlns= "http://ns.oracle.com/AQ/schemas/envelope">
      <Body>
        <AQXmlReceive xmlns = "http://ns.oracle.com/AQ/schemas/access">
          <consumer_options>
            <destination>QS.NEW_ORDERS_QUE</destination>
            <wait_time>0</wait_time>
            <selector>
                 <correlation>NEW</correlation>
            </selector>
          </consumer_options>
        	</AQXmlReceive>  
      </Body>
</Envelope>

Dequeue Request Example--Receiving Messages that Satisfy a Specific Condition

Using the multiconsumer queue AQUSER.EMP_TOPIC with subscriber APP1 and condition deptno=60, the receive request has the following format: 

<?xml version="1.0"?>
<Envelope xmlns= "http://ns.oracle.com/AQ/schemas/envelope">
      <Body>
        <AQXmlReceive xmlns = "http://ns.oracle.com/AQ/schemas/access">
          <consumer_options>
            <destination>AQUSER.EMP_TOPIC</destination>
            <consumer_name>APP1</consumer_name>
            <wait_time>0</wait_time>
            <selector>
                 <condition>tab.user_data.deptno=60</condition>
            </selector>
          </consumer_options>
        	</AQXmlReceive>  
      </Body>
</Envelope>

Dequeue Request Example--Receiving Messages and Committing

In the dequeue request examples, if you include AQXmlCommit at the end of the RECEIVE request, the transaction is committed upon completion of the operation. In "Dequeue Request Example--Receiving Messages from a Multiconsumer Queue", the receive request can include the commit flag as follows: 

 <?xml version="1.0"?>

<Envelope xmlns= "http://ns.oracle.com/AQ/schemas/envelope">
      <Body>
        <AQXmlReceive xmlns = "http://ns.oracle.com/AQ/schemas/access">
          <consumer_options>
            <destination>QS.NEW_ORDERS_QUE</destination>
            <wait_time>0</wait_time>
          </consumer_options>

          	<AQXmlCommit/>

        	</AQXmlReceive>  
      </Body>
</Envelope>

Dequeue Request Example--Browsing Messages

Messages are dequeued in REMOVE mode by default. To receive messages from QS.NEW_ORDERS_QUE in BROWSE mode, modify the receive request as follows: 

<?xml version="1.0"?>

<Envelope xmlns= "http://ns.oracle.com/AQ/schemas/envelope">
      <Body>
        <AQXmlReceive xmlns = "http://ns.oracle.com/AQ/schemas/access">
          <consumer_options>
            <destination>QS.NEW_ORDERS_QUE</destination>
            <wait_time>0</wait_time>
            <dequeue_mode>BROWSE</dequeue_mode>
          </consumer_options>
         	</AQXmlReceive>  
      </Body>
</Envelope>

Client Requests for Registration

Client requests for registration use the AQXmlRegister method, which takes the arguments and argument attributes shown in Table 17-4. Required arguments are shown in bold.

.
Table 17-4 Client Registration--Arguments and Attributes for AQXmlRegister
Argument  Attribute 

register_options 

destination--specify the queue or topic on which notifications are registered. The destination element has an attribute lookup_type which determines how the destination element value is interpreted

  • DATABASE (default)--destination is interpreted as schema.queue_name

  • LDAP--the LDAP server is used to resolve the destination

 

 

consumer_name--the consumer name for multiconsumer queues or topics. For single consumer queues, this parameter must not be specified 

 

notify_url--where notification is sent when a message is enqueued. The form can be http://<url> or mailto://<email address> or plsql://<pl/sql procedure>. 

Register Request Example--Registering for Notification at an Email Address

To notify an email address of messages enqueued for consumer APP1 in queue AQUSER.EMP_TOPIC, the register request has the following format: 

<?xml version="1.0"?>
<Envelope xmlns= "http://ns.oracle.com/AQ/schemas/envelope">
      <Body>
      
        <AQXmlRegister xmlns = "http://ns.oracle.com/AQ/schemas/access">

          <register_options>
            <destination>AQUSER.EMP_TOPIC</destination>
            <consumer_name>APP1</consumer_name>
            <notify_url>mailto:app1@hotmail.com</notify_url>
          </register_options>
          
          <AQXmlCommit/>
          
        	</AQXmlRegister>  
      </Body>
</Envelope>

Client Requests to Commit a Transaction

A request to commit all actions performed by the user in a session uses the AQXmlCommit method.

Commit Request Example

A commit request has the following format. 

<?xml version="1.0"?>
<Envelope xmlns="http://ns.oracle.com/AQ/schemas/envelope">
   <Body>
      <AQXmlCommit xmlns="http://ns.oracle.com/AQ/schemas/access"/>
   </Body>
</Envelope>
Client Requests to Rollback a Transaction

A request to roll back all actions performed by the user in a session uses the AQXmlRollback method. Actions performed with IMMEDIATE visibility are not rolled back.

Rollback Request Example

A rollback request has the following format: 

<?xml version="1.0"?>
<Envelope xmlns="http://ns.oracle.com/AQ/schemas/envelope">
   <Body>
      <AQXmlRollback xmlns="http://ns.oracle.com/AQ/schemas/access"/>
   </Body>
</Envelope>

Server Response to Enqueue

The response to an enqueue request to a single-consumer queue uses the AQXmlSendResponse method. The components of the response are shown in Table 17-5.

.
Table 17-5 Server Response to an Enqueue to a Single-Consumer Queue (AQXmlSendResponse)
Response  Attribute 

status_response

 

status_code--indicates success (0) or failure (-1)

error_code--Oracle code for the error

error_message--description of the error 

send_result 

destination--where the message was sent

message_id--identifier for every message sent 

Server Request Example--Enqueuing a Single Message to a Single-Consumer Queue

The result of a SEND request to the single consumer queue QS.NEW_ORDERS_QUE has the following format: 

<?xml version = '1.0'?>
<Envelope xmlns="http://ns.oracle.com/AQ/schemas/envelope">
   <Body>
      <AQXmlSendResponse xmlns="http://ns.oracle.com/AQ/schemas/access">
         <status_response>
            <status_code>0</status_code>
         </status_response>
         <send_result>
            <destination>QS.NEW_ORDERS_QUE</destination>
            <message_id>12341234123412341234</message_id>
         </send_result>
      </AQXmlSendResponse>
   </Body>
</Envelope>

The response to an enqueue request to a multiconsumer queue or topic uses the AQXmlPublishResponse method. The components of the response are shown in Table 17-6.

.
Table 17-6 Server Response to an Enqueue to a Multiconsumer Queue or Topic (AQXmlPublishResponse)
Response  Attribute 

status_response

 

status_code--indicates success (0) or failure (-1)

error_code--Oracle code for the error

error_message--description of the error 

publish_result 

destination--where the message was sent

message_id--identifier for every message sent 

Server Request Example--Enqueuing to a Multiconsumer Queue

The result of a SEND request to the multiconsumer queue AQUSER.EMP_TOPIC has the following format: 

<?xml version = '1.0'?>
<Envelope xmlns="http://ns.oracle.com/AQ/schemas/envelope">
   <Body>
      <AQXmlPublishResponse xmlns="http://ns.oracle.com/AQ/schemas/access">
         <status_response>
            <status_code>0</status_code>
         </status_response>
         <publish_result>
            <destination>AQUSER.EMP_TOPIC</destination>
            <message_id>23434435435456546546546546</message_id>
         </publish_result>
      </AQXmlPublishResponse>
   </Body>
</Envelope>

Server Response to a Dequeue Request

The response to a dequeue request uses the AQXmlReceiveResponse method. The components of the response are shown in Table 17-7.

.
Table 17-7 Server Response to a Dequeue from a Queue or Topic (AQXmlReceiveResponse)
Response  Attribute 

status_response

 

status_code--indicates success (0) or failure (-1)

error_code--Oracle code for the error

error_message--description of the error 

receive_result 

destination--where the message was sent

message_set--the set of messages dequeued 

Dequeue Response Example--Receiving Messages from an ADT Queue (AQXmlReceiveResponse)

The result of a RECEIVE request on the queue AQUSER.EMP_TOPIC with a payload of type EMP_TYP has the following format: 

<?xml version = '1.0'?>
<Envelope xmlns="http://ns.oracle.com/AQ/schemas/envelope">
   <Body>
      <AQXmlReceiveResponse xmlns="http://ns.oracle.com/AQ/schemas/access">
         <status_response>
            <status_code>0</status_code>
         </status_response>
         <receive_result>
            <destination>AQUSER.EMP_TOPIC</destination>
            <message_set>
               <message_count>1</message_count>
               <message>
                  <message_number>1</message_number>
                  <message_header>
                     <message_id>1234344545565667</message_id>
                     <correlation>TKAXAP10</correlation>
                     <priority>1</priority>
                     <delivery_count>0</delivery_count>
                     <sender_id>
                        <agent_name>scott</agent_name>
                     </sender_id>
                     <message_state>0</message_state>
                  </message_header>
                  <message_payload>
                    <EMP_TYP>
              	        <EMPNO>1111</EMPNO>
              	        <ENAME>Mary</ENAME>
          	            <MGR>5000</MGR>
          	            <HIREDATE>1996-01-01 0:0:0</HIREDATE>
                      <SAL>10000</SAL>
                      <COMM>100.12</COMM>
          	            <DEPTNO>60</DEPTNO>
          	          </EMP_TYP>
                 </message_payload>
               </message>
            </message_set>
         </receive_result>
      </AQXmlReceiveResponse>
   </Body>
</Envelope>

Dequeue Response Example--Receiving Messages from a JMS Queue

The result of a RECEIVE request on a queue with a payload of type JMS Text message has the following format: 

<?xml version = '1.0'?>
<Envelope xmlns="http://ns.oracle.com/AQ/schemas/envelope">
<Body>
      <AQXmlReceiveResponse xmlns="http://ns.oracle.com/AQ/schemas/access">
         <status_response>
            <status_code>0</status_code>
         </status_response>
         <receive_result>
            <destination>AQUSER.JMS_TEXTQ</destination>
            <message_set>
               <message_count>1</message_count>
               <message>
                  <message_number>1</message_number>
                  <message_header>
                     <message_id>12233435454656567</message_id>
                     <correlation>TKAXAP01</correlation>
                     <delay>0</delay>
                     <priority>1</priority>
                     <message_state>0</message_state>
                     <sender_id>
                        <agent_name>scott</agent_name>
                     </sender_id>
                  </message_header>
                  <message_payload>
                     <jms_text_message>
                        <oracle_jms_properties>
                           <reply_to>
                              <agent_name>oracle</agent_name>
                              <address>redwoodshores</address>
                              <protocol>100</protocol>
                           </reply_to>
                           <userid>AQUSER</userid>
                           <appid>AQProduct</appid>
                           <groupid>AQ</groupid>
                           <timestamp>01-12-2000</timestamp>
                           <recv_timestamp>12-12-2000</recv_timestamp>
                        </oracle_jms_properties>
                        <user_properties>
                           <property>
                              <name>Country</name>
                              <string_value>USA</string_value>
                           </property>
                           <property>
                              <name>State</name>
                              <string_value>California</string_value>
                           </property>
                        </user_properties>
                        <text_data>All things bright and beautiful</text_data>
                     </jms_text_message>
                  </message_payload>
               </message>
            </message_set>
         </receive_result>
      </AQXmlReceiveResponse>
   </Body>
</Envelope>

Server Response to a Register Request

The response to a register request uses the AQXmlRegisterResponse method, which consists of status_response. (SeeTable 17-7 for a description of status_response.)

Commit Response

The response to a commit request uses the AQXmlCommitResponse method, which consists of status_response. (SeeTable 17-7 for a description of status_response.)

Example

The response to a commit request has the following format: 

<?xml version = '1.0'?>
<Envelope xmlns="http://ns.oracle.com/AQ/schemas/envelope">
   <Body>
      <AQXmlCommitResponse xmlns="http://ns.oracle.com/AQ/schemas/access">
         <status_response>
            <status_code>0</status_code>
         </status_response>
      </AQXmlCommitResponse>
   </Body>
</Envelope>

Rollback Response

The response to a rollback request uses the AQXmlRollbackResponse method, which consists of status_response. (SeeTable 17-7 for a description of status_response.)

Notification

When an event for which a client has registered occurs, a notification is sent to the client at the URL specified in the REGISTER request. AQXmlNotification consists of:

Response in Case of Error

In case of an error in any of the above requests, a FAULT is generated. The FAULT element consists of:

Example

A FAULT message has the following format: 

<?xml version = '1.0'?>
<Envelope xmlns="http://ns.oracle.com/AQ/schemas/envelope">
   <Body>
      <Fault xmlns="http://ns.oracle.com/AQ/schemas/envelope">
         <faultcode>100</faultcode>
         <faultstring>Server Fault</faultstring>
         <detail>
            <status_response>
               <status_code>-1</status_code>
               <error_code>410</error_code>
               <error_message>JMS-410: XML SQL Excetpion 
ORA-24031: invalid value, OWNER_NAME should be non-NULL
ORA-06512: at "SYS.DBMS_AQJMS", line 177
ORA-06512: at line 1
</error_message>
            </status_response>
         </detail>
      </Fault>
   </Body>
</Envelope>
Go to previous page Go to beginning of chapter Go to next page
Oracle
Copyright © 1996-2001, Oracle Corporation.
All Rights Reserved.
Go To Documentation Library
Home		 Go To Product List
Book List		 Go To Table Of Contents
Contents		 Go To Index
Index
Master Index
Feedback