Javadoc for the XML Convert API: Class Sax2FlatFileParser

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 Sax2FlatFileParser

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

All Implemented Interfaces:: org.xml.sax.XMLReader

public class Sax2FlatFileParser
extends java.lang.Object
implements org.xml.sax.XMLReader

The Sax2FlatFileParser class converts flat file data into a stream of SAX 2.0 document events.

The Sax2FlatFileParser class is an implementation of the SAX 2.0 org.xml.sax.XMLReader interface. In other words, it's a SAX 2.0 driver for the XML Convert flat file parser.

Please note the following about the Sax2FlatFileParser class:

before the parse() method is invoked for the first time, an XFlat schema must be specified via the setXflatSchema() method or the setProperty() method or the com.unidex.xflat.schema-file-name system property;
if an Sax2FlatFileParser instance is used to parse multiple flat files and an XFlat schema is specified before the first invocation of the parse() method, but not after the the first invocation of parse(), then the instance will use the same XFlat schema to parse all the flat files and the XFlat schema will be read and parsed only once;
the Locator, which the Sax2FlatFileParser class provides to the ContentHandler via the setDocumentLocator() method, provides information about the record that generated the current document event;
the line number returned by the Locator.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 Locator.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 Sax2FlatFileParser will not call the EntityResolver, since this SAX 2.0 feature is not supported;
if your application specifies an org.xml.sax.DTDHandler via the setDTDHandler() method, then Sax2FlatFileParser will not call the DTDHandler, since this SAX 2.0 feature is not supported;
the Sax2FlatFileParser 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 Sax2FlatFileParser class will generate a multiple streams of SAX 2.0 document events (i.e., the class will generate multiple start document events).

Note that SAX 2.0 XML readers, including Sax2FlatFileParser, are reusable but not re-entrant; the application may reuse a Sax2FlatFileParser instance (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 XFlat schema of the flat file input must be specified before the parse() method is invoked for the first time. The XFlat schema may be specified via the setXflatSchema() method or via the setProperty() method or via the com.unidex.xflat.schema-file-name system property. The Sax2FlatFileParser instance will examine the com.unidex.xflat.schema-file-name system property only if an XFlat schema has not been specified via the setXflatSchema() method or the setProperty() method. The system property can be set at the command line when invoking the Java Virtual Machine. Alternatively, your application can set the system property via the java.lang.System.setProperty() method.

If the XFlat schema is specified via the com.unidex.xflat.schema-file-name system property, then the suppress-startup-message flag may be set via the com.unidex.xflat.suppress-startup-message system property; the value values for this property are true and false (the default value is false).

If the XFlat schema is specified via the com.unidex.xflat.schema-file-name system property and the Sax2FlatFileParser instance is used to process more than one flat file, then the instance will examine the schema-file-name and suppress-startup-message system property before the first flat file is processed, but the instance will not examine these system properties before the second and subsequent flat files are processed.

The following sample application uses the Sax2FlatFileParser class to convert a flat file (i.e., "file:/c:/invoices.txt") into a stream of SAX 2.0 document events. These events are handled by an instance of the UserAppContentHandler class, which is an implementation of the org.xml.sax.ContentHandler 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.Sax2FlatFileParser ;
 import org.xml.sax.InputSource ;
 
 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 Sax2FlatFileParser.
     Sax2FlatFileParser parser = new Sax2FlatFileParser() ;
 
     // Create the SAX 2.0 content handler.
     UserAppContentHandler handler = new UserAppContentHandler() ;
 
     // Pass the XFlat schema input source to the parser.
     boolean suppress_startup_message = true ;
     parser.setXflatSchema( xflat_schema_source, suppress_startup_message ) ;
     // Pass the content handler to the parser.
     parser.setContentHandler( handler ) ;
 
     // Parse the flat file, and convert it to a stream
     // of SAX 2.0 document events that will be handled by
     // the content handler.
     parser.parse( flat_file_source ) ;
   }
 }

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

See Also:: Sax2FlatFileBuilder, ContentHandler, DTDHandler, EntityResolver, InputSource, Locator, XMLReader, SAXException, SAXParseException

Constructor Summary

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

Method Summary

org.xml.sax.ContentHandler getContentHandler()
          Return the current content handler.

org.xml.sax.DTDHandler getDTDHandler()
          Return the current DTD handler.

org.xml.sax.EntityResolver getEntityResolver()
          Return the current entity resolver.

org.xml.sax.ErrorHandler getErrorHandler()
          Return the current error handler.

