4
Sample Use Cases

This chapter describes sample use cases for the Advanced Queuing adapter.

Advanced Queuing Adapter Sample Use Cases

The following are sample use cases for the Advanced Queuing adapter.

Case One: The Advanced Queuing Publishes and Subscribes with RAW Payload

The Advanced Queuing adapter publishes and subscribes using RAW Payload. The following case uses one installation of an Advanced Queuing adapter that publishes a message and subscribes to the same event. Therefore, the log files will indicate that an outbound message is followed by an inbound message.

Using SQL*PLUS utility, run the following script to create the application user:

connect system/manager 
create user aquser identified by manager; 
grant connect, resource to aquser; 
grant aq_user_role, aq_administrator_role to aquser; 

Design Time Steps

The following steps describe the procedures necessary to publish and subscribe a message containing RAW XML payload. The event created is createCustomer where the payload corresponds to the customer.dtd provided. For outbound messages, the application queues are xml_raw_q1. For inbound messages, the application queues are xml_raw_q2.

1. Create a business object in iStudio. On the Create Business Object dialog, enter customer in the Business Object Name field.

2. Create the event in iStudio. On the Create Event dialog, complete the following:
   1. Select customer for the Business Object.

   2. Enter createCustomer in the Event Name field.

   3. Click Import and select XML to import the customer.dtd file.

   4. Select customer as the root element.

3. Create an application in iStudio. On the Create Application dialog, enter aqapp in the Application Name field.

4. Create a Published Event using the Publish Event Wizard in iStudio:
   1. On the Select an Event page:
      • Select aqapp for the Application.

      • Select AQ as the Message Type.

      • Expand the tree in the Select an Event box and select createCustomer.

   2. On the Define Application View page:
      • Click Import and select XML to import the customer.dtd file.

      • Select customer as the root element.

      • Click Tracking Fields and select the customer.id tracking fields.

   3. Define a mapping so that ObjectCopy is completed from the application view customer to the common view customer on the Define Mappings page.

   4. Click Finish.

5. Create a Subscribed Event using the Subscribe Wizard in iStudio:
   1. On the Select an Event page:
      • Select aqapp for the Application.

      • Select AQ as the Message Type.

      • Expand the tree in the Select an Event box and select createCustomer.

   2. On the Define Application View Page:
      • Click Import and select XML on the Define Application View page to import the customer.dtd file.

      • Select customer as the root element.

   3. Define a mapping so that ObjectCopy is completed from the application view customer to the common view customer on the Define Mappings page.

   4. Click Finish.

Runtime Steps:

The following steps describe the runtime procedures necessary to publish and subscribe a message containing RAW XML payload.

1. Create the database user aquser by running the create_user.sql script in SQL*PLUS. Log in as the system user.

2. Log in as aquser/manager using the SQL*PLUS utility.

3. Create Advanced Queues by executing the CreateAQ.sql script.

   See Also: "Case Two: The Advanced Queuing Invokes and Implements with Oracle Object Type Payload"

   
   
4. Enqueue an XML message by executing the EnqCust.sql script.

5. Set the agent_log_level parameter to 2 in the adapter.ini file.

6. Delete the persistence directory and start the adapter.

7. Verify that the message has been published, subscribed to, and delivered to xml_raw_q2 by viewing the log files in the log directory of the Advanced Queuing adapter.

Related Files

The following files are related to the steps in case one.

• DTD to be imported:

  customer.dtd 
  <!ELEMENT customer (id,name,address*)> 
  <!ELEMENT address (city, state)> 
  <!ELEMENT city (#PCDATA)> 
  <!ELEMENT state (#PCDATA)> 
  <!ELEMENT name (#PCDATA)> 
  <!ELEMENT id (#PCDATA)> 
  
  

• Script to create the Raw Queues xml_raw_q1, xml_raw_q2:

  CreateAQ.sql 
  EXECUTE dbms_aqadm.create_queue_table (queue_table => 'RawMsgs_qtab', queue_
  payload_type => 'RAW', multiple_consumers => FALSE); 
  EXECUTE dbms_aqadm.create_queue (queue_name => 'xml_raw_q1', queue_table => 
  'RawMsgs_qtab'); 
  EXECUTE dbms_aqadm.start_queue (queue_name => 'xml_raw_q1'); 
  EXECUTE dbms_aqadm.create_queue (queue_name => 'xml_raw_q2', queue_table => 
  'RawMsgs_qtab'); 
  EXECUTE dbms_aqadm.start_queue (queue_name => 'xml_raw_q2'); 
  
  

• Script to Enqueue a createCustomer event on xml_raw_q1 queue:

  EnqCust.sql
  DECLARE
    enqueue_options     dbms_aq.enqueue_options_t; 
    message_properties  dbms_aq.message_properties_t; 
    msgid               RAW(16); 
    payload             RAW(5000); 
  BEGIN
    payload := utl_raw.cast_to_raw('<?xml version="1.0" standalone="no"?> 
        <customer><id>10</id> 
        <name>Herb Stiel</name> 
        <address> 
    <city>SanMateo</city> 
          <state>California</state> 
       </address> 
      </customer>'); 
    dbms_aq.enqueue(queue_name         => 'xml_raw_q1', 
            enqueue_options    => enqueue_options, 
            message_properties => message_properties, 
            payload            => payload, 
            msgid              => msgid); 
    COMMIT; 
  END; 
  / 
  
  

• create_user.sql

  CREATE USER aquser IDENTIFIED BY manager;
  GRANT CONNECT, RESOURCE TO aquser;
  GRANT AQ_USER_ROLE, AQ_ADMINISTRATOR_ROLE TO aquser;
  

Case Two: The Advanced Queuing Invokes and Implements with Oracle Object Type Payload

The Advanced Queuing adapter invokes and implements with Oracle Object Type Payload. This case uses one installation of an Advanced Queuing adapter that sends a request, receives the request, sends back a reply, and receives the reply. Therefore, the log files will indicate four different message entries.

Design Time Steps

The following steps describe the procedures necessary to invoke and implement a procedure. An Oracle Object Type is used as a payload.

1. Log in as the aquser/manager using the SQL*PLUS utility.

2. Create the addr and cust Oracle Object Types by executing the CreateADT.sql file.

3. Create the necessary queues by executing the CreateADTQueue.sql script.

4. Create a Business Object in iStudio. On the Create Business Object dialog, enter customer in the Business Object Name field.

5. Create a Procedure in iStudio. On the Create Procedure dialog, complete the following:
   1. Select customer for the Business Object.

   2. Enter updateCustomer in the Procedure Name field.

   3. Click Import and select XML to import the customer.dtd file.

   4. Select the IN/OUT arguments option.

6. Create an application data type for the aqapp application. On the Create Data Type dialog, complete the following:
   1. Enter DTDs in the Common Data Type Name field.

   2. Click Import and select XML to import the customer.dtd file.

   3. Select customer as the root element.

7. Reload the project.

8. Create a new invoked procedure for the aqapp application. Using the Invoke Wizard, complete the following:
   1. On the Select a Procedure page:
      • Select aqapp for the Application.

      • Select AQ for the Message Type.

      • Expand the tree in the Select a Procedure box and select updateCustomer.

   2. On the Define Application View page:
      • Click Import and select Database.

      • Log in as the system user on the Database Login dialog.

      • On the Oracle Database Browser dialog, expand the AQUSER tree and drill down to select AQUSER.MY_QUEUE_TYPE.

      • Click Done.

   3. Create the following mapping on the Define Mapping IN Arguments page:
      • For aqapp view to the common view: updateCustomer:IN - ObjectCopy - updateCustomer:IN

   4. Create the following mapping on the Define Mapping OUT Arguments page:
      • For common view to aqapp: updateCustomer:OUT - ObjectCopy - updateCustomer:OUT

9. Repeat step 8 to create a new implemented procedure using the Implement Wizard.

10. Set up application queues in iStudio from the Deploy Navigation tab:
    1. Select aqapp then select Application Queues.

    2. Send Request: updateCustomer, Queue: xml_q1

    3. Receive Request: updateCustomer, Queue: xml_q2

    4. Send Reply: updateCustomer, Queue: xml_q2

    5. Receive Reply: updateCustomer, Queue: xml_q3

Runtime Steps

The following steps describe the runtime procedures that implements and invokes a procedure with Oracle Object Type payload.

1. Execute the EnqueueADT.sql script to enqueue an XML message.

   See Also: "Case Two: The Advanced Queuing Invokes and Implements with Oracle Object Type Payload"

   
   
2. Set the agent_log_level parameter to 2 in the adapter.ini file.

3. Delete the persistence directory and start the adapter.

4. Verify the following by viewing the adapter log files:
   • Request was dequeued from xml_q1 and enqueued to the hub queue oai_hub_queue.

   • Request was dequeued from oai_hub_queue and enqueued to xml_q2.

   • Reply was dequeued from xml_q2 and enqueued to the hub queue oai_hub_queue.

   • Reply was dequeued from oai_hub_queue and enqueued to xml_q3.

Related Files

The following files are related to the runtime steps in case two.

• CreateADT.sql

  CREATE TYPE my_queue_type as object(id number, payload varchar2(1000));
  / 
  
  

• CreateADTQueue.sql

  EXECUTE dbms_aqadm.create_queue_table (queue_table => 'ADTMsgs_qtab', queue_
  payload_type => 'my_queue_type', multiple_consumers =>
  FALSE); 
  
  EXECUTE dbms_aqadm.create_queue (queue_name => 'xml_q1', queue_table => 
  'ADTMsgs_qtab'); 
  EXECUTE dbms_aqadm.start_queue (queue_name => 'xml_q1'); 
  
  EXECUTE dbms_aqadm.create_queue (queue_name => 'xml_q2', queue_table => 
  'ADTMsgs_qtab'); 
  EXECUTE dbms_aqadm.start_queue (queue_name => 'xml_q2'); 
  
  EXECUTE dbms_aqadm.create_queue (queue_name => 'xml_q3', queue_table => 
  'ADTMsgs_qtab'); 
  EXECUTE dbms_aqadm.start_queue (queue_name => 'xml_q3'); 
  
  

• EnqueueADT.sql

  DECLARE 
        enqueue_options     dbms_aq.enqueue_options_t; 
        message_properties  dbms_aq.message_properties_t; 
        msgid               RAW(16); 
        payload             cust; 
  BEGIN 
        payload := my_queue_type(123,
                     '<customer><id>10</id> 
                      <name>Herb Stiel</name> 
                      <address> 
                         <city>SanMateo</city> 
                         <state>California</state> 
                      </address> 
                      </customer>');
  dbms_aq.enqueue(queue_name         => 'xml_q1', 
                        enqueue_options    => enqueue_options, 
                        message_properties => message_properties, 
                        payload            => payload, 
                        msgid              => msgid); 
        COMMIT; 
  END; 
  /