com.unidex.xflat
Class SaxFlatFileBuilder

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

All Implemented Interfaces:

org.xml.sax.DocumentHandler

Deprecated. This class is still available, but it has been superseded by the Sax2FlatFileBuilder class. SAX 1.0 has been superseded by SAX 2.0.

public class SaxFlatFileBuilder

extends java.lang.Object

implements org.xml.sax.DocumentHandler

The SaxFlatFileBuilder class is an implementation of the org.xml.sax.DocumentHandler interface. Loosely speaking, the SaxFlatFileBuilder class converts an XML document into flat file data, the layout of which is specified by an XFlat schema. More precisely, the class converts a stream of SAX 1.0 document events into flat file data. The class also verifies that the stream of SAX 1.0 document events conforms to the XFlat schema.

If the stream of SAX 1.0 document events does not conform to the XFlat schema, then the conversion is aborted and the SaxFlatFileBuilder class throws a SAXException. The exception message will contain a detailed description of the syntax error, including the following information about the location of the error:

• the system identifier of the XML source document (if applicable and available)
• the line number (if applicable and available)
• the column number (if applicable and available)

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, some of the flat file data will probably have been written to the flat file writer; the partial flat file data is useful for troubleshooting the syntax error.

The SaxFlatFileBuilder class is reusable. In other words, a SaxFlatFileBuilder object can be used to convert multiple XML documents. This feature also allows a SaxFlatFileBuilder object to handle an XFlat schema in which the flat file is mapped to multiple XML documents. When converting multiple XML documents using a single SaxFlatFileBuilder object, you can use the same XFlat schema and flat file writer for all the XML documents, or you can specify a new XFlat schema and/or a new flat file writer for each XML document.

The SaxFlatFileBuilder class can handle a stream of SAX 1.0 document events that includes multiple top-level elements. This feature allows the class to handle a stream of SAX 1.0 events from an XSLT processor, the output of which may be an external general parsed entity rather than a well-formed document.

The setXflatSchema() and setFlatFileWriter() methods must be called before the startDocument() method is called for the first time. The user's application calls these two methods to specify the input source of the XFlat schema and the flat file data writer.

Once the startDocument() method has been called, the setXflatSchema() method must not be called before the next call to the endDocument() method.

The following sample application uses the SaxFlatFileBuilder class to convert an XML document (i.e., "file:/c:/invoices.xml") into a flat file (i.e., "file:/c:/invoices.txt"). The XP parser parses the XML document and generates a stream of SAX 1.0 document events. The parser passes these events to an instance of the SaxFlatFileBuilder, which will convert these events into flat file data. The conversion is driven by the XFlat schema (i.e., "file:/c:/invoices.xfl") that is specified via the setXflatSchema() method.

 import com.jclark.xml.sax.Driver ; // The XP parser.
 import com.unidex.xflat.SaxFlatFileBuilder ;
 import java.io.FileWriter ;
 import org.xml.sax.InputSource ;
 
 public class UserApp2 {
 
   public static void main ( String args[] )
     throws Exception
   {
         // Create the input sources and the output writer.
         InputSource xml_source = 
                 new InputSource( "file:/c:/invoices.xml" ) ;
         InputSource xflat_schema_source = 
                 new InputSource( "file:/c:/invoices.xfl" ) ;
         FileWriter flat_file_writer = 
                 new FileWriter( "c:/invoices.txt" ) ;
 
         // Create a SaxFlatFileBuilder.
         SaxFlatFileBuilder builder = new SaxFlatFileBuilder( ) ;
 
         // Tell the SaxFlatFileBuilder about the XFlat schema
         // and the flat file writer.
         boolean suppress_startup_message = true ;
         builder.setXflatSchema( xflat_schema_source,
                                 suppress_startup_message ) ;
         boolean keep_open = false ;
         builder.setFlatFileWriter( flat_file_writer,
                                    keep_open ) ;
 
         // Create a new SAX-compliant parser (James Clark's XP parser).
         Driver xml_parser = new Driver() ;
 
         // Tell the parser about the SaxFlatFileBuilder.
         xml_parser.setDocumentHandler( builder ) ;
 
         // Parse the XML doc and convert it to a flat file.
         xml_parser.parse( xml_source ) ;
   }
 }
 

The SaxFlatFileBuilder class is thread-safe if the threads do not share any SaxFlatFileBuilder instances and if the SaxFlatFileBuilder instances do not share any character streams or byte streams.

See Also:

FileWriter, InputSource, DocumentHandler, HandlerBase, SAXException

Constructor Summary

SaxFlatFileBuilder()
Deprecated. Creates a SaxFlatFileBuilder instance that can be used to convert a stream of SAX 1.0 document events into flat file data.

Method Summary

void	characters(char[] chars, int start, int length) Deprecated. Receive notification of character data inside an element.
void	endDocument() Deprecated. Receive notification of the end of a document.
void	endElement(java.lang.String element_name) Deprecated. Receive notification of the end of an element.
void	ignorableWhitespace(char[] white_space, int start, int length) Deprecated. Receive notification of ignorable whitespace.
void	processingInstruction(java.lang.String target, java.lang.String data) Deprecated. Receive notification of a processing instruction.
void	setDocumentLocator(org.xml.sax.Locator locator) Deprecated. Receive an org.xml.sax.Locator object for locating the origin of SAX document events.
void	setFlatFileWriter(java.io.Writer flat_file_writer, boolean keep_open) Deprecated. Specifies the java.io.Writer object to which the flat file data will be written.
void	setXflatSchema(org.xml.sax.InputSource xflat_schema_source, boolean suppress_startup_message) Deprecated. Specifies the source of an XFlat schema, which the SaxFlatFileBuilder object will use to validate the SAX document events and convert them into flat file data.
void	startDocument() Deprecated. Receive notification of the start of a document.
void	startElement(java.lang.String element_name, org.xml.sax.AttributeList attribute_list) Deprecated. Receive notification of the start of an element.

Methods inherited from class java.lang.Object

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

Constructor Detail

SaxFlatFileBuilder

public SaxFlatFileBuilder()

Deprecated.

Creates a SaxFlatFileBuilder instance that can be used to convert a stream of SAX 1.0 document events into flat file data.

A SaxFlatFileBuilder instance is reusable. In other words, a SaxFlatFileBuilder object can be used to convert multiple XML documents into flat file data. It is more efficient to use a single SaxFlatFileParser instance to parse multiple flat files than it is to use multiple SaxFlatFileParser instances.

Method Detail

setXflatSchema

public void setXflatSchema(org.xml.sax.InputSource xflat_schema_source,
                           boolean suppress_startup_message)
                    throws org.xml.sax.SAXException

Deprecated.

Specifies the source of an XFlat schema, which the SaxFlatFileBuilder object will use to validate the SAX document events and convert them into flat file data.

The application must call this method before the startDocument() method is called for the first time. The application may also call the setXflatSchema() method between parses, so that a SaxFlatFileBuilder instance can build a variety of flat files that conform to different XFlat schemas.

Once the startDocument() method has been called, the setXflatSchema() method must not be called before the next call to the endDocument() method.

The setXflatSchema() method parses the specified XFlat schema and stores the information in an in-memory data structure, which is not garbage collected until the setXflatSchema() method is called again or until the SaxFlatFileBuilder instance is garbage collected.

If the specified XFlat schema is not a well-formed XML document or if it does not conform to the XFlat language, then this method will throw an org.xml.sax.SAXException, whose message will contain a detailed description of the syntax error, including the following information about the location of the error:

• the system identifier, if available
• the line number
• the column number

The line number of the first line in the schema is one. The column number of the first character in a line is one.

The setXflatSchema() method writes a start up message to standard output unless the suppress_startup_message parameter is set to true.

Parameters:

xflat_schema_source - The org.xml.sax.InputSource object that specifies an XFlat schema.

suppress_startup_message - The setXflatSchema() method will not display the start up message to standard output if this boolean flag is set to true.

Throws:

org.xml.sax.SAXException - if an I/O error occurs while reading the XFlat schema input source or if the XFlat schema is not well-formed or if the XFlat schema does not conform to the XFlat language.

See Also:

InputSource, SAXException, setFlatFileWriter(java.io.Writer, boolean), startDocument(), endDocument()

setFlatFileWriter

public void setFlatFileWriter(java.io.Writer flat_file_writer,
                              boolean keep_open)

Deprecated.

Specifies the java.io.Writer object to which the flat file data will be written.

The application must call this method before the startDocument() method is called for the first time. The application may also call the setFlatFileWriter() method between parses, so that a SaxFlatFileBuilder instance can write each set of flat file data to a different Writer.

The specified flat file writer is not garbage collected until the setFlatFileWriter() method is called again or until the SaxFlatFileBuilder instance is garbage collected.

The keep_open parameter should be set to true if the application will be sending SAX document events for multiple documents to the same flat file writer.

If the keep_open parameter of the setFlatFileWriter() method is set to true, then the SaxFlatFileBuilder instance will not close the flat file writer; however, the SaxFlatFileBuilder.endDocument() method flushes the flat file writer. If the keep_open parameter is set to true and the SaxFlatFileBuilder object aborts the conversion because the stream of document events does not conform to the XFlat schema, then the object will flush the flat file writer before throwing the SAXException.

If the keep_open parameter of the setFlatFileWriter() method is set to false, then the SaxFlatFileBuilder.endDocument() method will close the flat file writer. If the keep_open parameter is set to false and the SaxFlatFileBuilder object aborts the conversion because the stream of document events does not conform to the XFlat schema, then the object will close the flat file writer before throwing the SAXException.

