3 Design-Time and Run-Time Concepts

This chapter describes the design-time and run-time concepts of the AQ adapter. It contains the following topics:

• Chapter3, "AQ Adapter Design-Time Concepts"

• Chapter3, "Designing with iStudio"

• Chapter3, "AQ Adapter Run-Time Concepts"

• Chapter3, "Starting the AQ Adapter"

• Chapter3, "Stopping the AQ Adapter"

AQ Adapter Design-Time Concepts

The following topics describe the iStudio concepts pertinent to the AQ adapter. The AQ adapter can handle the following payload types:

• RAW Payload with XML data

• Oracle Object Payload with and without XML Data

RAW Payload with XML data

You can use iStudio to import a Document Type Definition (DTD) or XML Schema Definition(XSD) and configure an application where the corresponding message can be picked up or placed by the adapter. If the queue has been configured for RAW payload, then the message payload is plain XML.

See Also: Chapter 4, "Sample Use Cases"

Oracle Object Payload with and without XML Data

In addition to RAW payloads, the AQ adapter supports Oracle Object Types. The AQ adapter provides complete flexibility to import the Advanced Queue's Oracle Object Type payload. Thus, the attributes associated with objects within this Oracle Object Type can be of different XML types.

For example, assume that you want to send two objects, Customer and PurchaseOrder, as part of one OracleAS Integration InterConnectmessage. The corresponding DTDs are customer.dtd and purchaseOrder.dtd. When an Oracle Advanced Queue is inQueue, it contains an Oracle Object Type payload (Customer CLOB, CreationDATE, and PurchaseOrder BLOB). In this example, the application is enqueuing an Oracle Object containing Customer XML adhering to customer.dtd, a creation date, and a Purchase Order XML adhering to PurchaseOrder.dtd.

The following steps describe the tasks performed in iStudio to complete the example:

1. Create iStudio data types and import the corresponding XML DTDs.

   
   

   Note: This issue only affects users using queues with an Oracle Object Type payload.

   
   

   For example, create an application datatype called DTDs and then select Import from XML to import customer.dtd. Import PurchaseOrder.dtd in the same way. Select Reload from the File menu, then select the current project.

   Use the Import From the Database option when creating published events, subscribed events, invoked procedures, or implemented procedures.

   
   

   Note: Log in as the system user when importing DTDs on the Define Application View dialog.

   
   

   The three corresponding OracleAS Integration InterConnect attributes, Customer String, CreationDate Date, and PurchaseOrder String are created in iStudio.

2. Change the data type of the Customer attribute from string to the attribute created when customer.dtd was imported. Similarly, change the data type for the PurchaseOrder attribute to correspond to the one created using PurchaseOrder.dtd.

Designing with iStudio

The following steps describe how to create metadata using iStudio. To create metadata in iStudio, you should be familiar with the general process of creating metadata.

See Also: Oracle Application Server Integration InterConnect User's Guide

Importing from XML

1. Select Import XML on the Publish or Subscribe Wizard. The File dialog box is displayed.

2. Select the DTD file. A list of all nodes is displayed.

3. Select the root element.

   
   

   See Also: Oracle Application Server Integration InterConnect User's Guide

   
   

The following are salient points when working with AQ adapter:

• Specify the Message Type as AQ for Advanced Queue applications.

• Common view: Create by importing from XML and specifying the DTD file.

• Application view:

  • Raw Payload: Import from XML.

  • Object Payload: Import from the database by selecting the queue payload.

• Event map usage: Event maps need to be used only if two or more events published by a particular application have the same application view structure.

• Follow these steps to specify the application queues:

  1. Expand the Applications node on the deploy tab in iStudio.

  2. Expand applicationName.

  3. Expand the Routing node.

  4. Right-click Application Queues, and click Edit.

  5. Enter the Application Queue Names for the AQ adapter to subscribe and publish messages to.

  6. Click OK.

Returned In Arguments

Returned In Arguments are used only when invoking procedures. Returned In Arguments propagate IN/OUT attributes contained in both request and reply messages. Without this feature, these IN/OUT attributes would have to exist in both the common view and the application view of the implementor and mappings would need to exist to copy these attributes between the views.

