Javadoc for the XML Convert API: Class SaxFlatFileParser

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.unidex.xflat
Class SaxFlatFileParser

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

All Implemented Interfaces:: org.xml.sax.Locator, org.xml.sax.Parser

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

public class SaxFlatFileParser
extends java.lang.Object
implements org.xml.sax.Parser, org.xml.sax.Locator

The SaxFlatFileParser class converts flat file data into a stream of SAX 1.0 document events.

The SaxFlatFileParser class is an implementation of the SAX 1.0 org.xml.sax.Parser and org.xml.sax.Locator interfaces. In other words, it's a SAX 1.0 driver for the XML Convert flat file parser.

Please note the following about the SaxFlatFileParser class:

the setXflatSchema() method must be invoked before the parse() method is invoked;
the Locator provides information about the record that generated the current document event;
the line number returned by the getLineNumber() method is a record number, which will not be equal to the line number when the records in the flat file data are not lines;
the column number returned by the getColumnNumber() method is a column number within a record;
the only kind of error that is reported is a fatal error;
the setLocale() method always throws a SAXException, since Locales are not supported;
if your application specifies an org.xml.sax.EntityResolver via the setEntityResolver() method, then SaxFlatFileParser will not call the EntityResolver, since this SAX 1.0 feature is not supported;
if your application specifies an org.xml.sax.DTDHandler via the setDTDHandler() method, then SaxFlatFileParser will not call the DTDHandler, since this SAX 1.0 feature is not supported;
the SaxFlatFileParser class will ignore the following XFlat attributes in the XFlat schema: DTD, EncodingName, OmitXmlDeclaration and Standalone;
if your XFlat schema maps the flat file data to multiple XML documents, then the SaxFlatFileParser class will generate a multiple streams of SAX 1.0 document events (i.e., the class will generate multiple start document events).

Note that SAX 1.0 parsers, including SaxFlatFileParser, are reusable but not re-entrant; the application may reuse a SaxFlatFileParser object (possibly with a different input source and/or a different document handler and/or a different XFlat schema) once the first parse has completed successfully, but it may not invoke the parse() methods recursively within a parse.

The following sample application uses the SaxFlatFileParser class to convert a flat file (i.e., "file:/c:/invoices.txt") into a stream of SAX 1.0 document events. These events are handled by an instance of the UserAppDocHandler class, which is an implementation of the org.xml.sax.DocumentHandler interface. The conversion is driven by the XFlat schema (i.e., "file:/c:/invoices.xfl") that is specified via the setXflatSchema() method.

 import com.unidex.xflat.SaxFlatFileParser ;
 import org.xml.sax.InputSource ;
 import org.xml.sax.Parser ;
 
 public class UserApp {
 
   public static void main ( String args[] )
     throws Exception
   {
     // Create the input sources.
     InputSource xflat_schema_source = 
             new InputSource( "file:/c:/invoices.xfl" ) ;
     InputSource flat_file_source = 
             new InputSource( "file:/c:/invoices.txt" ) ;
 
     // Create the SaxFlatFileParser.
     SaxFlatFileParser parser = new SaxFlatFileParser() ;
 
     // Create the SAX document handler.
     UserAppDocHandler handler = new UserAppDocHandler() ;
 
     // Pass the XFlat schema input source to the parser.
     parser.setXflatSchema( xflat_schema_source, true ) ;
     // Pass the document handler to the parser.
     parser.setDocumentHandler( handler ) ;
 
     // Parse the flat file, and convert it to a stream
     // of SAX document events that will be handled by
     // the document handler.
     parser.parse( flat_file_source ) ;
   }
 }

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

See Also:: DocumentHandler, DTDHandler, EntityResolver, InputSource, Locator, Parser, SAXException, SAXParseException

Constructor Summary

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

Method Summary

int getColumnNumber()
          Deprecated. Returns the column number for the current document event.

int getLineNumber()
          Deprecated. Returns the record number for the current document event.

java.lang.String getPublicId()
          Deprecated. Returns the public identifier for the current document event.

java.lang.String getSystemId()
          Deprecated. Returns the system identifier for the current document event.

void parse(org.xml.sax.InputSource flat_file_data_source)
          Deprecated. Parses flat file data and converts the flat file data into a stream of SAX 1.0 document events.

void parse(java.lang.String system_id)
          Deprecated. Same as the previous method, except that the source of the flat file data is specified with a system identifier.

void setDocumentHandler(org.xml.sax.DocumentHandler document_handler)
          Deprecated. Allows an application to register a document event handler.

