3
Design Time and Runtime Concepts

This chapter describes the design time and runtime concepts for the Database adapter. Topics include:

• Database Adapter Design Time Concepts

• Database Adapter Runtime Concepts

• Starting the Database Adapter

• Stopping the Database Adapter

Database Adapter Design Time Concepts

The following topics discuss the iStudio concepts pertinent to the Database adapter.

See Also: Oracle Application Server InterConnect User's Guide

Importing Database Tables

For a database application, the application and common views resemble the underlying database schema. For this reason, iStudio allows the creation of a view by importing tables directly from the database. The following tables can be imported:

• Relational

• Object

• Oracle Object

• Advanced Queuing payload.

The following examples illustrate some basic features for the database tables.

Example: Relational Table

The following example illustrates basic features of a relational table.

Table 3-1 Customer

Parameter	Value
NAME	VARCHAR2(200)
ID	NUMBER
ADDRESSES	LONG

When imported into iStudio, this table results in the following:

Table 3-2 Customers

Parameter	Value
NAME	STRING
ID	INTEGER
ADDRESSES	STRING

When importing from database, iStudio allows any number of columns to be selected.

Example: Object Table

The following example illustrates basic features of the object table.

Table 3-3 Customer

Parameter	Value
NAME	VARCHAR2(200)
ID	NUMBER
ADDRESSES	ADDRESS_ARRAY

Where ADDRESS_ARRAY is VARRAY of ADDRESS and ADDRESS is an OBJECT TYPE containing the following attributes:

Parameter	Value
CITY	VARCHAR2(200)
STATE	VARCHAR2(200)
ZIP	NUMBER

When imported into iStudio, this table results in the following:

Table 3-4 Customer

Parameter	Value
NAME	STRING
ID	INTEGER
ADDRESSES	ARRAY (marked as an ARRAY)

Where ADDRESS_ARRAY contains the following attributes:

Parameter	Value
CITY	STRING
STATE	STRING
ZIP	NUMBER

In this example, the hierarchical structure is kept intact when dealing with Oracle Object Types.

Example: FOREIGN Key

In an example similar to the previous one, the structure or relationship is represented using a FOREIGN key. In this case, the end user is responsible for importing each of the different tables and setting up the relationship in iStudio by editing the types of attributes. The following example illustrates this point.

Relational Tables related by a FOREIGN Key

Table 3-5 Customer

Parameter	Value
NAME	VARCHAR2(200)
ID	NUMBER
ADDRESS	NUMBER (Foreign key)

Table 3-6 Address

Parameter	Value
ID	NUMBER (Primary key)
CITY	VARCHAR2(100)
STATE	VARCHAR2(50)
ZIP	NUMBER

Using iStudio, complete the following to import this structure:

1. Import the Address table.

   This results in:

   ID	NUMBER
   CITY	STRING
   STATE	STRING
   ZIP	NUMBER

2. Import the Customer table. This results in the following:

   NAME	STRING
   ID	NUMBER
   ADDRESS	NUMBER

3. Change the type of Address attribute to Address.

Importing an Oracle Object or Advanced Queuing Payload

Importing an Oracle Object or an Advanced Queuing payload in iStudio is similar to importing database tables. Importing from an Advanced Queuing payload is necessary when working with Advanced Queuing applications.

Note: When importing an Advanced Queuing payload, it may be necessary to log in as the system user.

Returned In Arguments

Returned In arguments applies when invoking procedures. The Returned IN Args page does only displays in the Invoke wizard. Returned In arguments are used to propagate INOUT attributes contained in the request to the reply. Without this feature, it would have to be ensured that these attributes exist in both the common view and application view of the implementor and are INOUT attributes. It would also be necessary to complete all the mappings to copy these attributes on their way out and back in, for example, when receiving the reply. For instance, one of these returned In arguments can be used to correlate the reply with an asynchronous request.

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

Customer
  Name
  ID
  Contact
    Address
      City
      State
      Zip
    Phone
      AreaCode
      PhoneNumber

If this is to be sent as part of a CreateCustomer message and ID is to be INOUT in both the request and the reply, then it should be an INOUT parameter. To do this, complete the following steps:

1. Click Returned In Args on the Invoke wizard.

2. Select ID on the Please Select In Arguments dialog and the Please Select Out Arguments dialog.

Exporting PL/SQL Code

