com.unidex.xflat
Class XmlConvert

java.lang.Object
  |
  +--com.unidex.xflat.XmlConvert

public class XmlConvert

extends java.lang.Object

Your Java application can use this class to perform any of the following conversions:

• flat file to XML document
• XML document to flat file
• flat file to flat file

The conversion process is driven by an XFlat schema that describes the structure of the source file. The source file is validated against the XFlat schema.

The XFlat schema(s) and the source file are read via java.io.Reader objects. The target file is written via a java.io.Writer object.

In the following example, the XmlConvert constructor parses an XFlat schema that is contained in a file named "C:\invoices.xfl". The flatToXml() method is invoked to convert the flat file (i.e., "C:\invoices.txt") into an XML document that will be written to a file named "C:\invoices.xml".

    XmlConvert xml_convert =
           new XmlConvert( new FileReader( "C:\\invoices.xfl" ),
                           true ) ;
    xml_convert.flatToXml( new FileReader( "C:\\invoices.txt" ),
                           new FileWriter( "C:\\invoices.xml" ) ) ;
 

In the next example, the XmlConvert constructor parses an XFlat schema that is contained in a file named "C:\invoices.xfl". The xmlToFlat() method is invoked to convert an XML document (i.e., "C:\invoices.xml") into a flat file (i.e., "C:\invoices.txt").

    XmlConvert xml_convert =
           new XmlConvert( new FileReader( "C:\\invoices.xfl" ),
                           true ) ;
    xml_convert.xmlToFlat( new FileReader( "C:\\invoices.xml" ),
                           new FileWriter( "C:\\invoices.txt" ) ) ;
 

In the next example, the XmlConvert constructor parses the source XFlat schema that is contained in a file named "C:\invoices_csv.xfl". The flatToFlat() method is invoked to convert the source flat file (i.e., "C:\invoices_csv.txt"), which is in the Comma Separated Value (CSV) format, into the target flat file (i.e., "C:\invoices_ini.txt"), which will be in the Windows INI format. The format of the target flat file is described by the target XFlat schema (i.e., "C:\invoices_ini.xfl").

  XmlConvert xml_convert =
         new XmlConvert( new FileReader( "C:\\invoices_csv.xfl" ),
                         true ) ;
  xml_convert.flatToFlat( new FileReader( "C:\\invoices_csv.txt" ),
                          new FileReader( "C:\\invoices_ini.xfl" ),
                          new FileWriter( "C:\\invoices_ini.txt" ) ) ;
 

The xmlconvert/samples folder contains Java programs that invoke the XmlConvert class.

Before you invoke the XmlConvert class from your Java program, you should first do the following:

• Make sure that the full name of the xflat.jar file is included in the value of the CLASSPATH environment variable.
• Make sure that you have a Java Virtual Machine on your computer that supports Java 1.1.7 or higher.

If you plan to invoke the XmlConvert class from your Java application, then we recommend that you develop and test your XFlat schemas using the command line interface to XML Convert (i.e., using flat2xml, xml2flat or flat2flat).

The XmlConvert class is thread-safe if the threads do not share any XmlConvert instances, and if the XmlConvert instances do not share any java.io.Reader or java.io.Writer instances.

See Also:

XflatException, FileReader, FileWriter

Constructor Summary

XmlConvert(java.io.Reader schema_reader, boolean suppress_startup_message)
Creates an XmlConvert instance that can be used to perform one or more of the following conversions: flat file to XML document, XML document to flat file, or flat file to flat file.

Method Summary

void	flatToFlat(java.io.Reader source_flat_file_reader, java.io.Reader target_schema_file_reader, java.io.Writer target_flat_file_writer) Converts source flat file data into target flat file data.
void	flatToXml(java.io.Reader flat_file_reader, java.io.Writer xml_writer) Converts flat file data into an XML document using the XFlat schema that was passed to the XmlConvert constructor.
void	xmlToFlat(java.io.Reader xml_reader, java.io.Writer flat_file_writer) Converts an XML document into flat file data using the XFlat schema that was passed to the XmlConvert constructor.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XmlConvert