void setDTDHandler(org.xml.sax.DTDHandler dtd_handler)
          Deprecated. If your application specifies an org.xml.sax.DTDHandler object via the setDTDHandler() method, then SaxFlatFileParser will not call the DTDHandler, since this SAX feature is not supported.

void setEntityResolver(org.xml.sax.EntityResolver entity_resolver)
          Deprecated. If your application specifies an org.xml.sax.EntityResolver object via the setEntityResolver() method, then SaxFlatFileParser will not call the EntityResolver, since this SAX feature is not supported.

void setErrorHandler(org.xml.sax.ErrorHandler error_handler)
          Deprecated. Allows an application to register an error event handler.

void setLocale(java.util.Locale locale)
          Deprecated. If your application calls the setLocale() method to specify a java.util.Locale object, then the method will throw a SAXException, since Locales are not supported.

void setXflatSchema(org.xml.sax.InputSource schema_source, boolean suppress_startup_message)
          Deprecated. Specifies the source of an XFlat schema, which the parse() method will use to parse and validate flat file data.

Methods inherited from class java.lang.Object

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

Constructor Detail

SaxFlatFileParser

public SaxFlatFileParser()

Deprecated.

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

A SaxFlatFileParser instance can be used to parse multiple flat files that conform to different XFlat schemas. 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 schema_source,
                           boolean suppress_startup_message)
                    throws org.xml.sax.SAXException

Deprecated.

Specifies the source of an XFlat schema, which the parse() method will use to parse and validate flat file data.

The application must call this method before it calls the parse() method for the first time. The application may also call the setXflatSchema() method between parses, so that a SaxFlatFileParser instance can parse a variety of flat files that conform to different XFlat schemas.

If the setXflatSchema() method is called in the middle of a parse, the current parse will continue to use the previously specified XFlat schema; once the current parse has completed, the next parse (if any) will use the new XFlat schema.

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 SaxFlatFileParser 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:: 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

setEntityResolver

public void setEntityResolver(org.xml.sax.EntityResolver entity_resolver)

Deprecated.

If your application specifies an org.xml.sax.EntityResolver object via the setEntityResolver() method, then SaxFlatFileParser will not call the EntityResolver, since this SAX feature is not supported.

Specified by:: setEntityResolver in interface org.xml.sax.Parser

Parameters:: entity_resolver - The org.xml.sax.EntityResolver object for resolving entities.
See Also:: EntityResolver

setDocumentHandler

public void setDocumentHandler(org.xml.sax.DocumentHandler document_handler)

Deprecated.

Allows an application to register a document event handler.

Specified by:: setDocumentHandler in interface org.xml.sax.Parser

Parameters:: document_handler - The org.xml.sax.DocumentHandler object for handling document events.
See Also:: DocumentHandler

setDTDHandler

public void setDTDHandler(org.xml.sax.DTDHandler dtd_handler)

Deprecated.

If your application specifies an org.xml.sax.DTDHandler object via the setDTDHandler() method, then SaxFlatFileParser will not call the DTDHandler, since this SAX feature is not supported.

Specified by:: setDTDHandler in interface org.xml.sax.Parser

Parameters:: dtd_handler - The org.xml.sax.DTDHandler object for handling DTD events.
See Also:: DTDHandler

setErrorHandler

public void setErrorHandler(org.xml.sax.ErrorHandler error_handler)

Deprecated.

Allows an application to register an error event handler. This method is supported, but only fatal errors will be passed to the specified org.xml.sax.ErrorHandler object.

Specified by:: setErrorHandler in interface org.xml.sax.Parser

Parameters:: error_handler - The org.xml.sax.ErrorHandler object for handling errors.
See Also:: ErrorHandler

setLocale

public void setLocale(java.util.Locale locale)
               throws org.xml.sax.SAXException

Deprecated.

If your application calls the setLocale() method to specify a java.util.Locale object, then the method will throw a SAXException, since Locales are not supported.

Specified by:: setLocale in interface org.xml.sax.Parser

Parameters:: locale - The java.util.Locale object, which specifies the locale for errors and warnings.
Throws:: org.xml.sax.SAXException - whenever this method is called.
See Also:: SAXException, Locale

parse

public void parse(org.xml.sax.InputSource flat_file_data_source)
           throws org.xml.sax.SAXException,
                  java.io.IOException

Deprecated.

Parses flat file data and converts the flat file data into a stream of SAX 1.0 document events. The parse() method validates the flat file data against the current XFlat schema.

The application must call the setXflatSchema() method before it calls the parse() method for the first time. The application may also call the setXflatSchema() method between parses, so that a SaxFlatFileParser instance can parse a variety of flat files that conform to different XFlat schemas.

When the parse() completes, the input source is closed.

