3
Design Time and Runtime Concepts

This chapter describes the design time and runtime concepts for the Advanced Queuing adapter. Topics discussed are:

Advanced Queuing Adapter Design Time Concepts

The following topics discuss the iStudio concepts pertinent to the Advanced Queuing adapter.

Supported Features

The Advanced Queuing adapter can handle the following payload types:

RAW with XML data.
Oracle Object (can be hierarchical) where any field can contain XML data.

RAW Payload

Using iStudio, a DTD can be imported and an application can be configured where the corresponding XML message can be picked up or placed in by the OracleAS InterConnect adapter. If the queue has been configured for RAW payload, the message payload is plain XML.

See Also:

Chapter 4, "Sample Use Cases"

Oracle Object Payload with and without XML Data

In addition to XML, the Advanced Queuing adapter supports Oracle Object Types. The Advanced Queuing adapter provides complete flexibility to import the Advanced Queue's payload Oracle Object Type. Therefore, any, some, or all of the attributes can be associated within this Oracle Object Type to be of different XML types.

For example, to send a Customer and PurchaseOrder as part of one OracleAS InterConnect message, the corresponding DTDs are contained in the Customer.DTD and PurchaseOrder.DTD files. When an Oracle Advanced Queueis 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 in order to complete the example:

Create iStudio datatypes corresponding to the XML DTDs by importing them.

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. This is a workaround for a known iStudio issue.

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 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. The remainder of the process is the same as for other messages.

Creating Metadata in iStudio

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

See Also:

Oracle Application Server InterConnect User's Guide

Importing from XML:

Select Import XML on the Publish or Subscribe Wizard.
In the File dialog, select the DTD file.
From the list of all nodes, select root element.

See Also:
Oracle Application Server InterConnect User's Guide

The following are salient points when working with Advanced Queuing adapter:

Common view--Create by importing from XML and specifying the appropriate DTD file.
Application view:
- Raw Payload--Import from XML.
- Object Payload--Import from the database by select the appropriate queue payload.
Always specify the Message Type as AQ for Advanced Queue applications.
Event map usage.
Follow these steps to specify the application queues:
1. On the deploy tab in iStudio, expand the Applications container.
2. Expand applicationName.
3. Expand the Routing container.
4. Right Click on Application Queues and select Edit.
5. Enter the Application Queue Names for the Advanced Queuing adapter to subscribe and publish messages to.
6. Click OK.

Returned In Arguments

Returned In Arguments are used only when invoking procedures. The concept of Returned In Arguments is to propagate INOUT attributes contained in the request to the reply as well. Without this feature, these attributes would have to exist in both the common view and the application view of the implementor and are INOUT. All these mappings would have to be one to copy these attributes on their way out and back in, for example, when receiving the reply. Therefore, the user could use one of these returned in arguments to correlate the reply with an asynchronous request.

For example, 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 INOUT, for example, both in the request and the reply, then it should be an INOUT parameter. Click Returned In Args in the Invoke Wizard and select ID in the Please Select In Arguments and the Please Select Out Arguments.

Advanced Queuing Adapter Runtime Concepts

The following section describes the runtime concepts of the Advanced Queuing adapter.

How the Advanced Queuing Adapter Works

The following topics describe how the Advanced Queuing adapter works.

Sending Adapter

The Advanced Queuing adapter is comprised of the Advanced Queuing 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 InterConnect message waiting to be sent by the adapter. The adapter then picks up the message, builds the corresponding OracleAS InterConnect message, persists it, transforms it to the common view, and routes it to the hub. From the hub, the message is routed to the appropriate subscriber based on configuration done using iStudio which could be content based or subscription based.

The application and the Advanced Queuing adapter communicate via the publishing and invoking queues, residing in the aq_bridge_username parameter, for outbound messages and via subscribing and implementing queues for inbound messages. Therefore, the Advanced Queuing adapter is down while the application is publishing OracleAS InterConnect messages. These messages are held in the queues and will be picked up in the order they were enqueued by the Advanced Queuing adapter once it is up and running. If there are messages in the queues which should no longer be published, dequeue them manually.

Receiving Adapter

On the subscribing or receiving side, the Advanced Queuing 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 on the Deploy tab of iStudio. The application should pick this message up from this. If the Advanced Queuing adapter were an implementor instead of a subscriber, 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.

Starting the Advanced Queuing Adapter

Start the Advanced Queuing adapter using the start script in the directory named after the Advanced Queuing adapter. On Windows or Windows 2000, start it from the Service window available from the Start menu.

Access the Services window from the Start menu:

Platform Action

Windows 2000

Start > Settings > Control Panel > Administrative Tools > Services

The Services window displays.
Select the OracleHomeOracleASInterConnectAdapter-Application service.
Start the service based on your operating system:

Platform Action

Windows 2000

Right click the service and choose Start from the menu that displays.

See Also:
"Configuring the Advanced Queuing Adapter" for the location of the start script

Platform	Action
Windows 2000	Start > Settings > Control Panel > Administrative Tools > Services

Platform	Action
Windows 2000	Right click the service and choose Start from the menu that displays.

Sample Log File of Successfully Started Advanced Queuing Adapter

Startup status can be verified by viewing the oailog.txt files in the appropriate timestamped subdirectory of the log directory of the Advanced Queuing adapter directory. Subdirectory names take the following form:

timestamp_in_milliseconds

The following file displays information about an Advanced Queuing adapter that started successfully:

D:\oracle\ora904\oai\9.0.4\adapters\aqapp>D:\oracle\ora904\oai\9.0.b·in\Java 
Service.exe -debug "Oracle OAI Adapter 9.0.4 - aqapp"
D:\oracle\ora9041\oai\9.0.4\adapters\aqapp adapter.ini
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 Advanced Queuing Adapter

Stop the Advanced Queuing adapter using the stop script in the directory named after the Advanced Queuing adapter. On Windows 2000, stop the adapter from the Services window available from the Start menu.

Access the Services window from the Start menu:

Platform Action

Windows 2000

Start > Settings > Control Panel > Administrative Tools > Services

The Services window displays.
Select the OracleHomeOracleASInterConnectAdapter-Application service.
Start the service based on your operating system:

Platform Action

Windows 2000

Right click the service and choose Stop from the menu that displays.

Stop status can be verified by viewing the oailog.txt files in the appropriate timestamped subdirectory of the log directory of the adapter directory.

See Also:
"Configuring the Advanced Queuing Adapter" for the location of the start script

3 Design Time and Runtime Concepts