public XmlConvert(java.io.Reader schema_reader,
                  boolean suppress_startup_message)
           throws XflatException

Creates an XmlConvert instance that can be used to perform one or more of the following conversions:

• flat file to XML document,
• XML document to flat file, or
• flat file to flat file.

The constructor parses the specified XFlat schema and stores the information in an in-memory data structure, which is not garbage collected until after the XmlConvert instance is garbage collected. An XmlConvert instance can be used to convert multiple source files that conform with the specified XFlat schema. It is more efficient to use a single XmlConvert instance to convert multiple source files (all of which must conform to the specified XFlat schema) than it is to use multiple XmlConvert instances.

The constructor writes a start up message to standard output unless the suppress_startup_message parameter is set to true.

If the XFlat schema is not a well-formed XML document or if it does not conform to the XFlat language, then the constructor will throw an XflatException, whose message will contain a detailed description of the syntax error. The exception message will include the line number and column number at which the error was found. The line number of the first line in the schema is one. The column number of the first character in a line is one.

Parameters:

schema_reader - The Reader from which the XFlat schema is read.

suppress_startup_message - The XmlConvert constuctor will not display the start up message to standard output if this boolean flag is set to true.

Throws:

XflatException - if an I/O error occurs while reading the XFlat schema file, or if the XFlat schema is not well-formed, or if the XFlat schema does not conform to the XFlat language.

See Also:

Reader, XflatException

Method Detail

flatToXml

public void flatToXml(java.io.Reader flat_file_reader,
                      java.io.Writer xml_writer)
               throws XflatException

Converts flat file data into an XML document using the XFlat schema that was passed to the XmlConvert constructor.

If the flat file data does not conform to the XFlat schema, then the conversion is aborted and the flatToXml() method throws an XflatException. The exception message will contain a detailed description of the syntax error, including the following information about the location of the error:

• the record number
• the column number (from the beginning of the record)
• the record offset in characters (from the beginning of the flat file data)

The record number of the first record in the flat file data is one. The column number of the first character in a record is one. The record offset of the first record in the flat file data is one. If the first record is 80 characters in length, then the record offset of the second record is 81.

When the conversion is aborted, the XML output will contain a partial XML document, which is useful for troubleshooting the syntax error.

The flatToXml() method will close the flat file reader and the XML writer before returning or throwing an exception.

Parameters:

flat_file_reader - A java.io.Reader object from which the flat file data is read. The flat file data will be converted into XML. The user's application does not need to wrap this Reader with a buffered reader, since XML Convert will do this.

xml_writer - A java.io.Writer object to which the XML document will be written. The XML document is the output of the conversion process. The user's application does not need to wrap this Writer with a buffered writer, since XML Convert will do this.

Throws:

XflatException - if an I/O error occurs or if the flat file data does not conform to the XFlat schema.

See Also:

Reader, Writer, XflatException

xmlToFlat

public void xmlToFlat(java.io.Reader xml_reader,
                      java.io.Writer flat_file_writer)
               throws XflatException

Converts an XML document into flat file data using the XFlat schema that was passed to the XmlConvert constructor.

If the XFlat Instance (i.e., the XML source document) does not conform to the XFlat schema, then the conversion is aborted and the xmlToFlat() method throws an XflatException. The exception message will contain a detailed description of the syntax error, including the following information about the location of the error:

• the line number
• the column number (from the beginning of the line)

The line number of the first line in the XML source document is one. The column number of the first character in a line is one.

When the conversion is aborted, the target file will contain part of the flat file data, which is useful for troubleshooting the syntax error.

The xmlToFlat() method will close the flat file writer before returning or throwing an exception.

Parameters:

xml_reader - A java.io.Reader object from which the source XML document is read. The XML document will be converted into flat file data.