boolean getFeature(java.lang.String name)
          Check a parser feature.

java.lang.Object getProperty(java.lang.String name)
          Get the value of a parser property.

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

void parse(java.lang.String system_id)
          Parses the flat file data and converts it into a stream of SAX 2.0 document events.

void setContentHandler(org.xml.sax.ContentHandler content_handler)
          Allow an application to register a content handler.

void setDTDHandler(org.xml.sax.DTDHandler dtd_handler)
          Allow an application to register a DTD handler.

void setEntityResolver(org.xml.sax.EntityResolver entity_resolver)
          Allow an application to register an entity resolver.

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

void setFeature(java.lang.String name, boolean state)
          Set a feature for the parser.

void setProperty(java.lang.String name, java.lang.Object value)
          Set a parser property.

void setXflatSchema(org.xml.sax.InputSource schema_source, boolean suppress_startup_message)
          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

Sax2FlatFileParser

public Sax2FlatFileParser()

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

A Sax2FlatFileParser instance can be used to parse multiple flat files.

Method Detail

setXflatSchema

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

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

The application must specify an XFlat schema (via this method or the setProperty() method or the com.unidex.xflat.schema-file-name system property) before it calls the parse() method for the first time.

The application may also call the setXflatSchema() method between parses, so that a Sax2FlatFileParser instance can parse a variety of flat files that conform to different XFlat schemas.

The setXflatSchema() method must not be called in the middle of a parse.

If the application specifies an XFlat schema via the com.unidex.xflat.schema-file-name system property and also calls the setXflatSchema() method to specify an XFlat schema, then the Sax2FlatFileParser instance will use the XFlat schema that was specified via the setXflatSchema() method.

If the application invokes the setProperty() method and/or the setXflatSchema() method multiple times, then the Sax2FlatFileParser instance will use the XFlat schema that was specified most recently.

The setXflatSchema() method parses the specified XFlat schema and stores the information in an in-memory data structure, which is not garbage collected until a new XFlat schema is specified (via the setXflatSchema() method or the setProperty() method) or until the Sax2FlatFileParser 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 source.; 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

setFeature

public void setFeature(java.lang.String name,
                       boolean state)
                throws org.xml.sax.SAXNotRecognizedException,
                       org.xml.sax.SAXNotSupportedException

Set a feature for the parser.

The only features supported are the following:

http://xml.org/sax/features/namespaces
http://xml.org/sax/features/namespace-prefixes
http://unidex.com/xflat/features/suppress-startup-message

In general, it's not necessary to set the namespaces and namespace-prefixes features, since XML Convert does not support XML namespaces.

If the application calls setFeature to set the state of the suppress-startup-message feature and calls setProperty to set the schema-file-name property, then the suppress-startup-message feature should be set before the schema-file-name property is set.

These features can not be set during a parse (i.e., while the parse() method is executing).

Specified by:: setFeature in interface org.xml.sax.XMLReader

Parameters:: name - The feature name, as a complete URI.; state - The new state for the feature.
Throws:: org.xml.sax.SAXNotRecognizedException - if the feature name is not recognized.; org.xml.sax.SAXNotSupportedException - if the application attempts to set a recognized feature during a parse.
See Also:: getFeature(java.lang.String), XMLReader.setFeature(java.lang.String, boolean)

getFeature

public boolean getFeature(java.lang.String name)
                   throws org.xml.sax.SAXNotRecognizedException,
                          org.xml.sax.SAXNotSupportedException

Check a parser feature.

The only features supported are the following:

http://xml.org/sax/features/namespaces
http://xml.org/sax/features/namespace-prefixes
http://unidex.com/xflat/features/suppress-startup-message

These features can be queried at any time.

Specified by:: getFeature in interface org.xml.sax.XMLReader

Parameters:: name - The feature name, as a complete URI.
Returns:: The current feature state.
Throws:: org.xml.sax.SAXNotRecognizedException - if the feature name is not recognized.; org.xml.sax.SAXNotSupportedException - if the feature name is recognized, but the value can not be determined at this time.
See Also:: setFeature(java.lang.String, boolean), XMLReader.getFeature(java.lang.String)

setProperty

public void setProperty(java.lang.String name,
                        java.lang.Object value)
                 throws org.xml.sax.SAXNotRecognizedException,
                        org.xml.sax.SAXNotSupportedException

Set a parser property.

The following is the only supported property:

   http://unidex.com/xflat/properties/schema-file-name

