XML Convert 2.2

Invoking XML Convert as an XT Output Method

This page describes how to invoke XML Convert from XT, which is James Clark's XSLT processor. XML Convert includes a public Java class, named com.unidex.xflat.XtFlatFileBuilder, which can be invoked by XT as an output method.

If you specify the com.unidex.xflat.XtFlatFileBuilder class as the output method of your XSLT stylesheet, then XT will transform the source XML document into a target flat file, the layout of which is specified in an XFlat schema. Thus, XT will write flat file data to the result file. Specifically, XT will transform the source XML document into a result tree, and will pass the result tree to XML Convert as a stream of SAX 1.0 document events. XML Convert will verify that this stream conforms to the specified XFlat schema, and will convert this stream into the target flat file data.

NOTE: XML Convert does not include XT. You can download XT for free at http://www.jclark.com/xml/xt.html.

Before you invoke the com.unidex.xflat.XtFlatFileBuilder class from XT, you should first do the following:

• Make sure that you have version 19991105 of XT installed on your computer. The XtFlatFileBuilder class has been tested with only version 19991105 of James Clark's XT.
• Make sure that the path name of the xflat.jar file is included in the value of the CLASSPATH environment variable.
• Make sure that the Java Virtual Machine that is installed on your computer supports Java 1.1.7 or higher.
• Develop and test your XSLT stylesheet with the output method set to xml, so that XT writes an XML document to the result file.
• Develop and test your XFlat schema using the xml2flat application, which will convert the result file (containing an XML document) into the target flat file.

The XtFlatFileBuilder class is an XT output method that converts a result tree into a flat file, the layout of which is specified in an XFlat schema. The class also verifies that the result tree conforms to the XFlat schema.

The following is an example of an XSLT stylesheet that specifies the com.unidex.xflat.XtFlatFileBuilder class as the output method:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                version="1.0">
    <xsl:output method="java:com.unidex.xflat.XtFlatFileBuilder"
                xmlns:java="http://www.jclark.com/xt/java"
                xflat:SchemaFile="c:\xflat_schemas\contacts.xfl"
                xmlns:xflat="http://www.unidex.com/xflat" />
    <!-- Note that the xflat:SchemaFile attribute
         specifies the name of the XFlat schema file. -->
    <!-- The rest of the stylesheet goes here. -->
</xsl:stylesheet>

Please note the following about this XSLT stylesheet:

• The method attribute specifies the com.unidex.xflat.XtFlatFileBuilder class as the output method.
• The value of the method attribute must be in the http://www.jclark.com/xt/java namespace.
• If the value of the method attribute is not spelled correctly or is not in the proper namespace, then XT will convert the result tree into XML and will not issue an error.
• If the path name of the xflat.jar file is not included in the value of the CLASSPATH environment variable, then XT will convert the result tree into XML and will not issue an error.
• The SchemaFile attribute specifies the name of the XFlat schema file. The com.unidex.xflat.XtFlatFileBuilder class verifies that the result tree conforms to the specified XFlat schema.
• The SchemaFile attribute must be in the http://www.unidex.com/xflat namespace.
• The SchemaFile attribute is a proprietary extension of the XSLT language. In other words, this attribute is not part of the XSLT recommendation and it is not a proprietary XT feature.

The following sections of the Examples page further illustrate how to invoke XT, so that it uses the XtFlatFileBuilder class to transform the result document into a flat file:

• Using XT to Convert an XML Document into a Flat File
• Using flat2xt to Convert a Flat File from one Format to Another

If XML Convert encounters any errors (e.g., an invalid XFlat schema, the result tree does not conform to the XFlat schema, etc.), then XT will abort the transformation and write an error message to standard error. The error message will include a detailed description of the error.

If an error is found in the XFlat schema (e.g., a well-formedness error or the XFlat schema does not conform to the XFlat language), then the error message will include the following information about the location of the error:

• the name of the XFlat schema file
• the line number
• the column number

The file name is displayed as a system identifier (e.g., file:/c:/invoices.xfl). The line number of the first line in the file is one. The column number of the first character in a line is one.

If the result tree does not conform to the XFlat schema, then XT will abort the transformation and write an error message to standard error. The error message will contain a detailed description of the syntax error. Even though the result tree is essentially an XML document, the error message will not contain the location of the error within the result tree.

We recommend that you use the xml2flat application when developing and debugging the XFlat schema that is specified in the XSLT stylesheet, since xml2flat will include the line number and column number of any errors in the XML input file.

The XtFlatFileBuilder class ignores the following standard attributes of the XSLT output instruction:

• version
• omit-xml-declaration
• standalone
• doctype-public
• doctype-system
• cdata-section-elements
• indent

The XtFlatFileBuilder class does not ignore the encoding and media-type attributes, which are standard attributes of the XSLT output instruction. The default value of the encoding attribute is the default encoding of your Java Virtual Machine. The default value of the media-type attribute is "text/plain".

The XtFlatFileBuilder class is an implementation of the com.jclark.xsl.sax.OutputDocumentHandler interface.

The XtFlatFileBuilder class will only work with James Clark's XT; it will not work with any other XSLT processors. Also, the XtFlatFileBuilder class has been tested with only version 19991105 of James Clark's XT.

Note that an XSLT processor can convert an XML document into non-XML text, without any help from XML Convert. Thus, you could use an XSLT processor without XML Convert to transform an XML document into a flat file. However, it would be difficult to write an XSLT stylesheet that rejects an input document that cannot be transformed into a valid flat file. It's important to reject a source document that cannot be transformed into a valid flat file, so that the receiving application does not import an invalid flat file.