flat_file_writer - A java.io.Writer object to which the flat file data will be written. The flat file data is the output of the conversion process. The user's application does not need to wrap this Writer with a buffered writer, since XML Convert will do this.

Throws:

XflatException - if an I/O error occurs, or if the source XML document is not well-formed, or if the source XML document does not conform to the XFlat schema.

See Also:

Reader, Writer, XflatException

flatToFlat

public void flatToFlat(java.io.Reader source_flat_file_reader,
                       java.io.Reader target_schema_file_reader,
                       java.io.Writer target_flat_file_writer)
                throws XflatException

Converts source flat file data into target flat file data. The source XFlat schema (i.e., the XFlat schema of the source flat file) is the XFlat schema that was passed to the XmlConvert constructor.

The flatToFlat() method uses the source XFlat schema to validate the source flat file data and to convert the source flat file data into an intermediary stream of SAX 1.0 document events; flatToFlat() then uses the target XFlat schema to validate this stream of events and to convert the stream into the target flat file data. The intermediary stream of SAX document events are not written to a file.

Calling the flatToFlat() method to convert source flat file data into target flat file data is equivalent to calling the flatToXml() method to convert source flat file data into an XML document, and then calling the xmlToFlat() method to convert this XML document into target flat file data. However, please note that the flatToFlat() method does not create an intermediary XML document. Also, if the target schema Reader is the same object as the source schema Reader, which was passed to the XmlConvert constructor, then the flatToFlat() method will not read the target XFlat schema; instead, it will assume that the target XFlat schema is the same as the source XFlat schema. Thus, it is more efficient to use flatToFlat() than it is to use flatToXml() followed by xmlToFlat().

If the source flat file data does not conform to the source XFlat schema, then the conversion is aborted and the flatToFlat() method throws an XflatException. The exception message will contain a detailed description of the syntax error, including the following information about the location of the error:

• the record number
• the column number (from the beginning of the record)
• the record offset in characters (from the beginning of the flat file)

The record number of the first record in the flat file data is one. The column number of the first character in a record is one. The record offset of the first record in the flat file is one. If the first record is 80 characters in length, then the record offset of the second record is 81.

When the source flat file data is converted into the stream of SAX document events, the flatToFlat() method verifies that these events conform to the target XFlat schema (i.e., the XFlat schema of the target flat file data). If the stream of SAX document events does not conform to the target XFlat schema, then the conversion is aborted and the flatToFlat() method throws an XflatException. The exception message will contain a detailed description of the syntax error. Even though the stream of SAX document events are essentially an XML document, the flatToFlat() method can not provide the location of the error within the stream. Instead, the exception message contains the record number of the last record that was read from the source flat file data.

When the conversion is aborted, the target flat file will contain part of the flat file data, which is useful for troubleshooting the syntax error.

The flatToFlat() method will close the source flat file reader and the target flat file writer before returning or throwing an exception.

Parameters:

source_flat_file_reader - A java.io.Reader object from which the source flat file data is read. The source flat file data will be converted into the target flat file data. The user's application does not need to wrap this Reader with a buffered reader, since XML Convert will do this.

target_schema_file_reader - A java.io.Reader object from which the target XFlat schema is read. The target XFlat schema is the XFlat schema of the target flat file data. If the target schema Reader is the same object as the source schema Reader, which was passed to the XmlConvert constructor, then the flatToFlat() method will not read the target XFlat schema; instead, it will assume that the target XFlat schema is the same as the source XFlat schema.

target_flat_file_writer - A java.io.Writer object to which the target flat file data will be written. The target flat file data is the output of the conversion process. The user's application does not need to wrap this Writer with a buffered writer, since XML Convert will do this.

Throws:

XflatException - if an I/O error occurs, or if the target XFlat schema is not well-formed, or if the target XFlat schema does not conform to the XFlat language, or if the source flat file data does not conform to the source XFlat schema, of if the stream of SAX document events do not conform to the target XFlat schema.

See Also:

XflatException, Reader, Writer