You can use one of these Returned In Arguments to correlate the reply with an asynchronous request.

For example, assume a Customer object exists which looks like the following in the application view:

Customer
  Name
  ID
  Contact
    Address
      City
      State
      Zip
    Phone
      AreaCode
      PhoneNumber

This Customer object is to be sent as part of a CreateCustomer message. If ID should be both in the request and the reply, then it should be an IN/OUT parameter. Click Returned In Args in the Invoke Wizard and select ID in the Please Select In Arguments and the Please Select Out Arguments dialogs.

AQ Adapter Run-Time Concepts

This section describes the run-time concepts of the AQ adapter. It contains the following topics:

• Advanced Queuing Sender

• Advanced Queuing Receiver

Advanced Queuing Sender

The AQ adapter consists of the bridge and the run-time agent. The bridge is constantly polling the queue chosen for publishing messages in the aq_bridge_username schema as specified in the adapter.ini file. A new message in this queue indicates a new outbound OracleAS Integration InterConnect message waiting to be sent by the adapter. The adapter then picks up the message, builds the corresponding OracleAS Integration InterConnect message, stores it, transforms it to the common view, and routes it to the hub. From the hub, the message is routed to the corresponding subscriber based on configuration done using iStudio, which could be content-based or subscription-based.

The application and the AQ adapter communicate using the publishing and invoking queues residing in the aq_bridge_username parameter for outbound messages and by subscribing and implementing queues for inbound messages. Thus, if the AQ adapter is down while the application is publishing OracleAS Integration InterConnect messages, these messages are held in the queues and will be picked up in the order they were enqueued by the AQ adapter once it is up and running. If there are messages in the queues that should no longer be published, then dequeue them manually.

Advanced Queuing Receiver

On the subscribing or receiving side, the AQ adapter receives the message from the hub, transforms it from common view to application view, and passes it to the bridge, which enqueues the message to the subscribe queue configured on the Deploy tab of iStudio. The application then picks this message from this queue. If the AQ adapter is an implementor instead of a subscriber, then the correlation fields are used to correlate between the request enqueued by the adapter and the reply enqueued by the application in the reply queue.

Note: The adapter subscribing to an event should be started before any other adapter can publish that event. If you publish an event before starting the subscribing adapter, then the event would not be delivered to the subscribing adapter.

Starting the AQ Adapter

Based on the operating system, the process for starting the adapter varies.

• To start the AQ adapter on UNIX:

  1. Change to the directory containing the start script.

     cd ORACLE_HOME/integration/interconnect/adapters/Application
     
     

  2. Type start and press Enter.

• To start the AQ adapter from Services on Windows:

  1. Access the Services window from the Start menu.

  2. Select the OracleHomeOracleASInterConnectAdapter-Application service.

  3. Start the service based on the operating system.

     
     

     Note: You can also start and stop the AQ adapter using the IC Manager. Refer to Oracle Application Server Integration InterConnect User's Guide for more details.

     
     

Log File of AQ Adapter Instance

You can verify the startup status of the AQ adapter by viewing the log.xml files. The files are located in the time-stamped subdirectory of the log directory in the AQ adapter directory. Subdirectory names take the following form:

timestamp_in_milliseconds

The following is an example of the information about an AQ adapter that started successfully:

The Adapter service is starting..
Registering your application (AQAPP)..
Initializing the Bridge oracle.oai.agent.adapter.aq.XMLAQBridge..
AQ Adapter: created a reader for queue xml_q1.
Starting the Bridge oracle.oai.agent.adapter.aq.XMLAQBridge..
Service started successfully.

Stopping the AQ Adapter

Based on the operating system, the process for stopping the adapter varies.

• To stop the AQ adapter on UNIX:

  1. Change to the directory containing the stop script.

     cd ORACLE_HOME/integration/interconnect/adapters/Application
     
     

  2. Type stop and press Enter.

• To stop the AQ adapter from Services on Windows:

  1. Access the Services window from the Start menu.

  2. Select the OracleHomeOracleASInterConnectAdapter-Application service.

  3. Stop the service based on the operating system.

  You can verify the stop status of the AQ adapter by viewing the log.xml files. These files are located in the time-stamped subdirectory of the log directory of the AQ adapter.