To export PL/SQL code, use the File/Export menu item in iStudio.

The SQL Code dialog appears at the end of Subscribe, Invoke, Implement wizards. In the drop down list the options are generated data types and <EventType>_<EventName>_<MetadataOwner>_<Version>.

Typically, there is no need to modify the generated data types SQL code. Insert the necessary code as indicated by -- declare here or -- fill code here in the latter dialog.

Database Adapter Runtime Concepts

The following section describes the runtime concepts pertinent to the Database Adapter.

How the Database Adapter Works

The following topics describe how the Database adapter works.

Sending Adapter

The Database adapter is comprised of the database bridge and the runtime agent. The bridge is constantly polling the MESSAGEOBJECTTABLE table in the oai schema, specified by the db_bridge_schema1_username parameter. A new row in this table indicates a new outbound OracleAS InterConnect message waiting to be sent by this adapter. The adapter then picks up the message from the interface tables residing in the oai schema, 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 gets routed to the appropriate subscriber based on configuration completed in iStudio which can be content-based or subscription-based.

The application and the database adapter communicate through the interface tables residing in the oai schema for outbound messages and through iStudio PL/SQL generated procedures for inbound messages. Therefore, if the adapter is down while the application is publishing OracleAS InterConnect messages using the iStudio generated PL/SQL procedures, the messages are held in the interface tables and will be picked up in a FIFO method by the database adapter once it is up and running. If there are messages in the interface tables that no longer need to be published, the DELETE FROM MESSAGEOBJECTTABLE using SQLPlus can be run in the oai schema.

Receiving Adapter

On the subscribing/receiving side, the Database adapter receives the message from the hub, transforms it from common view to application view, and passes it to the bridge which calls the appropriate PL/SQL procedures to inform the application about the newly arrived message. If this adapter were an implementor, the OUT arguments from the PL/SQL procedure invocation are put together and the REPLY in the form of another OracleAS InterConnect message is sent back to the INVOKER or REQUESTER.

The receiving adapter is responsible for creating any necessary cross reference entries. In a publish-subscribe scenario, the subscribing adapter creates the cross reference entry using the returned arguments, for example OUT, from the subscribe side procedure.

See Also: Oracle Application Server InterConnect User's Guide

Starting the Database Adapter

On UNIX, start the Database adapter using the start script located in the following directory:

ORACLE_HOME/oai/9.0.4/adapters/Application

Type start, then press Enter.

On Windows, start the Database adapter from the Services window available from the Start menu.

1. Access the Services window from the Start menu:

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

   The Services window appears.

2. Select the OracleHomeOracleASInterConnectAdapter-Application service.

3. Start the service based on the operating system:

   On...	Choose...
   Windows NT	Choose Start.
   Windows 2000	Right-click the service and choose Start from the menu that appears.

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

Sample Log File

The following is a sample log file of a Database adapter that was successfully started.

D:\oracle\ora904\oai\9.0.4\adapters+bapp>D:\oracle\ora904\oai\9.0.4·in\JavaServi
ce.exe -debug "Oracle OAI Adapter 9.0.4 -
dbapp" D:\oracle\ora9041\oai\9.0.4\adapters+bapp adapter.ini 
The Adapter service is starting.. 
Registering your application (DBAPP).. 
Initializing the Bridge oracle.oai.agent.adapter.database.DBBridge
Starting the Bridge oracle.oai.agent.adapter.database.DBBridge
Service started successfully. 
db_bridge_writer_1 has been started.
db_bridge_reader_1 has been started.
db_bridge_writer_1 has connected to the database successfully.
db_bridge_reader_1 has connected to the database successfully.

Stopping the Database Adapter

On UNIX, stop the Database adapter using the stop script located in the following directory.

ORACLE_HOME/oai/9.0.4/adapters/Application

Type stop, then press Enter.

On Windows, stop the Database adapter from the Services window available from the Start menu.

1. Access the Services window from the Start menu:

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

   The Services window appears.

2. Select the OracleHomeOracleASInterConnectAdapter-Application service.

3. Stop the service based on the operating system:

   On...	Choose...
   Windows NT	Choose Stop.
   Windows 2000	Right-click the service and choose Stop from the menu that appears.

   You can verify the stop status by viewing the oailog.txt files in the appropriate timestamped subdirectory of the log directory within the adapter directory.