If the flat file data does not conform to the XFlat schema, then the conversion is aborted and the parse() method 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, if available
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.

Specified by:: parse in interface org.xml.sax.Parser

Parameters:: flat_file_data_source - The org.xml.sax.InputSource object for the flat file data to be parsed.
Throws:: org.xml.sax.SAXException - if the flat file data does not conform to the XFlat schema.; java.io.IOException - if an I/O error occurs while reading the flat file data input source.
See Also:: InputSource, SAXException, IOException

parse

public void parse(java.lang.String system_id)
           throws org.xml.sax.SAXException,
                  java.io.IOException

Deprecated.

Same as the previous method, except that the source of the flat file data is specified with a system identifier.

Specified by:: parse in interface org.xml.sax.Parser

Parameters:: system_id - The system identifier for the flat file data to be parsed.
Throws:: org.xml.sax.SAXException - if the flat file data does not conform to the XFlat schema.; java.io.IOException - if an I/O error occurs while reading the flat file data.
See Also:: SAXException, IOException

getPublicId

public java.lang.String getPublicId()

Deprecated.

Returns the public identifier for the current document event.

Specified by:: getPublicId in interface org.xml.sax.Locator

Returns:: A string containing the public identifier, or null if none is available.
See Also:: Locator, getSystemId()

getSystemId

public java.lang.String getSystemId()

Deprecated.

Returns the system identifier for the current document event.

Specified by:: getSystemId in interface org.xml.sax.Locator

Returns:: A string containing the system identifier, or null if none is available.
See Also:: Locator, getPublicId()

getLineNumber

public int getLineNumber()

Deprecated.

Returns the record number for the current document event. If there is a one-to-one correspondence between records and lines in the flat file data, then the record number will be the same as the line number. The record number of the first record in the flat file data is one.

Specified by:: getLineNumber in interface org.xml.sax.Locator

Returns:: The line number, or -1 if none is available.
See Also:: Locator, getColumnNumber()

getColumnNumber

public int getColumnNumber()

Deprecated.

Returns the column number for the current document event. The column number is an offset within the record associated with the current document event.

Specified by:: getColumnNumber in interface org.xml.sax.Locator

Returns:: The column number, or -1 if none is available.
See Also:: Locator, getLineNumber()

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Table of Contents

Unidex Home Page

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

Method Summary
`int`	`getColumnNumber()` Deprecated. Returns the column number for the current document event.
`int`	`getLineNumber()` Deprecated. Returns the record number for the current document event.
`java.lang.String`	`getPublicId()` Deprecated. Returns the public identifier for the current document event.
`java.lang.String`	`getSystemId()` Deprecated. Returns the system identifier for the current document event.
`void`	`parse(org.xml.sax.InputSource flat_file_data_source)` Deprecated. Parses flat file data and converts the flat file data into a stream of SAX 1.0 document events.
`void`	`parse(java.lang.String system_id)` Deprecated. Same as the previous method, except that the source of the flat file data is specified with a system identifier.
`void`	`setDocumentHandler(org.xml.sax.DocumentHandler document_handler)` Deprecated. Allows an application to register a document event handler.
`void`	`setDTDHandler(org.xml.sax.DTDHandler dtd_handler)` Deprecated. If your application specifies an `org.xml.sax.DTDHandler` object via the `setDTDHandler()` method, then `SaxFlatFileParser` will not call the `DTDHandler`, since this SAX feature is not supported.
`void`	`setEntityResolver(org.xml.sax.EntityResolver entity_resolver)` Deprecated. If your application specifies an `org.xml.sax.EntityResolver` object via the `setEntityResolver()` method, then `SaxFlatFileParser` will not call the `EntityResolver`, since this SAX feature is not supported.
`void`	`setErrorHandler(org.xml.sax.ErrorHandler error_handler)` Deprecated. Allows an application to register an error event handler.
`void`	`setLocale(java.util.Locale locale)` Deprecated. If your application calls the `setLocale()` method to specify a `java.util.Locale` object, then the method will throw a `SAXException`, since Locales are not supported.
`void`	`setXflatSchema(org.xml.sax.InputSource schema_source, boolean suppress_startup_message)` Deprecated. Specifies the source of an XFlat schema, which the `parse()` method will use to parse and validate flat file data.

com.unidex.xflat Class SaxFlatFileParser

SaxFlatFileParser

setXflatSchema

setEntityResolver

setDocumentHandler

setDTDHandler

setErrorHandler

setLocale

parse

parse

getPublicId

getSystemId

getLineNumber

getColumnNumber

com.unidex.xflat
Class SaxFlatFileParser