3 Design Time and Runtime Concepts

This chapter describes the design time and runtime concepts for the AQ adapter. It contains the following topics:

Advanced Queuing Adapter Design Time Concepts
Designing with iStudio
Advanced Queuing Adapter Runtime Concepts
Starting the Advanced Queuing Adapter
Stopping the Advanced Queuing Adapter

3.1 Advanced Queuing Adapter Design Time Concepts

The following topics discuss 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

3.1.1 RAW Payload with XML data

You can use iStudio to import a Document Type Definition (DTD) 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.

3.1.2 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 wish to send two objects, Customer and PurchaseOrder, as part of one OracleAS Integration InterConnect message. 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:

Create iStudio datatypes 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.
Change the datatype of the Customer attribute from string to the attribute created when customer.dtd was imported. Similarly, change the datatype for the PurchaseOrder attribute to correspond to the one created using PurchaseOrder.dtd.

3.2 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.

3.2.1 Importing from XML

Select Import XML on the Publish or Subscribe Wizard. The File dialog is displayed.
Select the DTD file. A list of all nodes is displayed.
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 container on the deploy tab in iStudio.
2. Expand applicationName.
3. Expand the Routing container.
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.

3.2.2 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.

3.3 Advanced Queuing Adapter Runtime Concepts

This section describes the runtime concepts of the AQ adapter. It contains the following topics:

Advanced Queuing Sender
Advanced Queuing Receiver

3.3.1 Advanced Queuing Sender

The AQ adapter consists of the bridge and the runtime 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.

3.3.2 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.

3.4 Starting the Advanced Queuing 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. The Services window is displayed.
  
  On... Choose...
  
  Windows 2000 Start, Settings, Control Panel, Administrative Tools, Services
2. Select the OracleHomeOracleASInterConnectAdapter-Application service.
3. Start the service based on the operating system.
  
  On... Choose...
  
  Windows 2000 Right-click the service and select Start from the context menu.
  
  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.

On...	Choose...
Windows 2000	Start, Settings, Control Panel, Administrative Tools, Services

On...	Choose...
Windows 2000	Right-click the service and select Start from the context menu.

3.4.1 Log File of Advanced Queuing Adapter Instance

You can verify the start up status of the AQ adapter by viewing the oailog.txt files. The files are located in the timestamped 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.

3.5 Stopping the Advanced Queuing 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. The Services window is displayed.
  
  On... Choose...
  
  Windows 2000 Start, Settings, Control Panel, Administrative Tools, Services
2. Select the OracleHomeOracleASInterConnectAdapter-Application service.
3. Stop the service based on the operating system.
  
  On... Choose...
  
  Windows 2000 Right-click the service and select Stop from the context menu.
You can verify the stop status of the AQ adapter by viewing the oailog.txt files. These files are located in the timestamped subdirectory of the log directory of the AQ adapter.