The value of this property is the name of the XFlat schema file, and must be specified as a string (i.e., as an instance of java.lang.String). The value of this property can not be set during a parse.

The application must specify an XFlat schema (via this method or the setXflatSchema() method or the com.unidex.xflat.schema-file-name system property) before it calls the parse() method for the first time. The parse() method will use the specified XFlat schema to parse and validate flat file data.

The application may call the setProperty() method between parses, so that a Sax2FlatFileParser instance can parse a variety of flat files that conform to different XFlat schemas.

The setProperty() method must not be called in the middle of a parse.

If the application specifies an XFlat schema via the com.unidex.xflat.schema-file-name system property and also calls the setProperty() method to specify an XFlat schema, then the Sax2FlatFileParser instance will use the XFlat schema that was specified via the setProperty() method.

The setProperty() method parses the specified XFlat schema and stores the information in an in-memory data structure, which is not garbage collected until a new XFlat schema is specified (via the setXflatSchema() method or the setProperty() method) or until the Sax2FlatFileParser 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.SAXNotSupportedException, 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 setProperty() method writes a start up message to standard output unless the http://unidex.com/xflat/features/suppress-startup-message feature has been set to true via the setFeature() method.

Specified by:: setProperty in interface org.xml.sax.XMLReader

Parameters:: name - The property name, which must be http://unidex.com/xflat/properties/schema-file-name.; value - The property value, which is the name of an XFlat schema file. The value must be specified as a string (i.e., as an instance of java.lang.String).
Throws:: org.xml.sax.SAXNotRecognizedException - if the property name is not recognized.; org.xml.sax.SAXNotSupportedException - if an I/O error occurs while reading the specified XFlat schema or if the XFlat schema is not well-formed or if the XFlat schema does not conform to the XFlat language.
See Also:: setXflatSchema(org.xml.sax.InputSource, boolean), setFeature(java.lang.String, boolean), getProperty(java.lang.String), XMLReader.setProperty(java.lang.String, java.lang.Object)

getProperty

public java.lang.Object getProperty(java.lang.String name)
                             throws org.xml.sax.SAXNotRecognizedException,
                                    org.xml.sax.SAXNotSupportedException

Get the value of a parser property.

The only property supported is:

   http://unidex.com/xflat/properties/schema-file-name

The value of this property is the name of the XFlat schema file that was specified by the most recent invocation of the setProperty() method. If the setProperty() method has not been invoked, then the value of this property is null.

The value of this property can be queried at any time.

Specified by:: getProperty in interface org.xml.sax.XMLReader

Parameters:: name - The property name.
Returns:: The property value. If an XFlat schema file name has not been specified via setProperty, then null is returned. If an XFlat schema file name has been specified via setProperty, then the file name is returned as a string (i.e., as an instance of java.lang.String).
Throws:: org.xml.sax.SAXNotRecognizedException - if the property name is not recognized.; org.xml.sax.SAXNotSupportedException - if the property name is recognized, but the value can not be determined at this time.
See Also:: setProperty(java.lang.String, java.lang.Object), XMLReader.getProperty(java.lang.String)

setEntityResolver

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

Allow an application to register an entity resolver.

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

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

Parameters:: entity_resolver - The org.xml.sax.EntityResolver object for resolving entities.
See Also:: getEntityResolver(), XMLReader.setEntityResolver(org.xml.sax.EntityResolver), EntityResolver

getEntityResolver

public org.xml.sax.EntityResolver getEntityResolver()

Return the current entity resolver.

Specified by:: getEntityResolver in interface org.xml.sax.XMLReader

Returns:: The current entity resolver, or null if none was supplied.
See Also:: setEntityResolver(org.xml.sax.EntityResolver), XMLReader.getEntityResolver(), EntityResolver

setDTDHandler

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

Allow an application to register a DTD handler.

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

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

Parameters:: dtd_handler - The org.xml.sax.DTDHandler object for handling DTD events.
See Also:: getDTDHandler(), XMLReader.setDTDHandler(org.xml.sax.DTDHandler), DTDHandler

getDTDHandler

public org.xml.sax.DTDHandler getDTDHandler()

Return the current DTD handler.

Specified by:: getDTDHandler in interface org.xml.sax.XMLReader

Returns:: The current DTD handler, or null if none was supplied.
See Also:: setDTDHandler(org.xml.sax.DTDHandler), XMLReader.getDTDHandler(), DTDHandler

setContentHandler

public void setContentHandler(org.xml.sax.ContentHandler content_handler)

Allow an application to register a content handler.

