Oracle® XML Developer's Kit Programmer's Guide 10g Release 2 (10.2) Part Number B14252-01 |
|
|
View PDF |
This appendix describes version 1.0 of the Data Loading Format (DLF), which is the standard format to describe translated messages and seed data loaded into the database by the TransX utility. It contains the following topics:
See Also:
Chapter 10, "Using the TransX Utility"DLF defines a standard format for loading data with the TransX utility. It is intended to supersede loading data with SQL scripts. DLF provides the following advantages:
Format validation. Validation results in fewer errors during the translation and loading processes.
Ease of use. The user does not have to maintain the character encoding of each data file to correspond with the language used in the data file.
DLF is based on the XML 1.0 specification.
This section describes the naming conventions used in this document.
The following naming conventions for elements and attributes are used throughout this specification:
Standard English letters
Lowercase letters only
Hyphen (-) may be used for concatenation
Attribute names must be consistently defined throughout
Industry-standard terminology should be followed wherever possible
Data Loading Format is XML, so it begins with an XML declaration. After the XML declaration comes the DLF document itself, enclosed within the <table>
element. A DLF document is composed of the following required sections:
The <lookup-key>
element contains a list of column names that determine whether existing rows in the database are duplicates of the rows in the dataset definition included in the <dataset>
element.
The <columns>
element contains metadata about the <dataset>
such as the names, datatypes, and attributes of columns.
The <dataset>
element contains a <row>
element for each row, which in turn contains a <col>
element that corresponds to a piece of data that will be loaded in a database column. In this way a DLF document looks similar to the familiar tabular format in printing data in the database and allows easy editing.
DLF provides one optional section, which is enclosed within a <translation>
element. This section may precede the required sections.
In addition, DLF provides information about TransX utility processing. Such information includes but is not limited to the following:
The <query>
element used to retrieve the value to be loaded to the column from a SQL query
The sequence
attribute used to retrieve the value to be loaded to the column from a sequence object in the database
The constant
attribute used to specify a constant value to the column
The following sections provide further details.
This section shows the possible structure of a DLF document as a tree. Each element is represented as <element_name>
, where element_name
is the name of an element. Attributes have no markup. Each element and attribute is followed by notation indicating its possible occurrence. Table 28-1 describes the occurrence notation.
Table 28-1 Notation for Occurrence of Attributes and Elements
Symbol | Meaning |
---|---|
1 | one |
+ |
one or more |
? | zero or one |
* |
zero or more |
(a|b|c) | exactly one of a, b, and c |
Example 28-1 shows the tree structure of a DLF document. The elements are described in "Elements in DLF". The attributes are described in "Attributes in DLF".
Example 28-1 DLF Tree Structure
<table>1 | +---- lang? | +---- space? | +---- <translation>? | | | +---- <target>+ | | | | | +---- <language ID> | | | +---- <restype>+ | | | +---- name1 | | | +---- expansion? | +---- <lookup-key>1 | | | +---- <column>* | | | +---- name1 | +---- <columns>1 | | | +---- <column>+ | | | +---- name1 | | | +---- type1 | | | +---- translate? | | | +---- translation-note? | | | +---- constant? | | | +---- sequence? | | | +---- virtual? | | | +---- useforupdate? | | | +---- maxsize? | | | +---- size-unit? | | | +---- restype? | | | +---- space? | | | +---- (<query>|<sql>)? | | | +---- text1 | | | +---- <parameter>* | | | +---- id1 | | | +---- (col|constant)1 | | | +---- translate? | | | +---- trans-key? | | | +---- translation-note? | | +---- <dataset>1 | +---- <row>+ | +---- space? | +---- <col>* | +---- space? | +---- name1 | +---- trans-key? | +---- translation-note? | +---- <the text element for the data>
This section contains the following topics:
The XML declaration is strongly recommended. It indicates the XML version and can be used to declare the encoding of the file, as in the following example:
<?xml version="1.0" encoding="iso-8859-1" ?>
As in all XML files, the default encoding for a DLF file is assumed to be either UTF-8, which is a superset of the 7-bit ASCII character set, or UTF-16, which is conceptually UCS-2 with surrogate pairs for code points above 65,535. Thus, for these character sets, the encoding declaration is not necessary. Furthermore, all XML parsers support these character sets. If the encoding is UTF-16, then the first character of the file must be the Unicode Byte-Order-Mark, #xFEFF, which indicates the endianness of the file.
Other character sets supported by Oracle XML parsers include all Oracle character sets and commonly used IANA character set and Java encodings. The names of these character sets can be found in the parser documentation. You must declare these with encoding declarations if the document does not have an external source of encoding information such as from the execution environment or the network protocol. Therefore, it is recommended that you use a Unicode character encoding so that you can dispense with the encoding declaration. The recommended practice is to encode the document in UTF-8 and use the following declaration:
<?xml version="1.0" ?>
There are five entity references predefined by XML. These entity references are listed in Table 28-2. The <
and &
entity references must always be used in place of the character they reference.
The DLF elements shown in Example 28-1 are divided into the categories described in Table 28-3. Attributes are shared among them. The attributes are described in "Attributes in DLF".
Table 28-3 DLF Elements
Type of Element | Tag |
---|---|
Top Level Table Element |
<table> |
Translation Elements |
<target> , <restype> |
Lookup Key Elements |
<lookup-key> , <column> |
Metadata Elements |
<columns> , <column> , <query> , <sql> , <parameter> |
Data Elements |
<dataset> , <row> , <col> |
Table 28-10 describes the top level table element.
Table 28-4 Top Level Table Element
Table 28-5 describes the translation elements.
Table 28-5 Translation Elements
Table 28-6 describes the lookup key elements.
Table 28-6 Lookup Key Elements
Table 28-7 describes the metadata elements.
Table 28-7 Metadata Elements
Table 28-8 describes the data elements.
Table 28-8 Data Elements
This section lists the various attributes used in the DLF elements. An attribute is never specified more than once for each element. Along with some of the attributes are the Recommended Attribute Values. Values for these attributes are case sensitive.
Table 28-9 Attributes
Type of Attribute | Attributes |
---|---|
DLF Attributes |
name , type , translate , constant , sequence , virtual , useforupdate , maxsize , size-unit , restype , text , id , col , trans-key , translation-note |
XML Namespace Attributes |
xml:space |
Table 28-10 describes the DLF attributes.
Table 28-10 DLF Attributes
Table 28-11 describes the XML namespace attributes.
Table 28-11 XML Namespace Attributes
Attribute | Description | Value Description | Default Value | Used by Elements |
---|---|---|---|---|
xml:space | Specifies how whitespace (ASCII spaces, tabs and line-breaks) should be treated. | "default" or "preserve"
The value |
"default" |
None |
This section contains the following topics:
Example 28-3 shows a sample DLF document that contains seed data for the CLK_STATUS_L
table.
Example 28-3 Sample DLF Document
<!-- - $Header: $ - - Copyright (c) 2001 Oracle Corporation. All Rights Reserved. - - NAME - status.xml - Seed file for the CLK_STATUS_L table - - DESCRIPTION - This file contains seed data for the Status level table. - - NOTES - - MODIFIED (MM/DD/YY) - dchiba 06/11/01 - Adaption to enhancements of data loading tool - dchiba 05/23/01 - Adaption to generic data loading tool - rbolsius 05/07/01 - Created --> <table name="clk_status_l" xml:space="preserve"> <lookup-key> <!--column name="status_id" /--> <column name="status_code" /> </lookup-key> <columns> <column name="status_id" type="number" sequence="clk_status_seq" useforupdate="no"/> <column name="status_code" type="number" /> <column name="status_name" type="string" translate="yes" /> <column name="status_description" type="string" translate="yes" /> <column name="version_created" type="number" constant="0" /> <column name="version_updated" type="number" constant="0" /> <column name="status_type_code" type="string" virtual="yes" /> <column name="status_type_id" type="number" > <query text="select status_type_id from clk_status_type_l where status_type_code = :1" > <parameter id="1" col="status_type_code" /> </query> </column> </columns> <dataset> <row> <col name="status_code" >100</col> <col name="status_name" trans-key="stts-name-1" >Continue</col> <col name="status_description" trans-key="stts-desc-1" > The client should continue with its request.</col> <col name="status_type_code" >INFO</col> </row> <row> <col name="status_code" >101</col> <col name="status_name" trans-key="stts-name-2" >Switching Protocols</col> <col name="status_description" trans-key="stts-desc-2" > The server understands and is willing to comply with the client''s request (via the Upgrade message header field) for a change in the application protocol being used on this connection.</col> <col name="status_type_code" >INFO</col> </row> <row> <col name="status_code" >200</col> <col name="status_name" trans-key="stts-name-3" >OK</col> <col name="status_description" trans-key="stts-desc-3" > The request has succeeded.</col> <col name="status_type_code" >SUCCESS</col> </row> <row> <col name="status_code" >201</col> <col name="status_name" trans-key="stts-name-4" >Created</col> <col name="status_description" trans-key="stts-desc-4" > The request has been fulfilled and resulted in a new resource being created.</col> <col name="status_type_code" >SUCCESS</col> </row> <row> <col name="status_code" >202</col> <col name="status_name" trans-key="stts-name-5" >Accepted</col> <col name="status_description" trans-key="stts-desc-5" > The request has been accepted for processing, but the processing has not been completed.</col> <col name="status_type_code" >SUCCESS</col> </row> <row> <col name="status_code" >203</col> <col name="status_name" trans-key="stts-name-6" >Non-Authoritative Information</col> <col name="status_description" trans-key="stts-desc-6" > The returned metainformation in the entity-header is not the definitive set as available from the origin server, but is gathered from a local or a third-party copy.</col> <col name="status_type_code" >SUCCESS</col> </row> <row> <col name="status_code" >204</col> <col name="status_name" trans-key="stts-name-7" >No Content</col> <col name="status_description" trans-key="stts-desc-7" > The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation.</col> <col name="status_type_code" >SUCCESS</col> </row> <!-- ... --> </dataset> </table>
Example 28-4 shows an example of elements and attributes for localization.
Example 28-4 DLF with Localization
<?xml version="1.0"?> <table name="table_name" lang="en" space="preserve"> <translation> <target>ar</target> <target>bs</target> <target>es</target> <restype name="alt" expansion="50%"/> <restype name="foo" expansion="50%"/> <restype name="bar" expansion="30%"/> </translation> <lookup-key><column name="resid" /></lookup-key> <columns> <column name="resid" type="number" sequence="seq_foo" useforupdate="no"/> <column name="image" type="binary"/> <column name="alt_text" type="string" translate="yes" maxsize="30" size-unit="byte" restype="alt"/> </columns> <dataset> <col name="image">foo1.gif</col> <col name="alt_text">Hello world</col> </dataset> </table>
See the following references for further information:
[IETFRFC3066] Tags for the Identification of Languages http://www.ietf.org/rfc/rfc3066.txt