Overview

The XML data handler is a data-conversion module whose primary role is to convert business objects to and from XML documents. An XML document is serialized data with the text/xml MIME type. The XML data handler can be used by connectors and by access clients.

This overview provides the following information about the XML data handler:

Processing XML documents and business objects

XML documents use a template, called a schema, to define their structure. Table 11 shows the most common data models for defining this schema.

Table 11. XML data models

XML data model For more information
Document type definitions (DTDs) XML documents that use DTDs
Schema documents XML documents that use schema documents

Just as a DTD or a schema document describes the structure of the XML document, the business object definition describes the structure of the business object. The XML data handler uses business object definitions when it converts between business objects and XML documents. It determines how to perform the conversion using the structure of the business object definition and its application-specific information. 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. Before the XML data handler can perform a conversion between XML document and business object, it must be able to locate the associated business object definition.

Use of the XML data handler to convert an XML document to a business object or a business object to an XML document requires that the following steps occur.

Table 12. Using the XML data handler

Step For more information
1. Business object definitions that describe the XML and business-object structure must exist and be available to the XML data handler when it executes. Requirements for business object definitions
Creating business object definitions from DTDs
2. The XML data handler must be configured for your environment. Configuring the XML data handler
3. The XML data handler must be called from a connector (or access client) to perform the appropriate data operation:
a) Data operation: receive a business object from the caller, convert the business object to an XML document, and pass the XML document to the caller. Converting business objects to XML documents
b) Data operation: Receive an XML document from the caller and use the name handler and SAX parser to build a business object. Then return the business object to the caller. Converting XML documents to business objects

XML data handler components

The XML data handler uses following components to convert XML data to a business object:

Figure 11 illustrates the XML data handler components and their relationship to one another. These components are described in the sections that follow.

Figure 11. XML data handler components


Name handler

The XML data handler uses the name handler to extract the name of the business object from an XML message. The data handler invokes an instance of the name handler based on the value of the NameHandlerClass attribute in the XML data handler child meta-object:

For information on how to create a custom name handler, see "Building a custom XML name handler".

SAX parser

If a parser is not specified in the Default Value property of the Parser attribute in the XML child meta-object, the data handler uses the default SAX Parser:

org.apache.xerces.parsers.SAXParser

To use a validating parser, you can take either of the following steps:

Note:
When using a validating parser, make sure that you are using the correct EntityResolver and that the DTDPath is set correctly. For instruction on how to do this, see Configuring the XML data handler.

Alternatively, you may use the non-validating SAX Parser from IBM. To use this parser, set the Default Value property of the Parser attribute of the XML child meta-object to the value com.ibm.xml.parsers.SAXParser.

Entity resolver

The entity resolver specifies how the SAX parser resolves external references (such as references to DTDs and schema documents) in XML data. If the XML document contains entity references, the SAX parser invokes an instance of the entity resolver using the EntityResolver attribute in the XML data handler configuration meta-object.

External references are handled differently depending on the entity-resolver class that EntityResolver specifies. Table 13 shows the entity-resolver classes that the XML data handler provides.

Table 13. Entity-resolver classes for the XML data handler

Entity-resolver class Description
DefaultEntityResolver

This class is the default entity resolver. If this entity resolver is invoked, all external references are ignored.

LocalEntityResolver

The local entity resolver processes external references as local file names. Its behavior depends on the data model used for validation:

  • If DTDs are used for validation, the local entity resolver substitutes the path in the systemID with the value of the DTDPath meta-object attribute, if the systemID starts with file:// or http:// and the DTDPath attribute is set. The external reference is ignored if the systemID is not a path name or the DTDPath attribute is not set.
  • If schema documents are used for validation, the local entity resolver substitutes the path that the schemaLocation or noNamespaceSchemaLocation attribute specifies with the value of the DTDPath meta-object attribute, if path starts with file:// or http://, or it contains a DOS filename (for example, "D:\xmlschemas\test").

URIEntityResolver

This entity resolver processes external references as local file names or downloadable URLs. It dynamically resolves the external reference in either of the following cases:

  • If DTDs are used for validation: if the DOCTYPE contains a SYSTEM value that begins with http:// or file://
  • If schema documents are used for validation: if the schemaLocation or noNamespaceSchemaLocation attribute begins with http:// or file://

The entity resolver then opens an HTTP connection and downloads the DTD or schema document from the specified web site.

Attention: The XML data handler does not cache the DTDs or schema documents. When the data handler uses the URIEntityResolver class as its entity resolver, it opens an HTTP connection each time it parses the XML document. Therefore, network traffic can impact the performance of the XML data handler.

Note:
All entity-resolver classes in Table 13 must have the following class prefix:
com.crossworlds.DataHandlers.xml

If your XML documents use schema documents, any external schemas that the schema document includes are also treated as external entities. Therefore, the SAX parser invokes an entity resolver to resolve these included schema documents. If the XML document uses the schemaLocation or noNamespaceSchemaLocation to specify schema locations, you can set the EntityResolver attribute to either LocalEntityResolver or URIEntityResolver for validation of external schema documents (either included or imported).

If you need to specify another way to find external entities, you must create a custom entity resolver. For information on creating a custom entity resolver, see Building a custom entity resolver.

Copyright IBM Corp. 1997, 2004