4 Sample Use Cases

This chapter describes the sample use cases for the AQ adapter.

Case One: Publish and Subscribe with RAW Payload
Case Two: Invoke and Implement with Oracle Object Type Payload

Case One: Publish and Subscribe with RAW Payload

In this case, the AQ adapter publishes and subscribes using RAW Payload. This use case uses one installation of an AQ adapter that publishes a message and subscribes to the same event. Thus, the log files will indicate that an outbound message is followed by an inbound message.

Design Time Steps

This section describes the steps for publishing and subscribing a message containing RAW payload. The event created is createCustomer where the payload corresponds to the customer.dtd file. For outbound messages, the application queue is xml_raw_q1. For inbound messages, the application queue is xml_raw_q2.

Create a business object in iStudio. In the Create Business Object dialog box, enter customer in the Business Object Name field.
Create the event in iStudio. In the Create Event dialog box, complete the following:
1. Select customer from 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.
Create an application in iStudio. In the Create Application dialog box, enter aqapp in the Application Name field.
Create a Published Event using the Publish Event Wizard in iStudio:
1. In the Select an Event dialog box:
  - Select aqapp for the Application.
  - Select AQ as the Message Type.
  - Expand the list in the Select an Event box and select createCustomer.
2. On the Define Application View dialog box:
  - 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 an ObjectCopy transformation from the application view customer to the common view customer on the Define Mappings dialog box.
4. Click Finish.
Create a Subscribed Event using the Subscribe Wizard in iStudio:
1. On the Select an Event dialog box:
  - Select aqapp for the Application.
  - Select AQ as the Message Type.
  - Expand the list in the Select an Event box and select createCustomer.
2. On the Define Application View dialog box:
  - Click Import and select XML on the Define Application View dialog box 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 dialog box.
4. Click Finish.
Set up application queues in iStudio from the Deploy Navigation tab:
1. Select aqapp, and then select Application Queues.
2. Publish: createCustomer, Queue: xml_raw_q1
3. Subscribe: createCustomer, Queue: xml_raw_q2

Run-Time Steps

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;

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

Create the database user aquser by running the create_user.sql script.
Log in as aquser/manager.
Create Advanced Queues by executing the CreateAQ.sql script.

See Also:
"Design Time Steps"
Enqueue an XML message by executing the EnqCust.sql script.
Set the agent_log_level parameter to 2 in the adapter.ini file.
Delete the persistence directory and start the adapter.
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 AQ 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; 
/

The create_user.sql script:

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

Case Two: Invoke and Implement with Oracle Object Type Payload

In this case, the AQ adapter invokes and implements using Oracle Object Type Payload. The following case uses one installation of an AQ adapter that sends a request, receives the request, sends back a reply, and receives the reply. Thus, the log files will indicate four different message entries. The application used is aqapp.

Design Time Steps

This section describes the steps for invoking and implementing a procedure.

Log in as the aquser/manager.
Create the addr and cust Oracle Object Types by executing the CreateADT.sql script.
Create the necessary queues by executing the CreateADTQueue.sql script.
Create a Business Object in iStudio. In the Create Business Object dialog box, enter customer in the Business Object Name field.
Create a Procedure in iStudio. In the Create Procedure dialog box, complete the following:
1. Select customer as 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.
In the Create Data Type dialog box, 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.
Reload the project.
Using the Invoke Wizard, complete the following:
1. On the Select a Procedure dialog box:
  - Select aqapp for the Application.
  - Select AQ for the Message Type.
  - Expand the list in the Select a Procedure box and select updateCustomer.
2. On the Define Application View dialog box:
  - Click Import and select Database.
  - Log in as the system user on the Database Login dialog box.
  - On the Oracle Database Browser dialog box, expand the AQUSER list and select AQUSER.MY_QUEUE_TYPE.
  - Click Done.
3. Create the following mapping on the Define Mapping IN Arguments dialog box:
  - For aqapp view to the common view: updateCustomer:IN - ObjectCopy - updateCustomer:IN
4. Create the following mapping on the Define Mapping OUT Arguments dialog box:
  - For common view to application view: updateCustomer:OUT - ObjectCopy - updateCustomer:OUT
Repeat step 8 to create a new implemented procedure using the Implement Wizard.
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

Run-Time Steps

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

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

See Also:
"Design Time Steps"
Set the agent_log_level parameter to 2 in the adapter.ini file.
Delete the persistence directory and start the adapter.
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; 
/