Oracle Application Server InterConnect User's Guide 10g (9.0.4) Part Number B10404-01 |
|
This appendix describes how to use the data definition description language (D3L) in its 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 Oracle Application Server InterConnect. Oracle Corporation provides several transport adapters (known as OracleAS InterConnect Adapters) that interact with the D3L message description language:
OracleAS InterConnect Adapters perform the following tasks:
Native format messages already in XML format are not translated by OracleAS InterConnect Adapters if the
"D3L Integration with OracleAS InterConnect Adapters" for detailed information on how D3L is integrated with OracleAS InterConnect Adapters
Note:
ota.type
parameter is set to XML
in the adapter.ini
file.
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.4\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.
OracleAS InterConnect 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.
Text description of the illustration appx_d3l3.gif
The D3L engine supports a rudimentary pattern matching capability in the value
attribute of the D3L message
element.
A D3L author can create a D3L definition, such as:
<message type="CrtCust" header="filename" value="cust_create%" ...
This example is relevant for the FTP adapter, which provides a header property called filename
that holds the name of a received file.
The above D3L will be selected to parse incoming files which filename match the name pattern in the value
attribute, such as,
cust_create01 <-- match! cust_create02 <-- match! po_int_ext01 cust_create03 <-- match! po_int_ext02
The "fuzzy" character in the pattern ("%
") can only appear at two places in the attribute string-value, as either the first or the last character, or both the first and last characters.
For example, the following patterns are acceptable:
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.
The D3L attribute startsat
of the message
element enables the D3L author to specify the byte location that magic matching should start.
Having this attribute allows the D3L definition:
<?xml version="1.0" encoding="US-ASCII"?> <!DOCTYPE message SYSTEM "d3l.dtd"> <message name="newBook" type="BookType" object="BookObj" magic="ISBN#" startsat="12">
This D3L definition will trigger if a native message contains the byte
character sequence ISBN#
in byte positions 12 to 16, counting from 0.
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 Oracle Application Server 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 Oracle Application Server 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.
<field name="quantity"> <unsigned4 endian="big" align="6"/> </field>
The field "quantity"
defines a four byte unsigned binary integer, using big (default) endian, and at an alignment of 6 bytes. For example, D3L will ensure that the reading or writing of this integer will start at a position in the buffer, so that <
position
> modulus <
alignment
> = 0
.
Data example
Byte
addresses
(hex
):
00 01 02 03 04 05 06 07 08 09 0A 0B
Byte
(hex
):
00 00 00 00 00 00 80 FF FF FF 00 00
Parsed value
(dec
):
quantity = 128x2563 + 255x2562 + 255x2561 + 255x2560 = 2164260863
<field name="weight"> <unsigned2 align="3"/> </field> <field name="length"> <unsigned2 align="3"/> </field>
The fields "weight"
and "length
" define two bytes unsigned binary integers, using big endian, and at an alignment of 3 bytes.
Data example
Byte
addresses
(hex
):
.. 07 08 09 0A 0B 0C 0D 0E ..
Byte
(hex
):
.. 00 00 EE 88 00 22 F0 00 ..
Parsed value
(dec
):
weight = 238x2561 + 136x2560 = 61064 length = 34x2561 + 240x2560 = 8944
<field name="temperature"> <signed2 endian="little" /> </field> <field name="pressure"> <unsigned4 endian="big" /> </field> <field name="wind"> <unsigned2 endian="little" align="4" /> </field>
The field "temperature"
defines a two byte signed binary integer, using little endian, and no alignment.
The field "pressure
" defines a four byte unsigned binary integer, using big endian, and no alignment.
The field wind
defines a two byte unsigned binary integer, using little endian, and a 4 byte alignment.
Data example
Byte
addresses
(hex
):
.. 60 61 62 63 64 65 66 67 68 69 ..
Byte
(hex
):
.. EF FE 00 00 04 0A 00 00 3C 00 .. ^ ^ ^ little end big end alignment
Parsed value
(dec
):
temperature = 256x256 - (239x2560 + 254x2561) = -273 pressure = 4x2561 + 10x2560 = 1034 wind = 60x2560 + 0x2561 = 60
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.
<field name="distance"> <double align="6"/> </field> <field name="age"> <float /> </field>
The field "distance"
defines an eight byte double-float (floating-point value according to the IEEE 754 floating-point double precision
bit layout), at an alignment of 6 bytes.
The field "age"
defines a four byte single-float (floating-point value according to the IEEE 754 floating-point single precision
bit layout).
Note:: The IEEE 754 floating-point format is parsed and produced by the following Java class methods:
|
Data example
Byte
addresses
(hex
):
..77 78 03 04 05 06 07 08 09 0A 0B xx xx ..
Byte
(hex
):
00 00 D2 47 D3 CE 16 2A B1 A1 5E 5D 6B 0B .. ^ double ^ float
Parsed value
(dec
):
distance = 1 x 1038 age = 1 x 1018
D3L supports the following string types:
limarry
structure.
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.
padstring
<field name="CURRENCY_CODE"> <padstring length="4" padchar=" " padstyle="tail"/> </field> <field name="COUNTRY_CODE"> <padstring length="2" padchar="" padstyle="none"/> </field> <field name="TO_USD_RATE"> <padstring length="12" padchar="0" padstyle="head"/> </field>
The field "CURRENCY_CODE
" defines a fixed length string of 4 characters. Any blank (" ") characters (pads) towards the end (padstyle="tail"
) of the string are not considered part of the data value.
The field "COUNTRY_CODE
" defines a fixed length string of 2 characters. Since padstyle is "none
", all characters in this field are prt of the data value.
The field "TO_USD_RATE
" defines a fixed length string of 12 characters. Any zero's ("0
" pads) at the beginning (padstyle="head"
) of the string are not considered part of the data value.
Data example
Native byte
(character
) stream:
GBP UK000012550.00
Parsed value
s:
CURRENCY_CODE = 'GBP' COUNTRY_CODE = 'UK' TO_USD_RATE = '12550.00'
limstring
<field name="State"> <limstring delimiter="." /> </field> <field name="Region"> <limstring delimiter="." /> </field> <field name="City"> <limstring delimiter="|" /> </field> <field name="Landmark"> <limstring delimiter="|" /> </field> <field name="Street"> <limstring delimiter="+" /> </field>
The five fields "State
", "Region
", "City
", "Landmark
" and "Street
" are delimited strings each respectively enclosed by ".", ".", "|", "|" and "+".
Data example
Native byte
(character
) stream:
.FL..Florida Keys.|Key West||Ernest Hemingway Museum|+Whitehead St.+
Parsed value
s:
State = 'FL' Region = 'Florida Keys' City = 'Key West' Landmark = 'Ernest Hemingway Museum' Street = 'Whitehead St.'
pfxstring
<unsigned1 id="ubyte1" /> <unsigned2 id="ubyte2" endian="little" /> <struct> <field name="user"> <pfxstring length="ubyte1" /> </field> <field name="encr_user"> <pfxstring length="ubyte2" /> </field>
The field "user
" defines a string the length of which is defined by a one-byte binary integer preceeding the string contents.
The field "encr_user
" defines a string the length of which is defined by a two-byte binary integer preceeding the string contents.
Data example
Byte
addresses
(hex
):
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11 12
Characters
:
03 j o e 0D 00 D U Z a c . 1 H K V m I Y
Parsed values
:
user = 'joe'
encr_user = 'DUZac.1HKVmIY'
termstring
<field name="product"> <termstring endchar=","/ > </field> <field name="ordered"> <termstring endchar=","/ > </field> <field name="inventory"> <termstring endchar=","/ > </field> <field name="backlog"> <termstring endchar=","/ > </field> <field name="listprice"> <termstring endchar="\n"/> </field>
The first four fields will each be populated with input characters until the terminating/ending character (endchar
) is encountered (",") whereas the last field be ended with a linefeed.
Data example
Native byte
(character
) stream:
1020,16,18,,1580.00<LF
>
Parsed values
:
product = '1020' ordered = '16' inventory = '18' backlog = '' listprice = '1580.00'
simplestring
<limarray id="CSV_Type" contchar="," endchar="\n"> <simplestring /> </limarray> <struct> <field name="CSV"> <typeref type="CSV_Type" /> </field>
The field "CSV
" references a type declaration "CSV_Type
" which is a delimited array where array members are separated by commas (the continuation character contchar=",") and ended by the ending character linefeed (endchar="\n")
Data example
Native byte
(character
) stream:
5,18,2.5,255,78.75,9
Parsed values
:
CSV[]
=
{
'5',
'18',
'2.5',
'255',
'78.75',
'9'
}
date
<field name="StartDate"> <date format="MMDDYY"> <termstring endchar="\n"/> </date> </field> <field name="EndDate"> <date format="DDMMYY"> <termstring endchar="\n"/> </date> </field> <field name="Milestone"> <date format="MMDDYYYY"> <termstring endchar="\n"/> </date> </field> <field name="DueDate"> <date format="DDMMYYYY"> <termstring endchar="\n"/> </date> </field>
The four fields contain dates, representing the currently available 4 different date format.
Data example
Byte stream
(characters
):
11/16/02<LF
> 24/11/02<LF
> 11/20-2002<LF
> 23*11*2002<LF
>
Parsed values
:
StartDate = Sat Nov 16 00:00:00 PST 2002 EndDate = Sun Nov 24 00:00:00 PST 2002 Milestone = Wed Nov 20 00:00:00 PST 2002 DueDate = Sat Nov 23 00:00:00 PST 2002
number
<unsigned1 id="u1" /> <pfxstring id="HueType" length="u1" /> <struct id="ColorDefinition"> <field name="Red"> <number> <padstring length="4" padstyle="head" padchar="0"/> </number> </field> <field name="Green"> <number> <pfxstring length="u1" /> </number> </field> <field name="Blue"> <number> <limstring delimiter="."/> </number> </field> <field name="Brightness"> <number> <termstring endchar="|"/> </number> </field> <field name="Hue"> <number> <typeref type="HueType"/> </number> </field> </struct>
The declared type "u1
" is an unsigned one-byte integer (0-255). The second type declaration "HueType
" is a length prefixed string, where the string length will be defined in a one-byte binary integer preceding the string contents.
The field "Red
" is a number defined as a fixed length string of 4 characters, which can be padded with '0
's at the beginning.
The field "Green
" is a number defined as a length prefixed string, where the string length will be defined in a one-byte binary integer preceeding the string contents.
The field "Blue
" is a number defined as a "." delimited string, the string beginning and end is demarcated by ".".
The field "Brightness
" is a number defined as a string which is read from the current point until the ending character ("|") is encountered.
The field "Hue
" is a number defined as a string of type "HueType
" (defined above).
Data example
Byte addresses
(hex
) and Characters (hex values shown in italics):
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 0 1 2 8 03 1 2 8 . 2 5 5 . 0 . 7 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 5 3 3 3 3 | 08 0 . 6 6 6 6 6 6
Parsed values
:
Red = 128.0 Green = 128.0 Blue = 255.0 Brightness= 0.753333 Hue = 0.666666
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 Oracle Application Server InterConnect message attribute names. All names within the same structure must be mutually unique.
Within a D3L file the first allowable element is <message>
. The message
element must refer to a <struct>
(via the IDREF
type
attribute) which then becomes the top level data structure of the message.
<message type="ColorDefinition" name="myEV" object="myBO"> <unsigned1 id="u1" /> <pfxstring id="HueType" length="u1" /> <struct id="ColorDefinition"> <field name="Red"> ... <field name="Green"> ...
Note:
The top level structure can be placed anywhere in the D3L file (within the scope of the |
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).
limarray
<field name="members"> <limarray contchar=";" endchar="."> <limstring delimiter="." /> </limarray> </field>
The field "members
" will become an array of data elements separated by semicolons (contchar=";"). The end of the array will be marked by a period (endchar="."). Each data element in the array will be a string delimited by a set of periods (delimiter=".").
Data example
Native byte
(character) stream:
.John.;.Steve.;.Paul.;.Todd..
Parsed values
:
members[] = { 'John', 'Steve', 'Paul', 'Todd' }
pfxarray
<unsigned2 id="u2" endian="little" align="4" /> <struct> <field name="measurements"> <pfxarray length="u2" > <signed1 /> </pfxarray> </field>
The field "measurements
" will become an array of signed one-byte binary integers (signed1). The number of elements in the array will be determined by the unsigned two-byte binary integer at the beginning of the array.
Data example
Byte addresses
(hex
):
.. 08 09 0A 0B 0C 0D 0E 0F 10 ..
Bytes
(hex
):
.. 06 00 FF A2 6C 24 0E 77 ..
Values
(dec
):
measurements[] = { -1, -94, 108, 36, 14, 119 }
fixarray
<field name="digits"> <fixarray length="10"> <number> <termstring endchar="-"> </number </fixarray>
The field "digits
" will become an array of numbers (doubles). Each number element in the native byte format is represented as a string which is terminated by a dash (endchar="-
"). The number of elements in the array will/must always be 10 (length="10
").
Data example
Native byte
(character
) stream:
1-2-3-4-5-6-7-8-9-0-
Parsed values
:
digits[] = { 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 0.0 }
imparray
<message name="addOrders" object="Order" type="OrdersType"> <number id="Number"> <termstring endchar="," /> </number> <number id="Price"> <termstring endchar=";" /> </number> <number id="Total"> <termstring endchar="\n"/> </number> <struct id="OrderLineType"> <field name="LineNo"> <typeref type="Number" /> </field> <field name="ProductNo"> <typeref type="Number" /> </field> <field name="Quantity"> <typeref type="Number" /> </field> <field name="LinePrice"> <typeref type="Price " /> </field> </struct> <struct id="OrderType"> <field name="OrderTotal"> <typeref type="Total" /> </field> <field name="OrderLines"> <limarray contchar="\n" endchar="\n\n"> <struct> <field name="OrderLine"> <typeref type="OrderLineType" /> </field> </struct> </limarray> </field> </struct> <number id="ID"> <termstring endchar="\n" /> </number> <imparray id="OrdersArrayType"> <struct> <field name="CustomerID"> <typeref type="ID" /> </field> <field name="CustomerName"> <termstring endchar="\n" /> </field> <field name="Order"> <typeref type="OrderType" /> </field> </struct> </imparray> <struct id="OrdersType"> <field name="OrdersArray"> <typeref type="OrdersArrayType" /> </field> </struct> </message>
The "OrdersType
" structure consists of a single field "OrdersArray
" which is an implicit array of three fields--a "CustomerID
", "CustomerName
" and "Order
" (of type "OrderType
"). Since "OrdersArrayType
" is an implicit array, it will consume all remaining bytes in the native byte input stream, i.e. the size of the array is first known when the input byte stream has been exhausted.
The field "OrderLines
" is a (nested) array, where each array element is of type "OrderLineType
". The "OrderLineType
" is a structure of four fields--"LineNo
", "ProductNo
", "Quantity
" and "LinePrice
".
This abstract structure of the input stream would have to follow the below structure to be parseable:
CustomerID CustomerName Order: OrderTotal OrderLines: LineNo, ProductNo, Quantity, LinePrice LineNo, ProductNo, Quantity, LinePrice ...
Data example
Native byte
(character
) stream:
1234 Boeing 1000 1,555,10,250.00; 2,666,10,750.00; 5678 Lockheed Martin 424 1,555,5,125.00; 2,777,1,100.00; 3,888,2,199.00;
Parsed values
:
{OrdersArray= [ { CustomerName=Boeing, CustomerID=1234.0, Order= { OrderTotal=1000.0, OrderLines = [ {OrderLine={LinePrice=250.0, ProductNo=555.0, Quantity=10.0, LineNo=1.0}}, {OrderLine={LinePrice=750.0, ProductNo=666.0, Quantity=10.0, LineNo=2.0}} ] } }, { CustomerName=Lockheed Martin, CustomerID=5678.0, Order= { OrderTotal=424.0, OrderLines = [ { OrderLine={LinePrice=125.0, ProductNo=555.0, Quantity=5.0, LineNo=1.0}}, { OrderLine={LinePrice=100.0, ProductNo=777.0, Quantity=1.0, LineNo=2.0}}, { OrderLine={LinePrice=199.0, ProductNo=888.0, Quantity=2.0, LineNo=3.0}} ] } } ] }
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 Oracle Application Server 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____
Pads can also be explicitly defined between fields in a structure by using the <pad>
element.
The following D3L example shows to fields, which are separated by a pad of size 5.
<struct id="PROD"> <field name=PRODID"> <termstring endchar=";" /> </field> <pad length="10" /> <field name=PRODDESC"> <termstring endchar=";" /> </field> </struct>
The following native byte (character) stream would satisfy this format:
48682HW;~~~~~~~~~~WASHER AND DRYER; [...]
A comma-separated values (CSV) file consists of multiple lines. Each line contains values separated by commas that end when a new line is required:
a,b,c,d 1,2,3
Two string types, termstring
and simplestring
, have been added to make it easier to parse CSV files.
termstring
String type termstring
is a variation of limstring
, but requires only a terminating delimiter and, not a beginning delimiter. For example:
<termstring endchar="," />
This parses any string contents until a comma is encountered.
simplestring
String type simplestring
is a special data type only used when the nearest parent structure defines a valid set of delimiters, which for the current data definition description language (D3L) library is limited to limarray
. For example:
<limarray contchar="," endchar="\n">
<simplestring />
</limarray>
These new string types provide two ways for parsing CSV files. The examples provided in the following sections use imparray
so that input can be any number of elements, lines, or both.
With this method, all CSVs on each line are assigned to named fields (fixed number of fields per line). Example B-17 provides an example.
<message name="createPhone" object="Phone" type="phoneRecord"><imparray id="lines"><struct><field name="rectype"> <termstring endchar=","/ > </field> <field name="quantity"><termstring endchar=","/ > </field> <field name="endHour"> <termstring endchar=","/ > </field> <field name="endMin"> <termstring endchar=","/ > </field> <field name="cost"> <termstring endchar="\n"/> </field></struct></imparray> <struct id="phoneRecord"><field name="csv"> <typeref type="lines" /> </field></struct></message>
The native format message payload for Example B-17 is as follows:
4,,9,22,2324.29 ,,,,, 55,2342,11,46,728372339.57
With this method, all CSVs on each line are read into an array (variable number of fields per line). Example B-18 provides an example.
<message name="createPhone" object="Phone" type="phoneRecord"><limarray id="linearr" contchar="#44" endchar="\n"><simplestring /></limarray> <imparray id="myArray"><struct><field name="line"> <typeref type="linearr" /> </field></struct></imparray> <struct id="phoneRecord"><field name="csv"> <typeref type="myArray" /> </field></struct></message>
The native format message payload for Example B-18 is as follows:
4,,9,22,2324.29 55,2342,11,46,728372339.57 55,2342,11,46,728372339.57,4,,9,22,2324.29 1,2,3,4,5,6,7,8,9,0,1,2,3,4,5,6,7,8,9,0
The delimiters for limstring
, termstring
, and limarray
are enhanced to allow multiple characters, as well as additional encoding styles. The associated ASCII table codes are shown in parentheses:
"\
"-- This works for "\r
" (13)
, "\n
" (10)
, "\t
" (9)
, and "\f
" (12)
.
where:
#13
".
\eof
" which maps to a virtual end-of-file character--This delimiter can only be used once. No other fields can follow once it has been used.
Example B-19 provides several examples of delimiter encoding styles.
<termstring endchar="#x2C"/> <termstring endchar="\n"/> <limarray id="linearr" contchar="," endchar="\r\n"> <simplestring/> </limarray> <termstring id="FileContents" endchar="\eof"/>
The "\r\n
" on line 3 of Example B-19 represents a DOS style line break.
This section provides information on how the D3L files and D3L translation engine are integrated in runtime events and message translations with the OracleAS InterConnect Adapter agent and bridge subcomponents. This section contains these topics:
The OracleAS InterConnect Adapter agent reads .ini
files (such as adapter.ini
) at runtime to access each OracleAS InterConnect Adapter's configuration information. The OracleAS InterConnect Adapter bridge initializes itself and the common transport layer with configuration information provided by the OracleAS InterConnect Adapter agent. At the completion of a successful initialization, the OracleAS InterConnect Adapter bridge knows:
See Also:
When the OracleAS InterConnect 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 OracleAS InterConnect 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. OracleAS InterConnect Adapter operations are logged by Oracle Application Server 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.
Text description of the illustration asiug002.gif
When a common view event is raised, the OracleAS InterConnect Adapter agent subscribing to the event:
The OracleAS InterConnect Adapter bridge queries the metadata associated with the event to determine:
adapter.ini
file, and made available to the bridge during initialization).
All OracleAS InterConnect Adapter operations are logged using the Oracle Application Server InterConnect logging and tracing APIs for debugging, performance analysis, and other business intelligence functions.
Figure B-5 shows the data flow sequence.
Text description of the illustration asiug001.gif
D3L is automatically installed with Oracle Application Server InterConnect. See Oracle Application Server InterConnect Installation Guide for information on installing Oracle Application Server InterConnect.
See Also:
Your OracleAS InterConnect Adapter documentation for instructions on installing and configuring the appropriate adapter to use with D3L |
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.4\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.4\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 OracleAS InterConnect Adapter at startup.
ORACLE_HOME
\oai\9.0.4\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 OracleAS InterConnect 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 OracleAS InterConnect Adapter restarted.
iStudio enables you to import a D3L file for use with the following Oracle Application Server InterConnect features:
When a D3L file is associated with Oracle Application Server InterConnect common data types, application data types, events, or procedures, an iStudio OracleAS InterConnect 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 OracleAS InterConnect 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 OracleAS InterConnect Adapter that subscribes to the event. |
|
See Chapter 2 of the appropriate OracleAS InterConnect 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 Oracle Application Server InterConnect configuration and setup that uses D3L. This use case involves two applications using OracleAS InterConnect 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:
This use case assumes that you have already installed and configured Oracle Application Server InterConnect and iStudio.
Note:
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-20.
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.
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 OracleAS InterConnect 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.
You can choose
Note:
ObjectCopy
here because the common view and application view are based on the same D3L file.
The Subscribe Wizard - Define Mapping dialog appears as follows:
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 Oracle Application Server 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 Oracle Application Server 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.4/adapters/aqapp_pub
$ start &
To start the fileapp_sub
(FTP) adapter:
fileapp_sub
adapter is installed:
$ cd $ORACLE_HOME/oai/9.0.4/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.4\adapters\aqapp_pub
start
To start the fileapp_sub
(FTP) adapter:
fileapp_sub
adapter is installed:
cd %ORACLE_HOME%\oai\9.0.4\adapters\fileapp_sub
start
Note: You can also start adapters from the Windows Control Panel. See your OracleAS InterConnect Adapter documentation for instructions. |
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.4/adapters/aqapp_pub |
Windows |
cd %ORACLE_HOME%\oai\9.0.4\adapters\aqapp_pub |
newemp.sql
in this example) with the contents shown in Example B-21:
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:
The |
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 OracleAS InterConnect 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 OracleAS InterConnect 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".
Replacement steps Steps 2a and 2b assume that you do not have the D3L file. However, as a shortcut, you can still define the common view event attributes as they were performed in Step 6 of "Task 3: Create the newEmployee Event".
Note:
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-22 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-23 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-24 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-25 shows the DTD to which D3L (XML) files must conform.
<!ENTITY % Name "CDATA" > <!ENTITY % Number "NMTOKEN" > <!ENTITY % Comment "CDATA" > <!ENTITY % DelimiterChar "CDATA" > <!ENTITY % QuotationCharAttribute " quote %DelimiterChar; #IMPLIED " > <!-- ======================================================== --> <!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; %QuotationCharAttribute; " > <!-- ======================================================== --> <!ENTITY % Align "%Number;" > <!ENTITY % IntegerSize "( 1 | 2 | 4 | 8 )" > <!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 % StringAttributes " %GenericAttributes; " > <!ENTITY % SimpleStringAttributes " %StringAttributes; " > <!ENTITY % TerminatedStringAttributes " %StringAttributes; endchar %DelimiterChar; #REQUIRED " > <!ENTITY % QuotedTerminatedStringAttributes " %StringAttributes; %QuotationCharAttribute; endchar %DelimiterChar; #REQUIRED " > <!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 | qtdtermstring | termstring | simplestring " > <!-- ======================================================== --> <!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 % ScalarElements " signed1 | unsigned1 | signed2 | unsigned2 | signed4 | unsigned4 | signed8 | unsigned8 | float | double | date | number | padstring | pfxstring | limstring | termstring | qtdtermstring | simplestring " > <!ENTITY % TypeElements "%ScalarElements; | struct | fixarray | pfxarray | limarray | imparray " > <!-- ======================================================== --> <!ENTITY % FieldElements "%TypeElements;" > <!ENTITY % MessageElements "%TypeElements;" > <!ENTITY % StructElements "field | pad" > <!ENTITY % ArrayElements "%ScalarElements; | struct" > <!ENTITY % ImplicitArrayElements "%ArrayElements; | limarray" > <!-- ======================================================== --> <!ELEMENT message ( %MessageElements; )* > <!ATTLIST message name %Name; #REQUIRED object CDATA #REQUIRED type IDREF #REQUIRED comment %Comment; #IMPLIED id ID #IMPLIED header CDATA #IMPLIED value CDATA #IMPLIED magic CDATA #IMPLIED startsat %Number; #IMPLIED reply (Y|N) "N" %QuotationCharAttribute; > <!-- ======================================================== --> <!ELEMENT struct ( %StructElements; )* > <!ATTLIST struct %StructAttributes; > <!-- ======================================================== --> <!ELEMENT field ( typeref | %FieldElements; ) > <!ATTLIST field %FieldAttributes; > <!-- ======================================================== --> <!ELEMENT signed1 EMPTY > <!ATTLIST signed1 %IntegerAttributes; size %IntegerSize; #FIXED "1" align %Align; "1" > <!ELEMENT unsigned1 EMPTY > <!ATTLIST unsigned1 %IntegerAttributes; size %IntegerSize; #FIXED "1" align %Align; "1" > <!ELEMENT signed2 EMPTY > <!ATTLIST signed2 %IntegerAttributes; size %IntegerSize; #FIXED "2" align %Align; "2" > <!ELEMENT unsigned2 EMPTY > <!ATTLIST unsigned2 %IntegerAttributes; size %IntegerSize; #FIXED "2" align %Align; "2" > <!ELEMENT signed4 EMPTY > <!ATTLIST signed4 %IntegerAttributes; size %IntegerSize; #FIXED "4" align %Align; "4" > <!ELEMENT unsigned4 EMPTY > <!ATTLIST unsigned4 %IntegerAttributes; size %IntegerSize; #FIXED "4" align %Align; "4" > <!ELEMENT signed8 EMPTY > <!ATTLIST signed8 %IntegerAttributes; size %IntegerSize; #FIXED "8" align %Align; "8" > <!ELEMENT unsigned8 EMPTY > <!ATTLIST unsigned8 %IntegerAttributes; size %IntegerSize; #FIXED "8" align %Align; "8" > <!-- ======================================================== --> <!ELEMENT float EMPTY > <!ATTLIST float %FloatAttributes; align %Align; "4" > <!ELEMENT double EMPTY > <!ATTLIST double %FloatAttributes; align %Align; "8" > <!-- ======================================================== --> <!ELEMENT simplestring EMPTY > <!ATTLIST simplestring %SimpleStringAttributes; > <!ELEMENT qtdtermstring EMPTY > <!ATTLIST qtdtermstring %QuotedTerminatedStringAttributes; > <!ELEMENT termstring EMPTY > <!ATTLIST termstring %TerminatedStringAttributes; > <!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 | %ImplicitArrayElements; ) > <!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, 2003 Oracle Corporation. All Rights Reserved. |
|