Internet Access to Advanced Queuing, 6 of 9

Using HTTP to Access the AQ XML Servlet

The procedures for an AQ client to make a request to the AQ servlet using HTTP and for the AQ servlet to process the request are as follows:

AQ Client Request to the AQ Servlet Using HTTP

The client opens an HTTP(S) connection to the server.

For example, https://aq.us.oracle.com:8000/aqserv/servlet/AQTestServlet

This opens a connection to port 8000 on aq.us.oracle.com.
The client logs in to the server by either:
- HTTP basic authentication (with or without SSL)
- SSL certificate-based client authentication

The client constructs the XML message representing the Send, Publish, Receive or Register request.

Example:

<?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>OE.OE_NEW_ORDERS_QUE</destination>
          </producer_options>
       
          <message_set>
            <message_count>1</message_count>	          
            <message>
              <message_number>1</message_number>   
              <message_header>
		                 	<correlation>XML_ADT_SINGLE_ENQ</correlation>
                 	<sender_id>
          	           <agent_name>john</agent_name>
          	       </sender_id>
              </message_header>
              <message_payload>	
              <ORDER_TYP>
                     <ORDERNO>100</ORDERNO>
                     <STATUS>NEW</STATUS>
                     <ORDERTYPE>NORMAL</ORDERTYPE>
                     <ORDERREGION>EAST</ORDERREGION>
                     <CUSTOMER>
                        <CUSTNO>1001233</CUSTNO>
                        <CUSTID>JOHN</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>
                     <CCNUMBER>NUMBER01</CCNUMBER>
                     <ORDER_DATE>2000-08-23 0:0:0</ORDER_DATE>
               </ORDER_TYP>
             </message_payload>
            </message>
          </message_set>
          </AQXmlSend>
      </Body>
</Envelope>

The client sends an HTTP POST to the servlet at the remote server.

See the $ORACLE_HOME/demo directory for sample code of POST requests using HTTP.

AQ Servlet Processes a Request Using HTTP

The server accepts the client HTTP(S) connection.
The server authenticates the user (AQ agent) specified by the client.
The server receives the POST request.
The AQ servlet is invoked.

If this is the first request being serviced by this servlet, the servlet is initialized--its init() method is invoked. The init () method creates a connection pool to the Oracle server using the AQxmlDataSource parameters (SID, host, port, AQ servlet super-user name, password) provided by the client.
The servlet processes the message as follows:
- If this is the first request from this client, a new HTTP session is created. The XML message is parsed and its contents are validated. If a session ID is passed by the client in the HTTP headers, then this operation is performed in the context of that session. This is described in detail in the next section.
- The servlet determines which object (queue and topic) the agent is trying to perform operations on:
  
  For example, in the client request (step 3 in "AQ Client Request to the AQ Servlet Using HTTP"), the agent JOHN is trying to access OE.OE_NEW_ORDERS_QUE.
- The servlet looks through the list of database users that map to this AQ agent (using the AQ$INTERNET_USERS view). If any one of these db_users has privileges to access the queue/topic specified in the request, the AQ servlet super-user creates a session on behalf of this db_user.
  
  For example, where the agent JOHN is mapped to the database user OE using the DBMS_AQADM.ENABLE_DB_ACCESS call, the servlet will create a session for the agent JOHN with the privileges of database user OE. (See "Mapping the AQ Agent to Database Users" for information on ENABLE_DB_ACCESS.)
- A new database transaction is started if no transaction is active in the HTTP session. Subsequent requests in the session will be part of the same transaction until an explicit COMMIT or ROLLBACK request is made.
- The requested operation (SEND/PUBLISH/RECEIVE/REGISTER/COMMIT/ROLLBACK) is performed.
- The response is formatted as an XML message and sent back the client.
  
  For example, the response for the above request may be as follows:
```
 <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>OE.OE_NEW_ORDERS_QUE</destination>
            <message_id>12341234123412341234123412341234</message_id>
         </send_result>
      </AQXmlSendResponse>
   </Body>
</Envelope>
```
- The response also includes the session id in the HTTP headers as a cookie. For example, Tomcat sends back session IDs as JSESSIONID=239454ds2343. If the operation does not commit the transaction, the transaction will remain active until an explicit commit/rollback call is received. The effects of the transaction are visible only after it is committed. If the transaction remains inactive for 120 seconds, it is automatically aborted.

User Sessions and Transactions

After a client is authenticated and connects to the AQ servlet, an HTTP session is created on behalf of the user. The first request in the session also implicitly starts a new database transaction. This transaction remains open until it is explicitly committed or aborted. The responses from the servlet includes the session ID in the HTTP headers as cookies.

If the client wishes to continue work in the same transaction, it must include this HTTP header containing the session ID cookie in subsequent requests. This is automatically done by most Web browsers. However, if you are using a Java or C client to post requests, this has to be done programmatically. An example of a Java program used to post requests as part of the same session is given in $ORACLE_HOME/demo directory.

An explicit commit or rollback must be issued to end the transaction. The commit or rollback requests can also be included as part of other AQ operations (Send, Publish, Receive, Register).

Each HTTP session has a default timeout of 120 seconds. If the user does not commit or rollback the transaction in 120 seconds after the last request that session, the transaction is automatically aborted. This timeout can be modified in the init() method of the servlet by using setSessionMaxInactiveTime(). See "Customizing the AQ Servlet" for more information.