Parameters:

flat_file_writer - The java.io.Writer object to which the flat file data will be written.

keep_open - This parameter should be set to true if the application will be sending SAX document events for multiple documents to the same flat file writer. If set to true, then the SaxFlatFileBuilder instance will flush but not close the flat file writer. If set to false, then the endDocument() method of the SaxFlatFileBuilder instance will close the flat file writer.

See Also:

Writer, setXflatSchema(org.xml.sax.InputSource, boolean), startDocument(), endDocument()

setDocumentLocator

public void setDocumentLocator(org.xml.sax.Locator locator)

Deprecated.

Receive an org.xml.sax.Locator object for locating the origin of SAX document events.

The locator allows the SaxFlatFileBuilder instance to determine the end position of any document-related event, even if the parser is not reporting an error.

If this method is called, it should be called before any of the other methods in the org.xml.sax.DocumentHandler interface.

Specified by:

setDocumentLocator in interface org.xml.sax.DocumentHandler

Parameters:

locator - A locator for SAX document events.

See Also:

Locator

startDocument

public void startDocument()
                   throws org.xml.sax.SAXException

Deprecated.

Receive notification of the start of a document.

The startDocument() method re-initializes the state of the SaxFlatFileBuilder object, so that the SaxFlatFileBuilder class can be reused.

The setXflatSchema() and setFlatFileWriter() methods must be called before the startDocument() method is called for the first time.

Once the startDocument() method has been called, the setXflatSchema() method must not be called before the next call to the endDocument() method.

Specified by:

startDocument in interface org.xml.sax.DocumentHandler

Throws:

org.xml.sax.SAXException - if an XFlat schema was not specified via the setXflatSchema() method or if a flat file writer was not specified via the setFlatFileWriter() method.

See Also:

endDocument()

startElement

public void startElement(java.lang.String element_name,
                         org.xml.sax.AttributeList attribute_list)
                  throws org.xml.sax.SAXException

Deprecated.

Receive notification of the start of an element.

Specified by:

startElement in interface org.xml.sax.DocumentHandler

Parameters:

element_name - The element type name.

attribute_list - A list of the attributes of the element.

Throws:

org.xml.sax.SAXException - if an I/O error occurs while writing to the flat file writer or if the stream of SAX document events does not conform to the XFlat schema.

See Also:

endElement(java.lang.String)

endElement

public void endElement(java.lang.String element_name)
                throws org.xml.sax.SAXException

Deprecated.

Receive notification of the end of an element.

Specified by:

endElement in interface org.xml.sax.DocumentHandler

Parameters:

element_name - The element type name.

Throws:

org.xml.sax.SAXException - if an I/O error occurs while writing to the flat file writer or if the stream of SAX document events does not conform to the XFlat schema.

See Also:

startElement(java.lang.String, org.xml.sax.AttributeList)

endDocument

public void endDocument()
                 throws org.xml.sax.SAXException

Deprecated.

Receive notification of the end of a document.

If the keep_open parameter of the setFlatFileWriter() method was set to true, then the endDocument() method will flush but not close the flat file writer.

If the keep_open parameter of the setFlatFileWriter() method was set to false, then the endDocument() method will close the flat file writer.

Once the startDocument() method has been called, the setXflatSchema() method must not be called before the next call to the endDocument() method.

Specified by:

endDocument in interface org.xml.sax.DocumentHandler

Throws:

org.xml.sax.SAXException - if an I/O error occurs while writing to the flat file writer or if the stream of SAX document events does not conform to the XFlat schema.

See Also:

startDocument()

processingInstruction

public void processingInstruction(java.lang.String target,
                                  java.lang.String data)

Deprecated.

Receive notification of a processing instruction.

This method does nothing.

Specified by:

processingInstruction in interface org.xml.sax.DocumentHandler

Parameters:

target - The processing instruction target.

data - The processing instruction data, or null if none is supplied.

characters

public void characters(char[] chars,
                       int start,
                       int length)
                throws org.xml.sax.SAXException

Deprecated.

Receive notification of character data inside an element.

Specified by:

characters in interface org.xml.sax.DocumentHandler

Parameters:

chars - A character array containing the character data.

start - The start position in the character array.

length - The number of characters to use from the character array.

Throws:

org.xml.sax.SAXException - if an I/O error occurs while writing to the flat file writer or if the stream of SAX document events does not conform to the XFlat schema.

ignorableWhitespace

public void ignorableWhitespace(char[] white_space,
                                int start,
                                int length)

Deprecated.

Receive notification of ignorable whitespace.

This method does nothing.

Specified by:

ignorableWhitespace in interface org.xml.sax.DocumentHandler

Parameters:

white_space - A character array containing the whitespace characters.

start - The start position in the character array.

length - The number of characters to use from the character array.