Oracle9iAS InterConnect User's Guide Release 2 (9.0.2) Part Number A92174-01 |
|
This appendix describes how to use the data definition description language (D3L) in native format message-to-application view and application view-to-native format message translations.
This appendix contains these topics:
This section contains these topics:
D3L is an XML-based message description language that describes the structure that an application's native, non-XML format message (known also as its native view) must follow to communicate with Oracle9iAS InterConnect. Oracle Corporation provides several transport adapters (known as Oracle9iAS InterConnect Technology Adapters) that interact with the D3L message description language:
Oracle9iAS InterConnect Technology Adapters perform the following tasks:
"D3L Integration with Oracle9iAS InterConnect Technology Adapters" for detailed information on how D3L is integrated with Oracle9iAS InterConnect Technology Adapters
See Also:
Not all applications use XML as their native message payload format. Applications also use other native formats, which are best described as structured records of bytes and/or characters. For these native formats to be successfully translated into a format understood by other applications, the content of their messages must follow a predefined, structured set of rules. This structured format can then be translated into an application view, transformed into a common view, and understood by other applications.
D3L provides both a predefined, structured set of rules and translation capabilities for native format messages. Specifically, D3L provides:
The D3L descriptions must comply with a syntax defined by the D3L document type definition (DTD). D3L enables you to describe the record layout of binary, string, structured, and sequence data. Use D3L only when the number of fields in the underlying native format message is fixed and known. D3L is not suitable for:
This section provides an example of how the contents of a native format message are:
Satisfying both these requirements enables the native format message to be successfully translated. This section contains the following topics:
This example shows an application's native format message (named price
) that contains payload data for updating the price of personal computer model number 2468
to 199.99
. The native message uses the following format to describe this payload data:
message ::= <action> <model> <price>
Where... | Is... |
---|---|
|
|
|
|
|
|
The payload data must strictly follow the structure defined in a D3L file (for this example, price.xml
) for the D3L translation engine (subcomponent of the bridge) to successfully translate it into an application view. Figure B-1 shows how a D3L file (price.xml
) defines the structure that the native format message price
must follow to successfully define the three preceding elements of payload data.
All three payload data elements are defined as strings with different delimiters for separating their data.
When the D3L translation engine receives a native format message (for example, price
), it must determine the exact D3L file to use to verify the native format message contents (for example, price.xml
). This section describes the methods for configuring the correct D3L file with the native format message:
The ota.d3ls
parameter in the %ORACLE_HOME%\oai\9.0.2\adapters\
application
\adapter.ini
file enables you to define the D3L file to use with the native format message. For example:
ota.d3ls=price.xml
This setting enables price.xml
in Figure B-1 to be configured with the native format message price
. When the D3L translation engine receives the native format message from the bridge, it retrieves the correct D3L file based on this parameter setting. Multiple D3L files can also be defined, for example:
ota.d3ls=price.xml,emp.xml,booking.xml
The D3L translation engine compares the data structure in the native format message to each D3L file until it finds the correct one to use for translation, unless one of the methods described in "Message Header Attributes" is used.
The D3L file includes message header attributes that guide the D3L engine in choosing the correct D3L file for translating a native format message to an application view. The values for these message header attributes match with the same settings in the native format message.
Message header attribute values override the approach of comparing each D3L file defined with the ota.d3ls
parameter in the adapter.ini
file with a native format message.
Two message header attribute setting methods are available:
Both methods enable the D3L translation engine to use the correct D3L file for translation after receiving the native format message.
When the correct D3L file is selected (and a successful translation has taken place), the <message>
element attributes name
and object
in the D3L file define the Oracle9iAS InterConnect event name and business object, respectively.
Oracle9iAS InterConnect Technology Adapters such as the HTTP adapter make their protocol level transport properties available to the D3L translation engine, including custom properties added by a sending application (for example, an HTTP client). The D3L file <message>
element enables the user to specify two attributes, header
and value
, that match the protocol level headers in a received native format message.
For example, a third-party application uses the custom transport header D3L-Header
to communicate to the D3L translation engine which D3L file to use to translate an incoming native format message. The following steps must be performed:
D3L-Header
parameter in the transport message header to a value that matches the value
attribute setting of the <message>
element in the D3L file.
header
attribute of the <message>
element in the D3L file to D3L-Header
to match the D3L-Header
parameter name in the transport message header.
Figure B-2 provides an example using the HTTP adapter where D3L-Header
and price
are the header name and header value, respectively. Each are used to match a native format message with the correct D3L file:
The D3L translation engine retrieves the correct D3L file based on these settings.
You can set the magic
attribute of the <message>
element in the D3L file to match the first n bytes of payload data in a native format message. This feature enables you to define the D3L file to use with the native format message. When a native format message is received by the D3L translation engine, the magic
values of all D3L files are compared against the first n bytes of the native format message. The magic
values must be long enough to be unique across all registered D3Ls for a given adapter instance.
Figure B-3 provides an example where *UPDATE_PRICE
is the value that configures the native format message with the correct D3L file:
The D3L translation engine retrieves the correct D3L file based on these settings.
See Also:
|
This section describes the contents of a sample D3L file named book_reply.xml
.
1 <?xml version="1.0" encoding="US-ASCII"?> 2 <!DOCTYPE message SYSTEM "d3l.dtd"> 3 <message name="replyFlight" type="BookingReplyType" object="Booking" 4 header="D3L-Header" value="replyOptions"> 5 <unsigned4 id="u4" /> 6 <unsigned2 id="u2" /> 7 <struct id="DateTimeRecord"> 8 <field name="DateInfo"> 9 <date format="MMDDYY"> 10 <pfxstring id="datstr" length="u4" /> 11 </date> 12 </field> 13 <field name="TimeHour"><limstring delimiter="*" /></field> 14 <field name="TimeMinute"><limstring delimiter="*" /></field> 15 </struct> 16 <struct id="ItinRecord"> 17 <field name="DepartureTime"><typeref type="DateTimeRecord" /></field> 18 <field name="ArrivalTime"><typeref type="DateTimeRecord" /></field> 19 </struct> 20 <pfxarray id="ItinArray" length="u2"> 21 <typeref type="ItinRecord" /> 22 </pfxarray> 23 <struct id="BookingReplyType"> 24 <field name="AirportCodeFrom"><limstring delimiter="*" /></field> 25 <field name="AirportCodeTo"><limstring delimiter="*" /></field> 26 <field name="Itineraries"><typeref type="ItinArray" /></field> 27 </struct> 28 </message>
These lines define standard information, such as the Prolog and Document Type Declaration (DTD) that must always be these values (for example, specifying d3l.dtd
as the DTD).
These lines define the following:
name
(value replyFlight
), which must correspond to the associated Oracle9iAS InterConnect application view event name defined in iStudio. The D3L file can also be imported in iStudio when defining the message attributes of an event (the name of which must match the name
attribute of the D3L <message>
element).
type
(value BookingReplyType
) names a structure that is defined in subsequent lines of this D3L file.
object
(value Booking
), which must match the Oracle9iAS InterConnect business object defined in iStudio.
header
(value D3L-Header
), which is identified in the set of protocol level transport message headers associated with a native format message.
value
(value replyOptions
), which must match the actual value of the corresponding protocol level transport message header (defined through the header
attribute).
These lines define an unsigned, four-byte integer and unsigned, two-byte integer. These data type declarations are named u4
and u2
, respectively, so they can be referred to later.
These lines define the fields of a structure named DateTimeRecord
:
DateInfo
defines a date format of MMDDYY
and length prefixed by an unsigned four-byte integer.
TimeHour
defines a string delimited by the character *
.
TimeMinute
defines a string delimited by the character *
.
These lines define the fields of the structure named ItinRecord
:
DepartureTime
and ArrivalTime
both consist of the DataTimeRecord
structure defined in "Lines 7 through 15" .
These lines define a length-prefixed array named InitArray
, where each array element is of type ItinRecord
.
These lines define the fields of the message structure BookingReplyType
(which satisfies the BookingReplyType
type
declaration in the message document element, as shown in "Lines 3 through 4"):
AirportCodeFrom
is a string delimited by the character *
.
AirportCodeTo
is a string delimited by the character *
.
Itineraries
is a field of type ItinArray
(which is an array of ItinRecord
).
D3L supports use of the following data types and declarations in a D3L file:
D3L supports signed or unsigned integers that can be one, two, four, or eights octets in size, and in big or little endian octet ordering.
D3L supports single and double-precision, IEEE format, floating-point data. Single precision floating point numbers (known as floats) take up four bytes/octets, whereas double precision floating point numbers (known as doubles) take up eight bytes/octets.
D3L supports the following string types:
MMDDYY
, DDMMYY
, MMDDYYYY
, DDMMYYYY
, where the information is stored as a string in one of these formats with any separator character between month, date, and year (for example, 12!24=01
).
number
is handled as a double.
D3L supports structured types; that is, ordered records containing other data types (predefined or user defined). Types can be nested to arbitrary depth. This means you can use structures of sequences of structures of sequences [...] to any finite depth. Recursive, self referencing, data structures, however, are not supported in D3L.
All data fields in a message format description must be named. These names are used as Oracle9iAS InterConnect message attribute names.
D3L supports sequences (for example, arrays) of various types. These include:
The data being sequenced can be any other D3L type (predefined or user defined).
D3L supports data padding. Pads are unnamed gaps in a native format message that satisfy alignment constraints of the underlying native system. Pads are discarded in the Oracle9iAS InterConnect application view message.
The following D3L example defines a number as a left-aligned string, right padded with blanks to a field width of 10
:
<field name="Quantity"> <number> <padstring length="10" padchar=' ' padstyle="tail" /> </number>
The following native byte (character) stream satisfies this format:
9876.5____
This section provides information on how the D3L files and D3L translation engine are integrated in runtime events and message translations with the Oracle9iAS InterConnect Technology Adapter agent and bridge subcomponents. This section contains these topics:
The Oracle9iAS InterConnect Technology Adapter agent reads .ini
files (such as adapter.ini
) at runtime to access each Oracle9iAS InterConnect Technology Adapter's configuration information. The Oracle9iAS InterConnect Technology Adapter bridge initializes itself and the common transport layer with configuration information provided by the Oracle9iAS InterConnect Technology Adapter agent. At the completion of a successful initialization, the Oracle9iAS InterConnect Technology Adapter bridge knows:
See Also:
When the Oracle9iAS InterConnect Technology Adapter common transport layer detects an incoming message from an application, it receives the message in its native format. The common transport layer passes it to the Oracle9iAS InterConnect Technology Adapter bridge. The bridge:
The agent transforms the application view event into a common view event and passes it on for further routing and processing. Table B-1 describes the data flow sequence if D3L message header attributes are used.
If The... | Then... |
---|---|
Name/value pair message header attributes are used |
If the incoming native event:
the bridge assumes the matching D3L describes the incoming native event. Any conflicting header and value settings are detected and rejected by the bridge at initialization time. Oracle9iAS InterConnect Technology Adapter operations are logged by Oracle9iAS InterConnect logging and tracing APIs for debugging, performance analysis, and business intelligence functions. See Also: Figure B-2 for complete syntax examples |
Magic value message header attribute is used |
If a magic value is:
the bridge assumes the native event must be processed using the matching D3L. If multiple D3Ls specify magic values that may match the same native event, the bridge randomly picks a D3L; this can lead to undesirable bridge behavior (the resulting application view event raised may not be the correct one). See Also: Figure B-3 for complete syntax examples |
Figure B-4 shows the data flow sequence.
When a common view event is raised, the Oracle9iAS InterConnect Technology Adapter agent subscribing to the event:
The Oracle9iAS InterConnect Technology Adapter bridge queries the metadata associated with the event to determine:
adapter.ini
file, and made available to the bridge during initialization).
All Oracle9iAS InterConnect Technology Adapter operations are logged using the Oracle9iAS InterConnect logging and tracing APIs for debugging, performance analysis, and other business intelligence functions.
Figure B-5 shows the data flow sequence.
D3L is automatically installed with Oracle9iAS InterConnect. See the Oracle9i Application Server Installation Guide for information on installing Oracle9iAS InterConnect.
After installation, perform the following tasks to configure D3L:
You must define D3L in the browsers.init
file. This enables you to import D3L files as attributes and select D3L as the message type in iStudio.
To integrate D3L with iStudio:
%ORACLE_HOME%\oai\9.0.2\iStudio\browsers.init
file.
D3L;oracle.oai.agent.adapter.technology.D3LBrowser;
"Task 6: Import a D3L File in iStudio" for the locations of D3L functionality in iStudio
See Also:
33201
to 55000
:
*UPDATE_EMPLOYEE_SALARY* 33201 |55000|
Where... | Is... |
---|---|
|
|
|
|
|
|
updemp.xml
) that describes the format of the native message. For example, the following D3L file describes the contents of the native format message created in "Task 2: Create a Native Format Message".
<?xml version="1.0" encoding="US-ASCII"?> <!DOCTYPE message SYSTEM "d3l.dtd"> <message name="modify" object="Employee" type="modifyCommand" header="D3L-Header" value="employee"> <struct id="modifyCommand"> <field name="action
"><limstring delimiter="*"/></field> <field name="EmployeeID
"><limstring delimiter=" "/></field> <field name="newSalary
"><limstring delimiter="|"/></field> </struct> </message>
updemp.xml
) in the %ORACLE_HOME%\oai\9.0.2\adapters\
application
directory (for direct access at deployment time).
Configure a native format message with the correct D3L file. This enables the D3L translation engine to use the correct D3L file to verify native format message contents. For example, the D3L file created in "Task 3: Create a D3L File Describing the Native Format Message" includes settings for name/value pair message header attributes:
<?xml version="1.0" encoding="US-ASCII"?> <!DOCTYPE message SYSTEM "d3l.dtd"> <message name="modify" object="Employee" type="modifyCommand" header="D3L-Header" value="employee">
These settings can match with the transport message header D3L-Header parameter name and employee
value of a native format message:
POST /oai/servlet/transportServlet HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: acme.com:8888
Content-Length: 38
D3L-Header
:
employee
Define D3L in the following places in the adapter.ini
file. The adapter.ini
file is read by the appropriate Oracle9iAS InterConnect Technology Adapter at startup.
%ORACLE_HOME%\oai\9.0.2\adapters\
application
\adapter.ini
file.
where application
is the name of your application and the value of the application
parameter in the adapter.ini
file.
ota.type
is set to the following value:
ota.type=D3L
This defines D3L as the message type for the Oracle9iAS InterConnect Technology Adapter to handle for both incoming and outgoing messages.
ota.d3ls=updemp.xml
where updemp.xml
is an example of the D3L file created in "Task 3: Create a D3L File Describing the Native Format Message". Each event handled by the bridge must have its own D3L file. Whenever a new D3L file is imported in iStudio for use by an application, this parameter must be updated and the Oracle9iAS InterConnect Technology Adapter restarted.
iStudio enables you to import a D3L file for use with the following Oracle9iAS InterConnect features:
When a D3L file is associated with Oracle9iAS InterConnect common data types, application data types, events, or procedures, an iStudio Oracle9iAS InterConnect Technology Adapter browser plug-in verifies that the file conforms to the syntax and semantics of D3L. Table B-2 identifies the tasks and locations in iStudio where you can import a D3L file as an attribute and select D3L as a message type. Documentation references that describe how to perform these tasks are also provided.
For this D3L Functionality... | Do This... |
---|---|
Common Data Type Tasks: |
|
Application Data Types Tasks: |
|
Select File > New > Application Data Type from the iStudio menu |
|
Event Tasks: |
|
Procedure Tasks: |
|
You can associate metadata with each event in iStudio by selecting the Modify Fields buttons on the Subscribe Wizard - Define Application View dialog. The Modify Fields button appears after you select D3L as the Message Type on the preceding Subscribe Wizard - Select an Event dialog. Such metadata is used for content-based routing, for example, of events at runtime.
The following application view event metadata is used by the Oracle9iAS InterConnect Technology Adapters. The property name is prefixed by ota
to minimize namespace conflicts with user-defined metadata on application view events. The property name is considered a keyword/reserved name, and is used by both iStudio and the bridge (and must be kept consistent between these two components).
Property Name | Property Value Type | Explanation |
---|---|---|
|
The D3L filename (string). This is automatically set. Do not modify this property. |
The path name (relative or absolute) of the file that contains the D3L guidelines for this event. |
|
This value is always true (boolean) and automatically set. Do not modify this property. |
A flag indicating that this event is based on D3L. |
|
The endpoint URL (string). This is mandatory. For example:
|
The actual endpoint to which this message is sent. This setting must match the type of Oracle9iAS InterConnect Technology Adapter that subscribes to the event. |
|
See Chapter 2 of the appropriate Oracle9iAS InterConnect Technology Adapter documentation for the adapter being defined in the
|
The properties define the transport layer configuration. |
1
The SMTP adapter does not define any smtp.sender properties. The MQ Series adapter does not support multiple sending endpoints in this release. |
This section contains these topics:
This use case provides an example of a minimal Oracle9iAS InterConnect configuration and setup that uses D3L. This use case involves two applications using Oracle9iAS InterConnect Technology Adapters:
aqapp_pub
, which is based on the Advanced Queuing adapter
fileapp_sub
, which is based on the FTP adapter running in D3L mode
These applications use a business object called Employee
, which has one defined event called newEmployee
.
aqapp_pub
publishes the newEmployee
event, while fileapp_sub
subscribes to it. Table B-3 describes the attributes (message structure) of the newEmployee
event:
Attribute Name | Attribute Type |
---|---|
|
String |
|
Integer |
|
Date |
|
Double |
All these attributes are scalar (that is, there are no arrays). This message structure represents the common view of the newEmployee
event. For simplicity, the application views for the two applications have the exact same structure as the common view.
In "Creating Data Type Definitions for Application Views", a DTD file and a D3L file are created that match the common view attributes shown in Table B-3. These files are used when the application views for the two applications are defined.
You must create data type definitions for the two application views.
This section contains these topics:
The application view for the Advanced Queuing adapter must be defined through a DTD. The DTD enables the Advanced Queuing adapter to translate a received XML (text) document into a runtime application view (Java) object. The agent component of the Advanced Queuing adapter can then transform it to a common view object before routing it to any application subscribers. A DTD is registered with (imported to) the application while defining, for example, a publication in iStudio.
<!ELEMENT NewEmpRec (EmpName, EmpDept, EmpHiredate, EmpSalary)> <!ELEMENT EmpName (#PCDATA)> <!ELEMENT EmpDept (#PCDATA)> <!ELEMENT EmpHiredate (#PCDATA)> <!ELEMENT EmpSalary (#PCDATA)>
newemp.dtd
. This file can be saved to any location.
When running in D3L mode, the FTP adapter must have its application view defined by a D3L (XML) file. The D3L file enables a bidirectional translation between the internal runtime application view (Java) object representation and an external binary/native format message representation. The D3L file is registered with (imported to) the application while defining, for example, a subscription in iStudio.
Assume the external binary native format message of the newEmployee
event is as follows:
message ::= <empname> <empdept> <emphiredate> <empsalary> empname ::= char[20] // left adjusted string, 20 chars wide, right padded with spaces empdept ::= byte[2] // unsigned 2-byte integer, little endian emphiredate ::= '|' + <month> + <anysep> + <day> + <anysep> + <year> + '|' empsalary ::= '$' <number> '$'
<?xml version="1.0" encoding="US-ASCII"?> <!DOCTYPE message SYSTEM "d3l.dtd"> <message type="NewEmpRec" name="newEmployee" object="Employee">
<!-- TYPE DECLARATIONS -->
<!-- string field 20 chars wide with trailing spaces --> <padstring id="str20" padchar=" " padstyle="tail" length="20" /> <!-- unsigned 2-byte integer --> <unsigned2 id="uword" endian="little" /> <!-- date format using pattern MM-DD-YYYY enclosed by '|' --> <date id="date" format="MMDDYYYY"><limstring delimiter="|" /> </date> <!-- decimal number format enclosed by '$' --> <number id="number"><limstring delimiter="$" /></number>
<!-- MESSAGE STRUCTURE -->
<struct id="NewEmpRec">
<field name="EmpName"> <typeref type="str20" /> </field> <field name="EmpDept"> <typeref type="uword" /> </field> <field name="EmpHiredate"> <typeref type="date" /> </field> <field name="EmpSalary"> <typeref type="number" /> </field>
</struct>
</message>
newemp.xml
.
Note:
newemp.xml
is also copied to the FTP adapter application directory in "Task 4: Copy the newemp.xml D3L File to the fileapp_sub Adapter Directory".
The following example shows a native format message that can be translated by the newemp.xml
D3L file (The ?
character means nonprintable):
Pos Bytes (in hexadecimal) Characters 0000000 4a6f 686e 2044 6f65 2020 2020 2020 2020 John Doe 0000020 2020 2020 4000 7c31 322f 3134 2f32 3030 @?|12/14/200 0000040 317c 2435 3432 3230 2e37 3524 1|$54220.75$
Where... | Is... |
---|---|
|
|
|
|
|
|
|
|
In "Configuring the aqapp_pub and fileapp_sub Applications in iStudio", you complete all the steps necessary in iStudio, including defining the common view, defining the application creation, and so on.
This section describes the tasks to complete in iStudio.
This section contains these topics:
When iStudio starts, the last used workspace is automatically loaded. For this use case, define a new workspace and new Project.
d3l_tests
for the Workspace Name and click OK.
d3l_test_ftp
for the Project Name and click OK.
For... | Enter... |
---|---|
Hub database username |
|
Hub database password |
|
Hub database URL |
|
Employee
for the Business Object name and click OK.
The
Note:
Employee
Business Object name matches with the value for the object
attribute of the <message>
element in the D3L file created in "Task 2: Create a D3L File for the FTP Adapter".
Define the newEmployee
event as described in "D3L Use Case Overview". Define the (common view) attributes of the event by importing the newemp.xml
D3L file defined in "Task 2: Create a D3L File for the FTP Adapter". This D3L file defines the same data types as used by the common view. (See Table B-3.)
Employee
in the Business Object drop down list.
newEmployee
in the Event Name field.
D3L
from the list that appears.
newemp.xml
D3L file created in "Task 2: Create a D3L File for the FTP Adapter". The contents of newemp.xml
display in the Attributes fields of the Create Event dialog. If you receive an error while importing, check if the contents of the newemp.xml
file on your iStudio computer are identical to the text shown in Example B-1.
The
Note:
newEmployee
Event Name matches with the value for the name
attribute of the <message>
element in the D3L file created in "Task 2: Create a D3L File for the FTP Adapter".
The Create Event dialog looks as follows:
Now create the aqapp_pub
application, which publishes the defined event Employee
.newEmployee
.
Use the Publish Wizard to publish the newEmployee
event.
This section contains these topics:
Select the event to publish with the Publish Wizard.
The Publish Wizard - Select an Event dialog appears.
aqapp_pub
from the Application drop down list.
AQ
from the Message Type drop down list. This choice means that the aqapp_pub
application is based on the Advanced Queuing adapter.
newEmployee
event in the Select an Event tree, which is a child of the Employee
business object.
The Publish Wizard - Define Application View dialog appears.
Define the application view for the Advanced Queuing adapter-based application aqapp_pub
in this dialog. This view was defined in "Task 1: Create a DTD File for the Advanced Queuing Adapter" as an XML DTD, which is a requirement of the Advanced Queuing adapter. Import this DTD to define the application view.
XML
from the list that appears.
newemp.dtd
file, which you created in "Task 1: Create a DTD File for the Advanced Queuing Adapter".
NewEmpRec
in the Choose Root Element dialog.
The Publish Wizard - Define Application View dialog looks as follows:
The Publish Wizard - Define Mapping dialog appears.
Define the application view to common view mapping on this dialog.
The Mapping Parameters dialog appears.
newEmployee
and NewEmpRec
(clicking the '+') in the aqapp_pub
View pane.
newEmployee
and NewEmpRec
(clicking the '+') in the Common View pane.
EmpName
attribute in both panes.
CopyFields
in the Transformations list.
The Mapping Parameters dialog appears as follows:
EmpDept
, EmpHiredate
, and EmpSalary
.
When complete, the Publish Wizard - Define Mapping dialog appears as follows:
There is one line for each attribute.
The Publication for application aqapp_pub
is complete. The navigation tree pane on the left hand side of iStudio shows the following structure for the aqapp_pub
application:
Since the aqapp_pub
application publishes the newEmployee
event and is based on the Advanced Queuing adapter, you must define the (Oracle Advanced Queuing) queue from which the Advanced Queuing adapter reads the event. When an XML message, which complies with the DTD defined in "Task 1: Create a DTD File for the Advanced Queuing Adapter", is enqueued onto the outbound queue, the Advanced Queuing adapter:
The following steps describe how to choose the queue name. The queue does not have to exist physically at this point, as you create it in a later step. (See section "Task 2: Create the Application Queue AQAPP_NEWEMP".)
Applications
node.
aqapp_pub
node.
Routing
node.
Application
Queues
node.
Text description of the illustration Deploy.gif
The Edit Application Queues dialog appears.
AQAPP_NEWEMP
:
Create the fileapp_sub
application to subscribe to the defined event Employee
.newEmployee
(which is published by aqapp_pub
).
Use the Subscribe Wizard to subscribe to the newEmployee
event.
This section contains these topics:
Select the event to which to subscribe with the Subscribe Wizard.
The Subscribe Wizard - Select an Event dialog appears.
fileapp_sub
from the Application drop down list.
D3L
from the Message Type drop down list.
newEmployee
(under Employee
) in the Select an Event tree.
The Subscribe Wizard - Define Application View dialog appears.
Define the application view for the FTP adapter-based application fileapp_sub
in this dialog. This view was defined in "Task 2: Create a D3L File for the FTP Adapter" as a D3L file. This is a requirement of any Oracle9iAS InterConnect Technology Adapter operating in D3L mode. Import this D3L file to define the application view.
Employee
as the business object name in the Object Name input field.
D3L
from the list that appears.
newemp.xml
file, which you saved in "Task 2: Create a D3L File for the FTP Adapter".
The contents of newemp.xml
display in the Attributes fields:
The Publish Wizard - Define Mapping dialog appears.
Define the application view to common view mapping in this dialog.
The Mapping Parameters dialog appears.
newEmployee
(clicking the '+') in the Common View pane.
newEmployee
(clicking the '+') in the fileapp_sub
View pane.
NewEmpRec
node in both panes.
ObjectCopy
in the Transformations list and click OK.
The Subscribe Wizard - Define Mapping dialog appears as follows:
This completes the necessary setup steps in iStudio.
Now that iStudio setup is complete, you must install one instance of each of the two adapter types. This section contains these topics:
aqapp_pub
in the Application Name field of the Oracle9iAS InterConnect AQ Adapter Configuration dialog.
AQAPP_NEWEMP
application queue defined in "Task 6: Define the Application Queue for the aqapp_pub Application" is created here.
AQAPP_NEWEMP
). Select the schema name aqapp
and the password aqapp
. Leave the Consumer Name field blank, as you are creating the AQAPP_NEWEMP
queue as a single consumer queue.
When installation is complete, the new adapter instance is located in the following directory:
Platform | Directory |
---|---|
Windows |
|
UNIX |
|
To create the Advanced Queuing AQAPP_NEWEMP
application queue, you must first create the queue table, create the queue, and start the queue.
RESOURCE, CONNECT, AQ_ADMINISTRATOR_ROLE
SQL> EXECUTE dbms_aqadm.create_queue_table('AQAPP_NEWEMP', 'RAW');
SQL> EXECUTE dbms_aqadm.create_queue('AQAPP_NEWEMP', 'AQAPP_NEWEMP');
SQL> EXECUTE dbms_aqadm.start_queue('AQAPP_NEWEMP');
fileapp_sub
in the Application Name field of the Oracle9iAS InterConnect FTP Adapter Configuration dialog.
ftp://
localhost/tmp/fileapp_sub/read
ftp://
localhost/tmp/fileapp_sub/write
This places every newEmployee
message received by the fileapp_sub
application (by way of its configured subscription created in "Task 8: Enable the fileapp_sub Application to Subscribe to the newEmployee Event") in the /tmp/fileapp_sub/write
directory of the computer where the FTP adapter is installed. Ensure that you create these directories with global read and write permissions before starting the fileapp_sub
application (based on the FTP adapter), for example:
$ umask 0 $ mkdir -p /tmp/fileapp_sub/read $ mkdir -p /tmp/fileapp_sub/write
When installation is complete, the new adapter instance is located in the following directory:
Platform | Directory |
---|---|
Windows |
|
UNIX |
|
newemp.xml
D3L file defined in "Task 2: Create a D3L File for the FTP Adapter" to the platform-specific directory mentioned in the preceding Step 2.
Set the ota.d3ls
and ota.type
parameters in the adapter.ini
adapter initialization file for the FTP adapter. The adapter.ini
file is located in the platform-specific directory mentioned in the preceding Step 2.
ota.d3ls
parameter to newemp.xml
in adapter.ini
:
ota.d3ls=newemp.xml
If the ota.d3ls
parameter line already exists in adapter.ini
, replace it with this version.
ota.type
parameter to D3L
in adapter.ini
:
ota.type=D3L
Now that both the Advanced Queuing adapter instance aqapp_pub
and the FTP adapter instance fileapp_sub
have been installed, use both to run the D3L use case.
This section contains these topics:
Follow these steps to start the adapters on UNIX:
To start the aqapp_pub
(Advanced Queuing) adapter:
aqapp_pub
adapter is installed:
$ cd $ORACLE_HOME/oai/9.0.2/adapters/aqapp_pub
$ start &
To start the fileapp_sub
(FTP) adapter:
fileapp_sub
adapter is installed:
$ cd $ORACLE_HOME/oai/9.0.2/adapters/fileapp_sub
$ start &
Follow these steps to start the adapters on Windows:
To start the aqapp_pub
(Advanced Queuing) adapter:
aqapp_pub
adapter is installed:
cd %ORACLE_HOME%\oai\9.0.2\adapters\aqapp_pub
start
To start the fileapp_sub
(FTP) adapter:
fileapp_sub
adapter is installed:
cd %ORACLE_HOME%\oai\9.0.2\adapters\fileapp_sub
start
The next task generates the native event (that is, triggers the newEmployee
event). As configured in iStudio, the aqapp_pub
application publishes the newEmployee
event. It does so when it sees a new (XML) message on the AQAPP_NEWEMP
queue that conforms to the DTD defined in "Task 1: Create a DTD File for the Advanced Queuing Adapter".
To generate the native event, you must enqueue a message on the application queue (AQAPP_NEWEMP
) for the application aqapp_pub
. You do this through an anonymous PL/SQL block.
aqapp_pub
application (of the Advanced Queueing adapter) is installed, for example:
On... | Go To... |
---|---|
UNIX |
$ cd $ORACLE_HOME/oai/9.0.2/adapters/aqapp_pub |
Windows |
cd %ORACLE_HOME%\oai\9.0.2\adapters\aqapp_pub |
newemp.sql
in this example) with the contents shown in Example B-2:
DECLARE enqueue_options dbms_aq.enqueue_options_t; message_properties dbms_aq.message_properties_t; msgid RAW(16); raw_payload RAW(32767); payload varchar2(2000); BEGIN payload := '<?xml version="1.0" standalone="no"?> <NewEmpRec> <EmpName>Scott Tiger</EmpName> <EmpDept>257</EmpDept> <EmpHiredate>05/01/2001</EmpHiredate> <EmpSalary>52308.75</EmpSalary> </NewEmpRec>'; raw_payload := utl_raw.cast_to_raw(payload); dbms_aq.enqueue(queue_name => 'AQAPP_NEWEMP', enqueue_options => enqueue_options, message_properties => message_properties, payload => raw_payload, msgid => msgid); commit; END; /
Note that the payload
variable is being assigned a string value, which contains a valid XML document that conforms to the DTD newemp.dtd
defined in "Task 1: Create a DTD File for the Advanced Queuing Adapter".
Everything is now defined, created, and started. You must now trigger the newEmployee
event, which was prepared in "Task 2: Create PL/SQL Code to Trigger the Native newEmployee Event".
As mentioned earlier, the event is triggered when you place an XML message on the AQAPP_NEWEMP
queue, which is what the newemp.sql
script does.
Run the PL/SQL script to generate the event.
aqapp
where the AQAPP_NEWEMP
queue was defined. (See "Task 2: Create the Application Queue AQAPP_NEWEMP".) For example, assuming no connect string is necessary:
sqlplus aqapp/aqapp
newemp.sql
script:
SQL> START newemp.sql
The following message appears:
PL/SQL procedure successfully completed.
SQL> EXIT
After some time (maybe several minutes depending on overall system performance), a file appears in the /tmp/fileapp_sub/write
directory, which represents the sending endpoint for the FTP adapter. The file is named after the pattern:
app-name-timestamp
newEmployee
event has been published and received by the fileapp_sub
application. On UNIX, for example, perform the following commands:
$ cd /tmp/fileapp_sub/write $ ls -l total 2 -rw-rw-r-- 1 bstern svrtech 44 Dec 18 15:29 FILEAPP_SUB-1008718194783
The contents of the file can be displayed in different formats:
$ od -c FILEAPP_SUB-1008718194783 0000000 S c o t t T i g e r 0000020 001 001 | 0 5 / 0 1 / 2 0 0 0000040 1 | $ 5 2 3 0 8 . 7 5 $
or
$ od -x FILEAPP_SUB-1008718194783 0000000 5363 6f74 7420 5469 6765 7220 2020 2020 0000020 2020 2020 0101 7c30 352f 3031 2f32 3030 0000040 317c 2435 3233 3038 2e37 3524
newemp.sql
.
/write
directory appears much faster (in approximately 3-4 seconds). This is because the adapter allocated and initialized all connections and data structures after processing the first message.
This section briefly describes how to use adapters other than the FTP adapter, and how to run them in XML mode instead of D3L mode.
This section contains these topics:
Perform the following steps to use the D3L use case with a different Oracle9iAS InterConnect Technology Adapter.
smtpapp_sub
).
fileapp_sub
application name where ever it appears with the new application name.
The remaining steps are the same.
Perform the following steps to use XML as the operational mode of the Oracle9iAS InterConnect Technology Adapters.
XML
instead of D3L
in Step 3 of "Select the Event to which to Subscribe".
XML
and choose the file newemp.dtd
in Step 4 of "Define the Application View".
This section contains these topics:
This section provides several D3L sample files. These example files describe how to use the D3L language to define the content of native format messages.
Sample file msg-1.xml
represents a structure named VehicleRegistration
. Table B-4 describes the file fields and Example B-3 shows msg-1.xml
file contents.
<?xml version="1.0" encoding="US-ASCII"?> <message type="VehicleRegistration" name="Register" object="Vehicle"><date format="MMDDYYYY" id="Date_T"><padstring id="FixString10_T" length="10" padchar='' padstyle="none" /></date> <struct id="VehicleRegistration"><!-- Width x Length x Height x Weight (inch/lb) --> <field name="SizeWeight"><typeref type="ShortArray4_T" /></field> <field name="ProductCode"><unsigned2 align="2" endian="big" /></field> <field name="VIN"><unsigned8 align="2" endian="big" /></field> <field name="PreviousOwners"><typeref type="StringArray_T" /></field> <field name="Miles"><unsigned2 align="2" endian="big" /></field> <field name="DateProduced"><typeref type="Date_T" /></field></struct> <fixarray id="ShortArray4_T" length="4"><unsigned2 align="2" endian="little" id="" /></fixarray> <unsigned1 align="2" endian="little" id="Short_T" /> <pfxarray id="StringArray_T" length="Short_T"><typeref type="FixString10_T" /></pfxarray></message>
The following native format message examples show a hexadecimal and character representation of the same message, which can be parsed by the msg-1.xml
D3L file:
0000000 4500 b200 3400 8a0b 30d9 0000 0000 0072
0000020 55ff 0200 4a6f 6e65 732c 502e 2020 536d
0000040 6974 682c 522e 2020 5208 3131 2532 3225
0000060 3139 3939
0000000 E \0 262 \0 4 \0 212 013 0 331 \0 \0 \0 \0 \0 r
0000020 U 377 002 \0 J o n e s , P . S m
0000040 i t h , R . R \b 1 1 % 2 2 %
0000060 1 9 9 9
Sample file msg-2.xml
demonstrates a structure hierarchy named PersonRecord
. Table B-5 describes the file fields and Example B-4 shows msg-2.xml
file contents.
<?xml version="1.0" encoding="US-ASCII"?> <!DOCTYPE message SYSTEM "d3l.dtd"> <message type="PersonRecord"> <signed4 id="s4" /> <struct id="CityRecord"> <field name="Name"><limstring delimiter="*" /></field> <field name="State"><limstring delimiter="*" /></field> <field name="Country"><limstring delimiter="," /></field> <field name="Population"><unsigned4 /></field> </struct> <struct id="StateRecord"> <field name="Name"><limstring delimiter=" " /></field> <field name="Capital"><limstring delimiter=" " /></field> <field name="Population"><unsigned4 /></field> </struct> <struct id="PersonRecord"> <field name="Name"><limstring delimiter="," /></field> <field name="Age"><unsigned1 /></field> <field name="DOB"> <date format="MMDDYYYY"> <pfxstring id="dobstr" length="s4" /> </date> </field> <field name="Phone"><unsigned4 /></field> <field name="City"><typeref type="CityRecord" /></field> <field name="State"><typeref type="StateRecord" /></field> </struct> </message>
The following is a combined hexadecimal and character representation of a native message, which can be parsed by msg-2.xml
:
000 2c4a 6f68 6e20 446f 652c 1e00 0000 000a ,John Doe,_..... 020 3131 2f32 352f 3139 3635 0000 002c a155 11/25/1965...,.U 040 2a50 6f72 746c 616e 642a 2a4f 522a 2c55 *Portland**OR*,U 060 5341 2c00 000f 4240 204f 7265 676f 6e20 SA,...B@_Oregon_ 100 2053 616c 656d 2000 003d 0900 _Salem_..=..
Sample file msg-3.xml
defines a structure named ProductRecord
. Table B-6 describes the file fields and Example B-5 shows msg-3.xml
file contents.
Field | Description |
---|---|
|
A string delimited by a space |
|
A single-precision, floating-point number |
|
A length-prefixed array of |
<?xml version="1.0" encoding="US-ASCII"?> <!DOCTYPE message SYSTEM "d3l.dtd"> <message type="ProductRecord"> <unsigned1 id="u1" /> <unsigned2 id="u2" /> <number id="pfxnum"> <padstring length="8" padchar="" padstyle="none" /> </number> <pfxarray id="Unsigned1Tab" length="u1"> <unsigned1 /> </pfxarray> <pfxarray id="Signed4Tab" length="pfxnum"> <unsigned4 /> </pfxarray> <pfxarray id="StrTab" length="u1"> <limstring delimiter=" " /> </pfxarray> <struct id="WidgetRecord"> <field name="Name"><limstring delimiter=" " /></field> <field name="Color"><limstring delimiter=" " /></field> <field name="Weight"><float /></field> </struct> <pfxarray id="WidgetTab" length="u2"> <typeref type="WidgetRecord" /> </pfxarray> <struct id="ProductRecord"> <field name="Manufacturer"><limstring delimiter=" " /></field> <field name="Weight"><float /></field> <field name="Widgets"><typeref type="WidgetTab" /></field> </struct> </message>
Example B-6 shows the DTD to which D3L (XML) files must conform.
<?xml version="1.0" encoding="US-ASCII"?> <!-- ======================================================== --> <!ENTITY % Name "CDATA" > <!ENTITY % Number "NMTOKEN" > <!ENTITY % Comment "CDATA" > <!-- ======================================================== --> <!ENTITY % GenericAttributes " name %Name; #IMPLIED comment %Comment; #IMPLIED id ID #IMPLIED " > <!ENTITY % FieldAttributes " name %Name; #REQUIRED comment %Comment; #IMPLIED id ID #IMPLIED " > <!ENTITY % NonTypeAttributes " name %Name; #IMPLIED comment %Comment; #IMPLIED " > <!-- ======================================================== --> <!ENTITY % StructAttributes " %GenericAttributes; " > <!-- ======================================================== --> <!ENTITY % Align "%Number;" > <!ENTITY % Endian "( big | little )" > <!ENTITY % IntegerAttributes " %GenericAttributes; endian %Endian; 'big' " > <!ENTITY % IntegerTypes " signed1 | unsigned1 | signed2 | unsigned2 | signed4 | unsigned4 | signed8 | unsigned8 " > <!ENTITY % FloatAttributes " %GenericAttributes; " > <!ENTITY % FloatTypes " float | double " > <!-- ======================================================== --> <!ENTITY % PadStyle "( head | tail | none )" > <!ENTITY % PadChar "CDATA" > <!ENTITY % DelimiterChar "CDATA" > <!ENTITY % StringAttributes " %GenericAttributes; " > <!ENTITY % PaddedStringAttributes " %StringAttributes; length %Number; #REQUIRED padchar %PadChar; #REQUIRED padstyle %PadStyle; #REQUIRED " > <!ENTITY % PrefixedStringAttributes " %StringAttributes; length IDREF #REQUIRED " > <!ENTITY % DelimitedStringAttributes " %StringAttributes; delimiter %DelimiterChar; #REQUIRED " > <!ENTITY % StringTypes "padstring | pfxstring | limstring" > <!-- ======================================================== --> <!ENTITY % DateFormat "( DDMMYY | DDMMYYYY | MMDDYY | MMDDYYYY )" > <!ENTITY % DateAttributes " %GenericAttributes; format %DateFormat; #REQUIRED " > <!-- ======================================================== --> <!ENTITY % NumberAttributes " %GenericAttributes; " > <!-- ======================================================== --> <!ENTITY % ArrayAttributes " %GenericAttributes; " > <!ENTITY % FixedArrayAttributes " %ArrayAttributes; length %Number; #REQUIRED " > <!ENTITY % PrefixedArrayAttributes " %ArrayAttributes; length IDREF #REQUIRED " > <!ENTITY % DelimitedArrayAttributes " %ArrayAttributes; contchar %DelimiterChar; #REQUIRED endchar %DelimiterChar; #REQUIRED " > <!ENTITY % ImplicitArrayAttributes " %ArrayAttributes; " > <!-- ======================================================== --> <!ENTITY % TypeElements " signed1 | unsigned1 | signed2 | unsigned2 | signed4 | unsigned4 | signed8 | unsigned8 | float | double | date | number | struct | padstring | pfxstring | limstring | fixarray | pfxarray | limarray | imparray " > <!-- ======================================================== --> <!ENTITY % FieldElements "%TypeElements;" > <!ENTITY % MessageElements "%TypeElements;" > <!ENTITY % StructElements "field | pad" > <!ENTITY % ArrayElements "%TypeElements;" > <!-- ======================================================== --> <!ELEMENT message ( %MessageElements; )* > <!ATTLIST message %GenericAttributes; type IDREF #REQUIRED header CDATA #IMPLIED value CDATA #IMPLIED magic CDATA #IMPLIED endpoint CDATA #IMPLIED > <!-- ======================================================== --> <!ELEMENT struct ( %StructElements; )* > <!ATTLIST struct %StructAttributes; > <!-- ======================================================== --> <!ELEMENT field ( typeref | %FieldElements; ) > <!ATTLIST field %FieldAttributes; > <!-- ======================================================== --> <!ELEMENT signed1 EMPTY > <!ATTLIST signed1 %IntegerAttributes; align %Align; "1" > <!ELEMENT unsigned1 EMPTY > <!ATTLIST unsigned1 %IntegerAttributes; align %Align; "1" > <!ELEMENT signed2 EMPTY > <!ATTLIST signed2 %IntegerAttributes; align %Align; "2" > <!ELEMENT unsigned2 EMPTY > <!ATTLIST unsigned2 %IntegerAttributes; align %Align; "2" > <!ELEMENT signed4 EMPTY > <!ATTLIST signed4 %IntegerAttributes; align %Align; "4" > <!ELEMENT unsigned4 EMPTY > <!ATTLIST unsigned4 %IntegerAttributes; align %Align; "4" > <!ELEMENT signed8 EMPTY > <!ATTLIST signed8 %IntegerAttributes; align %Align; "8" > <!ELEMENT unsigned8 EMPTY > <!ATTLIST unsigned8 %IntegerAttributes; align %Align; "8" > <!-- ======================================================== --> <!ELEMENT float EMPTY > <!ATTLIST float %FloatAttributes; align %Align; "4" > <!ELEMENT double EMPTY > <!ATTLIST double %FloatAttributes; align %Align; "8" > <!-- ======================================================== --> <!ELEMENT padstring EMPTY > <!ATTLIST padstring %PaddedStringAttributes; > <!ELEMENT pfxstring EMPTY > <!ATTLIST pfxstring %PrefixedStringAttributes; > <!ELEMENT limstring EMPTY > <!ATTLIST limstring %DelimitedStringAttributes; > <!-- ======================================================== --> <!ELEMENT fixarray ( typeref | %ArrayElements; ) > <!ATTLIST fixarray %FixedArrayAttributes; > <!ELEMENT pfxarray ( typeref | %ArrayElements; ) > <!ATTLIST pfxarray %PrefixedArrayAttributes; > <!ELEMENT limarray ( typeref | %ArrayElements; ) > <!ATTLIST limarray %DelimitedArrayAttributes; > <!ELEMENT imparray ( typeref | %ArrayElements; ) > <!ATTLIST imparray %ImplicitArrayAttributes; > <!-- ======================================================== --> <!ELEMENT date ( typeref | %StringTypes; ) > <!ATTLIST date %DateAttributes; > <!-- ======================================================== --> <!ELEMENT number ( typeref | %StringTypes; ) > <!ATTLIST number %NumberAttributes; > <!-- ======================================================== --> <!ELEMENT typeref EMPTY > <!ATTLIST typeref %NonTypeAttributes; type IDREF #REQUIRED > <!-- ======================================================== --> <!ELEMENT pad EMPTY > <!ATTLIST pad %NonTypeAttributes; length %Number; #REQUIRED > <!-- ======================================================== -->
|
Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|