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:

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

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:

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.

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


Table of Contents

Copyright © 1999 - 2002 Unidex, Inc.
All rights reserved.

Unidex Home Page