A document type document (DTD) is a data model for XML documents that provides a special syntax to describe the XML document's template, called a schema. This DTD is a file with the .dtd extension. The business object definitions that represent the schema of an XML document use information in the DTD to preserve and record the document's structure. This section provides the following information about deriving structure information for a business object definition from a DTD:
To ensure that business object definitions that correspond to DTDs conform to the requirements of the XML data handler, use the guidelines in this section, which involve:
A properly-constructed business object definition ensures that the data handler can correctly convert a business object to an XML document and an XML document to a business object. For information on how to create business objects for the XML data handler, see XML documents that use schema documents.
To represent a DTD requires at least the two business object definitions described in Business object structure. For a DTD, these business object definitions have the following additional requirements:
Whether the XML ODA generates a DocType attribute in the top-level business object definition depends on the setting of its DocTypeOrSchemaLocation configuration property. For more information, see For an XML DOCTYPE declaration and Supported DTD structures.
This attribute must has the type=pi tag in its application-specific information. For more information, see For XML processing instructions.
As described in Business object structure, this attribute must have as its type a single-cardinality business object, whose type is the business object definition for the root element. The application-specific information must list the name of this element with the elem_name tag. For more information, see For XML elements.
A business object that is processed by the XML data handler using business object definitions based on DTDs must also follow these rules:
An example DTD for an XML document is shown below. The DTD is named Order, and it contains elements that correspond to an application Order entity.
<!--Order --> <!-- Element Declarations --> <!ELEMENT Order (Unit+)> <!ELEMENT Unit (PartNumber?, Quantity, Price, Accessory*)> <!ELEMENT PartNumber (#PCDATA)> <!ELEMENT Quantity (#PCDATA)> <!ELEMENT Price (#PCDATA)> <!ELEMENT Accessory (Quantity, Type)> <!ATTLIST Accessory Name CDATA > <!ELEMENT Type (#PCDATA)>
Figure 13 shows the structure of a business object that might be created to correspond to an XML document associated with the Order DTD. Note that each XML element and element attribute in the Order DTD has a corresponding business object attribute. The top-level business object contains attributes for the XML declaration, the DOCTYPE, and the top-level Order element. Note also that the element attribute Name is the first attribute in the Accessory business object.
Figure 13. Example business object for XML document using the Order DTD
When the business object definitions for an XML document are based on DTDs, the business object attribute properties have the restrictions discussed in Business object attribute properties. In addition, the DTD syntax can determine the "required-ness" of a business object attribute. The "required-ness" is a combination of factors, including cardinality and whether the attribute is a key, that determines whether the XML data handler requires the attribute. If an attribute is required, its Required attribute property must be set to true.
The setting of the Required attribute property depends on the XML element and attribute specifications, as well as the settings of the Cardinality, Key, and Foreign Key attribute properties, as follows:
Table 13. Cardinality and "Required-ness" for a DTD
DTD ELEMENT fragment | Cardinality | Required |
---|---|---|
None specified | 1 | Yes |
? | 1 | No |
+ | N | Yes |
* | N | No |
EMPTY | N | No |
Table 14. Keys and "Required-ness" for a DTD
This section provides the following information on the application-specific information format for business object definitions based on DTDs:
The XML data handler uses the following types of business objects to represent different kinds of XML elements generated from a DTD:
These types of business objects are distinguished by the application-specific information at the business object level.
A regular business object represents an XML element. In this type of business object, the application-specific information at the business object level identifies the name of the XML element that the business object represents. For example, suppose the XML element is defined as:
<!ELEMENT Unit(...)>
The application-specific information at the business object level for the associated business object definition is:
[BusinessObjectDefinition] Name = MyApp_Unit AppSpecificInfo = elem_name=Unit [Attribute] ...
A mixed business object represents a mixed XML element, one that contains mixed content of character data (#PCDATA ) and other subelements. The DTD representation of a mixed-type XML element looks like the following:
<!ELEMENT (#PCDATA | CONTAINED_ELEMENT1 | CONTAINED_ELEMENTN)*>
For example, suppose the Cust XML element is defined in the DTD as follows:
<!ELEMENT Cust(#PCDATA | Address | Phone)*>
To represent a mixed-type XML element, use a mixed-type business object definition. For a mixed business object definition, its business-object-level application-specific information consists of the following components:
For the business object definition, MyApp_Cust, which represents the Cust element, the application-specific information at the business object level is as follows:
[BusinessObjectDefinition] Name = MyApp_Cust AppSpecificInfo = Cust;type=MIXED;
A wrapper business object represents a repeating choice list. This type of business object definition is needed when an XML element has children that can appear in any order and be of any cardinality. A wrapper business object preserves the order and cardinality of the child elements in the XML document.
For a choice-list XML element, the DTD definition looks like this:
(CONTAINEDELEMENT1 | ... | CONTAINEDELEMENTN)*
As an example, the choice-list XML element definition in a DTD might be:
<!ELEMENT CUST( U | I | B )* )>
This element contains three subelements that are optional and that can appear in any order. Each subelement is a simple element. Figure 14 shows an XML document of this type.
Figure 14. XML document content for a repeating choice list
<CUST> <U>..... </U> <B>..... </B> <I>..... </I> <B>..... </B> <U>..... </U> ...
To represent a choice-list XML element defined in a DTD, the business object definition is hierarchical. It includes the following business object definitions:
This parent business object definition contains a single attribute that represents a multiple-cardinality business object array. This attribute has as its type the business object definition for the associated wrapper business object. The parent business object definition contains the following application-specific information:
(choiceElement1|...|choiceElementN)
where choiceElement1...choiceElementN correspond to each of the choice elements defined. The pipe (|) character must separate each of the choice elements and the entire tag must be enclosed in parentheses.
The wrapper business object definition contains one attribute for each of the choice elements defined in the choice-list element. It does not require any application-specific information at the business-object level.
Figure 15 shows an illustration of the hierarchy of the business object definitions for a choice-list XML element. At runtime, each child business object is an instance of a wrapper business object and has only one attribute populated with data. As an example, a business object for the XML content in Figure 14 would have five children, each with the appropriate attribute populated.
Figure 15. Hierarchical business object definition for choice-list XML element
Figure 16 shows the parent business object definition, MyApp_Cust, with its application-specific information.
Figure 16. Parent business object definition for a choice-list element
[BusinessObjectDefinition] Name = MyApp_Cust AppSpecificInfo = CUST [Attribute] Name = CustWrapper Type = MyApp_CustWrapper Cardinality = N AppSpecificInfo = attr_name=CustWrapper;(U|I|B) [End]
The wrapper business object definition, MyApp_CustWrapper, has three attributes, one for each choice element. Because each choice element contains character data, the application-specific information for each attribute specifies:
Figure 17 shows the wrapper business object definition for this XML document.
Figure 17. Wrapper business object definition for a choice-list element
[BusinessObjectDefinition] Name = MyApp_CustWrapper AppSpecificInfo = [Attribute] Name = DataU Type = String AppSpecificInfo = attr_name=U;type=pcdata; [End] [Attribute] Name = DataI Type = String AppSpecificInfo = attr_name=I;type=pcdata; [End] [Attribute] Name = DataB Type = String AppSpecificInfo = attr_name=B;type=pcdata; [End]
If a business object attribute represents an XML element that contains other elements, the application-specific information must contain the name of the element. For example, if an attribute named DeliveryDate has a business object type and represents an element named DATETIME, the application-specific information contains the name of the element:
Name = DeliveryDate Relationship = Containment Cardinality = n AppSpecificInfo = DATETIME
The attribute of a business object definition can represent the following XML components:
Table 23 shows the tags for attribute-level application-specific
information for these different XML components along with the sections in this
manual that describe these tags in more detail.
Table 15. Tags for attribute application-specific information
Representation of business object attribute | Application-specific information | For more information |
---|---|---|
An XML element | For XML elements | |
An XML element with only PCDATA | For an XML element with only PCDATA | |
An attribute for an XML element | For an XML attribute | |
An XML element that contains character data and attributes | For an XML element with character data and attributes | |
An XML element or attribute whose content includes special characters | For an XML element or attribute that contains special characters | |
For a DOCTYPE declaration | For an XML DOCTYPE declaration | |
For a CDATA section | For a CDATA section | |
A comment to be added to the XML document | type=comment | For an XML comment |
A processing instruction | type=pi | For XML processing instructions |
Every simple (String) business object attribute that represents an XML element must include the elem_name tag in its application-specific information to identify the associated element:
elem_name=name of XML element
For example, if a business object attribute CustLName represents a simple XML attribute, its application-specific information is:
Name = CustLName AppSpecificInfo = elem_name=CustLName;
XML element names can contain special characters (such as periods and hyphens). However, the names of business object attributes cannot contain these special characters. Therefore, the name of the XML element must be specified in the elem_name tag. To name the business object attribute, the XML ODA removes any special characters in the XML element's name, replacing them with an underscore (_) character.
In the following example, the application-specific information for the XML element specifies a different from the actual XML element's name because the attribute contains a special character:
Name = Phone_Tag AppSpecificInfo = elem_name=Phone#Tag;
The actual name of the XML element contains a pound sign (#), which is invalid in the names of business-object attributes. Therefore, the elem_name tag in the application-specific information specifies the actual XML element name. In the name of the associated business-object attribute, the pound sign is replaced with an underscore.
XML elements that contain only character data are mixed elements, which contain only the PCDATA element content specifier. A business object attribute that represents an XML element with only PCDATA must have the following type tag in the application-specific information:
type=pcdata
In this case, the element name is the first field in the application-specific information, and the type parameter is the second field.
For example, an element named PartNumber that contains only PCDATA would have the following definition in the DTD:
<!ELEMENT PartNumber (#PCDATA)>
The corresponding attribute in the business object definition would have the following application-specific information:
Name = PartNumber AppSpecificInfo = elem_name=PartNumber;type=pcdata;
If the application-specific information also contains the text notag, the XML data handler does not generate XML markup. It adds only the value of the attribute itself to the XML document. For more information, see For an XML element with character data and attributes.
If a business object attribute represents an attribute of an XML element, its application-specific information must include the following tags:
attr_name=attrName
XML attribute names can contain special characters (such as periods and hyphens). However, the names of business object attributes cannot contain these special characters. Therefore, the name of the XML attribute must be specified in the attr_name tag. To name the business object attribute, the XML ODA removes any special characters in the XML attribute's name.
type=attribute
This type tag identifies the purpose of the associated business object attribute as an XML attribute.
For example, if a business object attribute named ID represents an XML attribute named ID, its application-specific information is:
Name = ID AppSpecificInfo = attr_name=ID;type=attribute;
For another example that uses the type=attribute tag, see For an XML element with character data and attributes.
If an XML element contains only PCDATA or CDATA and has one or more XML attributes, its business object definition must include the following attributes:
The attribute name must match the name of the XML attribute. Its attribute-level application-specific information must include the attr_name and type=attribute tags. For more information, see For an XML attribute.
This attribute contains the data that is associated with the parent XML element. Its application-specific information must contain:
For example, suppose an XML element named Price has an attribute named Currency and requires data for Price:
<!ELEMENT Price (#PCDATA)> <!ATTLIST Price Currency NMTOKEN #IMPLIED>
Because the Price element has an XML attribute, in its business object definition a business-object attribute must created for Currency. In addition, another attribute must exist to hold the Price data. The attribute for the Price data must specify notag in its application-specific information to prevent the data handler from creating a start and end tag for this attribute.
The Price child business object might look like this:
[BusinessObjectDefinition] Name = Price AppSpecificInfo = Price
[Attribute] Name = Currency Type = String AppSpecificInfo = attr_name=Currency;type=attribute; ... [End]
[Attribute] Name = Price Type = String AppSpecificInfo = Price;type=pcdata;notag ... [End]
In this case, the data handler does not generate a new XML element for the Price data but simply adds the data to the parent element.
Business object attributes representing XML elements or XML attributes with content that require escape processing must include the following tag in their application-specific information:
escape=true
An attribute requires escape processing if the attribute represents an XML element whose value contains any of the following special characters:
An attribute will not be escape-processed unless it contains the escape=true tag in its application-specific information. This tag must be placed at the end of any existing application-specific information. For example:
[Attribute] Name=Data Type=String AppSpecificInfo=Price;type=pcdata;escape=true [End]
If the attribute's application-specific information does not include the escape tag, the XML data handler checks the value of the DefaultEscapeBehavior property to determine whether to perform escape processing:
If a business object attribute represents a document type declaration in the prolog, the application-specific information must include the following type tag:
type=doctype
For example, if a business object attribute named DocType represents a DOCTYPE element, its application-specific information is:
Name = DocType AppSpecificInfo = type=doctype;
If the DocType attribute has the value:
DOCTYPE CUSTOMER "customer.dtd"
then the data handler generates the following XML:
<!DOCTYPE CUSTOMER "customer.dtd">
This application-specific information may also be used to include general entity declarations in the XML document. However, there is no explicit support for the inclusion of an internal DTD or parameter entity declarations. These can be included in the document by putting the entire text into the value of an attribute that has type=doctype in the application-specific information.
If a business object attribute represents a CDATA section within an XML document, the application-specific information must include the following type tag:
type=cdata
For example, if a business object attribute UserArea represents a CDATA section, its application-specific information is:
Name = UserArea AppSpecificInfo = type=cdata;
When the XML data handler converts a business object to an XML document, you can specify that it add comments to the XML document. To enable the data handler to add comments, take the following steps:
type=comment
For example, if a business object attribute named Comment represents an XML comment that the data handler should add to an XML document, the Comment attribute would appear as follows:
Name = Comment AppSpecificInfo = type=comment;
If this attribute has the value "Customer information update from application A", the following XML is generated:
<!--Customer information update from application A-->
If a business object attribute represents a processing instruction, the application-specific information must include the following type tag:
type=pi
For example, if a business object attribute named XMLDeclaration represents the XML declaration in the prolog, the application-specific information is:
Name = XMLDeclaration AppSpecificInfo = type=pi;
If the attribute has the value:
xml version = "1.0"
then the XML data handler generates the following XML:
<?xml version="1.0"?>
A DTD describes the format of an XML document. Therefore, the DTD is very useful for obtaining information needed for the business object definition. To translate the structure information in the DTD to a business object definition, you can use the XML Object Discovery Agent (ODA). For information on XML ODA, see Using an XML ODA to create business object definitions.
The XML ODA supports structures of a DTD including:
<!ENTITY % name value>
<!ELEMENT SCENE (ANY) >
The corresponding business object definition is:
[Attribute] Name = SCENE Type = String Cardinality = 1 MaxLength = 255 IsKey = false IsForeignKey = false IsRequired = true AppSpecificInfo = SCENE;type=pcdata; [End]
The XML ODA is capable of processing most DTDs. However, it does not support the following DTD structures: