|
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--com.unidex.xflat.Sax2FlatFileParser
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:
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;
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;
Locator
, which the Sax2FlatFileParser
class provides to the ContentHandler
via the
setDocumentLocator()
method,
provides information about the record that generated
the current document event;
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;
Locator.getColumnNumber()
method is a column number within a record;
setLocale()
method always throws a
SAXException
, since Locales are not supported;
org.xml.sax.EntityResolver
via the setEntityResolver()
method,
then Sax2FlatFileParser
will not call the
EntityResolver
, since this
SAX 2.0 feature is not supported;
org.xml.sax.DTDHandler
via the setDTDHandler()
method,
then Sax2FlatFileParser
will not call the
DTDHandler
, since this SAX 2.0 feature is not supported;
Sax2FlatFileParser
class will ignore
the following XFlat attributes in the XFlat schema: DTD
,
EncodingName
, OmitXmlDeclaration
and
Standalone
;
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.
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 |
public Sax2FlatFileParser()
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 |
public void setXflatSchema(org.xml.sax.InputSource schema_source, boolean suppress_startup_message) throws org.xml.sax.SAXException
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
.
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
.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.InputSource
,
SAXException
public void setFeature(java.lang.String name, boolean state) throws org.xml.sax.SAXNotRecognizedException, org.xml.sax.SAXNotSupportedException
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).
setFeature
in interface org.xml.sax.XMLReader
name
- The feature name, as a complete URI.state
- The new state for the feature.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.getFeature(java.lang.String)
,
XMLReader.setFeature(java.lang.String, boolean)
public boolean getFeature(java.lang.String name) throws org.xml.sax.SAXNotRecognizedException, org.xml.sax.SAXNotSupportedException
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.
getFeature
in interface org.xml.sax.XMLReader
name
- The feature name, as a complete URI.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.setFeature(java.lang.String, boolean)
,
XMLReader.getFeature(java.lang.String)
public void setProperty(java.lang.String name, java.lang.Object value) throws org.xml.sax.SAXNotRecognizedException, org.xml.sax.SAXNotSupportedException
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.
setProperty
in interface org.xml.sax.XMLReader
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
).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.setXflatSchema(org.xml.sax.InputSource, boolean)
,
setFeature(java.lang.String, boolean)
,
getProperty(java.lang.String)
,
XMLReader.setProperty(java.lang.String, java.lang.Object)
public java.lang.Object getProperty(java.lang.String name) throws org.xml.sax.SAXNotRecognizedException, org.xml.sax.SAXNotSupportedException
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.
getProperty
in interface org.xml.sax.XMLReader
name
- The property name.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
).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.setProperty(java.lang.String, java.lang.Object)
,
XMLReader.getProperty(java.lang.String)
public void setEntityResolver(org.xml.sax.EntityResolver 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.
setEntityResolver
in interface org.xml.sax.XMLReader
entity_resolver
- The org.xml.sax.EntityResolver object for
resolving entities.getEntityResolver()
,
XMLReader.setEntityResolver(org.xml.sax.EntityResolver)
,
EntityResolver
public org.xml.sax.EntityResolver getEntityResolver()
getEntityResolver
in interface org.xml.sax.XMLReader
null
if none was supplied.setEntityResolver(org.xml.sax.EntityResolver)
,
XMLReader.getEntityResolver()
,
EntityResolver
public void setDTDHandler(org.xml.sax.DTDHandler 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.
setDTDHandler
in interface org.xml.sax.XMLReader
dtd_handler
- The org.xml.sax.DTDHandler object for
handling DTD events.getDTDHandler()
,
XMLReader.setDTDHandler(org.xml.sax.DTDHandler)
,
DTDHandler
public org.xml.sax.DTDHandler getDTDHandler()
getDTDHandler
in interface org.xml.sax.XMLReader
null
if none was supplied.setDTDHandler(org.xml.sax.DTDHandler)
,
XMLReader.getDTDHandler()
,
DTDHandler
public void setContentHandler(org.xml.sax.ContentHandler content_handler)
setContentHandler
in interface org.xml.sax.XMLReader
content_handler
- The new content handler.getContentHandler()
,
XMLReader.setContentHandler(org.xml.sax.ContentHandler)
,
ContentHandler
public org.xml.sax.ContentHandler getContentHandler()
getContentHandler
in interface org.xml.sax.XMLReader
null
if none was supplied.setContentHandler(org.xml.sax.ContentHandler)
,
XMLReader.getContentHandler()
,
ContentHandler
public void setErrorHandler(org.xml.sax.ErrorHandler 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.
setErrorHandler
in interface org.xml.sax.XMLReader
error_handler
- The new error handler.getErrorHandler()
,
XMLReader.setErrorHandler(org.xml.sax.ErrorHandler)
,
ErrorHandler
public org.xml.sax.ErrorHandler getErrorHandler()
getErrorHandler
in interface org.xml.sax.XMLReader
null
if none was supplied.setErrorHandler(org.xml.sax.ErrorHandler)
,
XMLReader.getErrorHandler()
,
ErrorHandler
public void parse(java.lang.String system_id) throws java.io.IOException, org.xml.sax.SAXException
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.
parse
in interface org.xml.sax.XMLReader
system_id
- The absolute URL of the document containing the
non-XML flat file data.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.parse(org.xml.sax.InputSource)
,
XMLReader.parse(java.lang.String)
,
SAXException
,
IOException
public void parse(org.xml.sax.InputSource flat_file_data_source) throws java.io.IOException, org.xml.sax.SAXException
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
.
parse
in interface org.xml.sax.XMLReader
flat_file_data_source
- The org.xml.sax.InputSource object for
the flat file data to be parsed.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.parse(java.lang.String)
,
XMLReader.parse(org.xml.sax.InputSource)
,
InputSource
,
SAXException
,
IOException
|
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright © 1999 - 2002 Unidex, Inc. |