Specified by:: setContentHandler in interface org.xml.sax.XMLReader

Parameters:: content_handler - The new content handler.
See Also:: getContentHandler(), XMLReader.setContentHandler(org.xml.sax.ContentHandler), ContentHandler

getContentHandler

public org.xml.sax.ContentHandler getContentHandler()

Return the current content handler.

Specified by:: getContentHandler in interface org.xml.sax.XMLReader

Returns:: The current content handler, or null if none was supplied.
See Also:: setContentHandler(org.xml.sax.ContentHandler), XMLReader.getContentHandler(), ContentHandler

setErrorHandler

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

Allow an application to register an error handler.

Set the error 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.XMLReader

Parameters:: error_handler - The new error handler.
See Also:: getErrorHandler(), XMLReader.setErrorHandler(org.xml.sax.ErrorHandler), ErrorHandler

getErrorHandler

public org.xml.sax.ErrorHandler getErrorHandler()

Return the current error handler.

Specified by:: getErrorHandler in interface org.xml.sax.XMLReader

Returns:: The current error handler, or null if none was supplied.
See Also:: setErrorHandler(org.xml.sax.ErrorHandler), XMLReader.getErrorHandler(), ErrorHandler

parse

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

Parses the flat file data and converts it into a stream of SAX 2.0 document events.

The parse() method validates the flat file data against the current XFlat schema and converts it into a stream of SAX 2.0 document events. The application must specify an XFlat schema (via the setXflatSchema() method or the setProperty() method or the com.unidex.xflat.schema-file-name system property) before it calls the parse() method for the first time. The application may also specify a new XFlat schema between parses (via the setXflatSchema() method or the setProperty() method), so that a Sax2FlatFileParser 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.XMLReader

Parameters:: system_id - The absolute URL of the document containing the non-XML flat file data.
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:: parse(org.xml.sax.InputSource), XMLReader.parse(java.lang.String), SAXException, IOException

parse

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

Parses the flat file data and converts it into a stream of SAX 2.0 document events.

Same as the parse(java.lang.String) method, except that the source of the flat file data is specified as an instance of org.xml.sax.InputSource.

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

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.
See Also:: parse(java.lang.String), XMLReader.parse(org.xml.sax.InputSource), InputSource, SAXException, IOException

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
`Sax2FlatFileParser()` Creates a `Sax2FlatFileParser` instance that can be used to convert flat file data into a stream of SAX 2.0 document events.

Method Summary
`org.xml.sax.ContentHandler`	`getContentHandler()` Return the current content handler.
`org.xml.sax.DTDHandler`	`getDTDHandler()` Return the current DTD handler.
`org.xml.sax.EntityResolver`	`getEntityResolver()` Return the current entity resolver.
`org.xml.sax.ErrorHandler`	`getErrorHandler()` Return the current error handler.
`boolean`	`getFeature(java.lang.String name)` Check a parser feature.
`java.lang.Object`	`getProperty(java.lang.String name)` Get the value of a parser property.
`void`	`parse(org.xml.sax.InputSource flat_file_data_source)` Parses the flat file data and converts it into a stream of SAX 2.0 document events.
`void`	`parse(java.lang.String system_id)` Parses the flat file data and converts it into a stream of SAX 2.0 document events.
`void`	`setContentHandler(org.xml.sax.ContentHandler content_handler)` Allow an application to register a content handler.
`void`	`setDTDHandler(org.xml.sax.DTDHandler dtd_handler)` Allow an application to register a DTD handler.
`void`	`setEntityResolver(org.xml.sax.EntityResolver entity_resolver)` Allow an application to register an entity resolver.
`void`	`setErrorHandler(org.xml.sax.ErrorHandler error_handler)` Allow an application to register an error handler.
`void`	`setFeature(java.lang.String name, boolean state)` Set a feature for the parser.
`void`	`setProperty(java.lang.String name, java.lang.Object value)` Set a parser property.
`void`	`setXflatSchema(org.xml.sax.InputSource schema_source, boolean suppress_startup_message)` Specifies the source of an XFlat schema, which the `parse()` method will use to parse and validate flat file data.

com.unidex.xflat Class Sax2FlatFileParser

Sax2FlatFileParser

setXflatSchema

setFeature

getFeature

setProperty

getProperty

setEntityResolver

getEntityResolver

setDTDHandler

getDTDHandler

setContentHandler

getContentHandler

setErrorHandler

getErrorHandler

parse

parse

com.unidex.xflat
Class Sax2FlatFileParser