|
|||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||
java.lang.Object | +--com.unidex.xflat.Sax2FlatFileBuilder
The Sax2FlatFileBuilder class
converts a stream of
SAX 2.0
document events into flat file data, the layout of
which is specified by an XFlat schema.
The Sax2FlatFileBuilder class is an implementation of
the SAX 2.0
org.xml.sax.ContentHandler interface.
Loosely speaking, the Sax2FlatFileBuilder 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 2.0 document events into flat file data. The class
also verifies that the stream of SAX 2.0 document events
conforms to the XFlat schema.
If the stream of SAX 2.0 document events
does not conform to the XFlat schema,
then the conversion is aborted and the Sax2FlatFileBuilder
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 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 Sax2FlatFileBuilder class is reusable.
In other words, a Sax2FlatFileBuilder instance
can be used to convert multiple XML documents. This feature also allows
a Sax2FlatFileBuilder instance to handle an XFlat schema
in which the flat file is mapped
to multiple XML documents. When converting
multiple XML documents using a single
Sax2FlatFileBuilder instance, 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 Sax2FlatFileBuilder class can handle
a stream of SAX 2.0 document events that includes multiple
top-level elements. This feature allows the class
to handle a stream of SAX 2.0 events from an XSLT processor,
the output of which may be an external general parsed entity
rather than a well-formed document.
The XFlat schema of the flat file output must be
specified before the startDocument()
method is invoked for the first time. The XFlat schema may be specified
via the setXflatSchema() method or via
the com.unidex.xflat.schema-file-name-2 system
property. 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 an XFlat schema is specified via
the setXflatSchema() method and another
XFlat schema is specified via
the com.unidex.xflat.schema-file-name-2 system
property, then the XFlat schema that is specified via the
setXflatSchema() method takes precedence
over the XFlat schema specified via the system property.
If the XFlat schema is specified via
the com.unidex.xflat.schema-file-name-2 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-2 system
property and the Sax2FlatFileBuilder
instance is used to process more than one document, then
the instance will examine the schema-file-name-2
and suppress-startup-message
system property before the first document is processed, but the
instance will not examine these system properties before the second
and subsequent documents are processed.
By default, the Sax2FlatFileBuilder writes
the flat file output to standard output. To direct the
flat file output to a java.io.Writer, your application must
invoke the setFlatFileWriter() method before the
first invocation of the startDocument() method.
Alternatively, you can direct the flat file output to a file
by specifying a flat file name via the
com.unidex.xflat.flat-file-name system
property. If the destination of the flat file output is specified via
the setFlatFileWriter() method and another
destination is specified via the
com.unidex.xflat.flat-file-name system
property, then the destination that is specified via the
setFlatFileWriter() method takes precedence
over the destination that is specified via the system property.
If the destination of the flat file output is specified via
the com.unidex.xflat.flat-file-name system
property, then the keep-open flag may be set via the
com.unidex.xflat.keep-open system
property; the valid values for this property are true
and false (the default value is false).
If set to true, then
the Sax2FlatFileBuilder.endDocument() method will
flush but not close the flat file writer.
If set to false, then the endDocument() method
of the Sax2FlatFileBuilder instance will
close the flat file writer.
The keep-open flag should be set to true if multiple
documents will be fed into the SaxFlatFileBuilder
instance. For example, the
Sax2FlatFileParser class could send SAX 2.0 events for
multiple documents to the Sax2FlatFileBuilder instance.
If the destination of the flat file output is specified via
the com.unidex.xflat.flat-file-name system
property and the Sax2FlatFileBuilder
instance is used to process more than one document, then
the instance will examine the flat-file-name
and keep-open
system properties before the first document is processed, but the
instance will not examine these system properties before the second
and subsequent documents are processed.
Once the startDocument() method has been
called, the setXflatSchema() and
setFlatFileWriter() methods must not be
called before the next call to the
endDocument() method.
An application may invoke the setXflatSchema() and
setFlatFileWriter() methods
after an invocation of the endDocument() method,
but before the next invocation of the
startDocument() method.
The following sample application uses the Sax2FlatFileBuilder
class to convert an XML document
(i.e., "file:/c:/invoices.xml") into a flat file
(i.e., "file:/c:/invoices.txt"). The Apache Xerces parser
parses the XML document and generates a stream of
SAX 2.0 document events. The parser passes these events to
an instance of the Sax2FlatFileBuilder, 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.unidex.xflat.Sax2FlatFileBuilder ;
import java.io.FileWriter ;
import org.apache.xerces.parsers.SAXParser ; // The Apache Xerces parser.
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 Sax2FlatFileBuilder.
Sax2FlatFileBuilder builder = new Sax2FlatFileBuilder( ) ;
// Tell the Sax2FlatFileBuilder 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.
SAXParser xml_parser = new SAXParser() ;
// Tell the parser about the Sax2FlatFileBuilder.
xml_parser.setContentHandler( builder ) ;
// Parse the XML doc and convert it to a flat file.
xml_parser.parse( xml_source ) ;
}
}
The Sax2FlatFileBuilder class is thread-safe if the threads
do not share any Sax2FlatFileBuilder instances and if
the Sax2FlatFileBuilder instances do not share any
character streams or byte streams.
Sax2FlatFileParser,
FileWriter,
InputSource,
ContentHandler,
SAXException| Constructor Summary | |
Sax2FlatFileBuilder()
Creates a Sax2FlatFileBuilder instance
that can be used to convert a stream of
SAX 2.0
document events into flat file data. |
|
| Method Summary | |
void |
characters(char[] chars,
int start,
int length)
Receive notification of character data inside an element. |
void |
endDocument()
Receive notification of the end of a document. |
void |
endElement(java.lang.String namespace_uri,
java.lang.String local_name,
java.lang.String qualified_name)
Receive notification of the end of an element. |
void |
endPrefixMapping(java.lang.String prefix)
End the scope of a prefix-URI namespace mapping. |
void |
ignorableWhitespace(char[] white_space,
int start,
int length)
Receive notification of ignorable whitespace. |
void |
processingInstruction(java.lang.String target,
java.lang.String data)
Receive notification of a processing instruction. |
void |
setDocumentLocator(org.xml.sax.Locator locator)
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)
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)
Specifies the source of an XFlat schema, which the Sax2FlatFileBuilder instance will use
to validate the SAX 2.0 document events and convert them into
flat file data. |
void |
skippedEntity(java.lang.String entity_name)
Receive notification of a skipped entity. |
void |
startDocument()
Receive notification of the start of a document. |
void |
startElement(java.lang.String namespace_uri,
java.lang.String local_name,
java.lang.String qualified_name,
org.xml.sax.Attributes attributes)
Receive notification of the start of an element. |
void |
startPrefixMapping(java.lang.String prefix,
java.lang.String uri)
Begin the scope of a prefix-URI namespace mapping. |
| Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Constructor Detail |
public Sax2FlatFileBuilder()
Sax2FlatFileBuilder instance
that can be used to convert a stream of
SAX 2.0
document events into flat file data.
The class verifies that the stream of SAX 2.0 document events conforms to an XFlat schema and converts the stream into flat file data, the format of which is specified by the XFlat schema.
A Sax2FlatFileBuilder instance is reusable.
In other words, a Sax2FlatFileBuilder instance
can be used to convert multiple XML documents into flat file data.
After the Sax2FlatFileBuilder instance processes
the first of the XML documents, your application may specify a
new XFlat schema (via the setXflatSchema() method)
for each subsequent XML document;
if your application does not specify a new XFlat
schema for the next XML document, then the next XML document
will be processed using the most recently specified XFlat schema.
It is more efficient to use a single SaxFlatFileBuilder
instance to build multiple flat files than it
is to use multiple SaxFlatFileBuilder instances.
| Method Detail |
public void setXflatSchema(org.xml.sax.InputSource xflat_schema_source,
boolean suppress_startup_message)
throws org.xml.sax.SAXException
Sax2FlatFileBuilder instance will use
to validate the SAX 2.0 document events and convert them into
flat file data.
The application must specify an XFlat schema (via this method
or via the com.unidex.xflat.schema-file-name-2
system property) before the startDocument() method
is called for the first time.
The application may call the setXflatSchema()
method between parses, so that
a Sax2FlatFileBuilder 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 Sax2FlatFileBuilder 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.
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.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,
setFlatFileWriter(java.io.Writer, boolean),
startDocument(),
endDocument()
public void setFlatFileWriter(java.io.Writer flat_file_writer,
boolean keep_open)
throws org.xml.sax.SAXException
java.io.Writer object to which
the flat file data will be written.
The application may specify the destination of the flat file
output via this method or via the
com.unidex.xflat.flat-file-name system property.
If the application does not specify the destination of the flat file
output, then the flat file output will be written to standard
output.
The application may call the setFlatFileWriter()
method between parses, so that
a Sax2FlatFileBuilder instance can
write each set of flat file data to a different
destination.
The specified flat file writer is not garbage collected until
the setFlatFileWriter() method is called again or until
the Sax2FlatFileBuilder 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 Sax2FlatFileBuilder.endDocument() method will not
close the flat file writer; however, the
Sax2FlatFileBuilder.endDocument()
method will flush the flat file writer. If the keep_open
parameter is set to true and the
Sax2FlatFileBuilder instance aborts the conversion
because the stream of document events does not conform to
the XFlat schema, then the instance 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 Sax2FlatFileBuilder.endDocument()
method will close the flat file writer. If the keep_open
parameter is set to false and the
Sax2FlatFileBuilder instance aborts the conversion
because the stream of document events does not conform to
the XFlat schema, then the instance will close the flat file writer
before throwing the SAXException.
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 Sax2FlatFileBuilder.endDocument() method will
flush but not close the flat file writer.
If set to false,
then the endDocument() method
of the Sax2FlatFileBuilder instance will
close the flat file writer.Writer,
setXflatSchema(org.xml.sax.InputSource, boolean),
startDocument(),
endDocument()public void setDocumentLocator(org.xml.sax.Locator locator)
org.xml.sax.Locator
object for locating the origin of SAX document events.
The locator allows the
Sax2FlatFileBuilder 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.ContentHandler
interface.
setDocumentLocator in interface org.xml.sax.ContentHandlerlocator - A locator for SAX document events.Locator
public void startDocument()
throws org.xml.sax.SAXException
The XFlat schema of the flat file output must be
specified before the startDocument()
method is invoked for the first time.
The XFlat schema may be specified
via the setXflatSchema() method or via
the com.unidex.xflat.schema-file-name-2 system
property.
startDocument in interface org.xml.sax.ContentHandlerorg.xml.sax.SAXException - if an XFlat schema
was not specified.endDocument()
public void startElement(java.lang.String namespace_uri,
java.lang.String local_name,
java.lang.String qualified_name,
org.xml.sax.Attributes attributes)
throws org.xml.sax.SAXException
startElement in interface org.xml.sax.ContentHandlernamespace_uri - The namespace URI, or the empty string if
the element has no namespace URI or if namespace processing
is not being performed.local_name - The local name (without prefix), or the
empty string if namespace processing is not being performed.qualified_name - The qualified name (with prefix), or the
empty string if qualified names are not available.attributes - The attributes of the element. If there are
no attributes, then it should be an empty
Attributes object.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.endElement(java.lang.String, java.lang.String, java.lang.String)
public void endElement(java.lang.String namespace_uri,
java.lang.String local_name,
java.lang.String qualified_name)
throws org.xml.sax.SAXException
endElement in interface org.xml.sax.ContentHandlernamespace_uri - The namespace URI, or the empty string if
the element has no namespace URI or if namespace processing
is not being performed.local_name - The local name (without prefix), or the
empty string if namespace processing is not being performed.qualified_name - The qualified name (with prefix), or the
empty string if qualified names are not available.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.startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)
public void endDocument()
throws org.xml.sax.SAXException
If the keep-open flag was set to
true, then the endDocument() method
will flush but not close the flat file writer.
If the keep-open flag 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.
endDocument in interface org.xml.sax.ContentHandlerorg.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.startDocument()
public void processingInstruction(java.lang.String target,
java.lang.String data)
throws org.xml.sax.SAXException
This method does nothing.
processingInstruction in interface org.xml.sax.ContentHandlertarget - The processing instruction target.data - The processing instruction data, or null if
none is supplied.org.xml.sax.SAXException - never thrown.
public void characters(char[] chars,
int start,
int length)
throws org.xml.sax.SAXException
characters in interface org.xml.sax.ContentHandlerchars - 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.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.
public void ignorableWhitespace(char[] white_space,
int start,
int length)
throws org.xml.sax.SAXException
This method does nothing.
ignorableWhitespace in interface org.xml.sax.ContentHandlerwhite_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.org.xml.sax.SAXException - never thrown.
public void startPrefixMapping(java.lang.String prefix,
java.lang.String uri)
throws org.xml.sax.SAXException
This method throws a SAXException, since XML Convert does not currently support XML namespaces.
startPrefixMapping in interface org.xml.sax.ContentHandlerprefix - The namespace prefix being declared.uri - The namespace URI, to which the prefix is mapped.org.xml.sax.SAXException - always thrown.
public void endPrefixMapping(java.lang.String prefix)
throws org.xml.sax.SAXException
This method throws a SAXException, since XML Convert does not currently support XML namespaces.
endPrefixMapping in interface org.xml.sax.ContentHandlerprefix - The namespace prefix being declared.org.xml.sax.SAXException - always thrown.
public void skippedEntity(java.lang.String entity_name)
throws org.xml.sax.SAXException
This method does nothing.
skippedEntity in interface org.xml.sax.ContentHandlerentity_name - The name of the skipped entity.org.xml.sax.SAXException - never thrown.
|
|||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||
|
Copyright © 1999 - 2002 Unidex, Inc. |