org.greybird.xmliter
Class XercesSaxEventSource

java.lang.Object
  |
  +--org.greybird.xmliter.XercesSaxEventSource

All Implemented Interfaces:

SaxEventSource

public class XercesSaxEventSource

extends java.lang.Object

implements SaxEventSource

A SaxEventSource for incremental parsers using the Xerces Native Interface.

The Xerces Native Interface provides incremental or pull-parsing. Its XMLPullParserConfiguration interface is used by this class to implement the SaxEventSource interface. This allows using a SaxIterator with the Xerces pull-parser.

If you used the XercesSaxEventSource(InputSource) constructor, the standard Xerces parser configuration will be used to create a parser. This is the simplest way to create a XercesSaxEventSource, and is used automatically by SaxIterator.SaxIterator(InputSource) if the Xerces pull-parser is available. You can also call isAvailable() to determine for yourself whether the required Xerces libraries are in the classpath and this technique will work.

 import org.greybird.xmliter.SaxEventSource;
 import org.greybird.xmliter.SaxIterator;
 import org.greybird.xmliter.XmlIterator;
 import org.greybird.xmliter.XercesSaxEventSource;
 import org.xml.sax.InputSource;
 ...
 //
 // Create a XercesSaxEventSource from a SAX InputSource.
 //
 InputSource input = new InputSource(...);
 SaxEventSource eventSource = new XercesSaxEventSource(input);
 //
 // Create a SaxIterator from a XercesSaxEventSource
 //
 XmlIterator iter = new SaxIterator(eventSource);
 while (iter.advance()) { ...
 

If you need more control over the parser configuration, or you would like to reuse an existing configuration for performance reasons, you can use the XercesSaxEventSource(InputSource, XMLPullParserConfiguration) instead. This allows specifying a Xerces parser configuration of your choice.

 import org.apache.xerces.parsers.StandardParserConfiguration;
 import org.greybird.xmliter.SaxEventSource;
 import org.greybird.xmliter.SaxIterator;
 import org.greybird.xmliter.XmlIterator;
 import org.greybird.xmliter.XercesSaxEventSource;
 import org.xml.sax.InputSource;
 ...
 //
 // Create a XercesSaxEventSource from a SAX InputSource and Xerces
 // pull-parser.
 //
 InputSource input = new InputSource(...);
 StandardParserConfiguration parser = new StandardParserConfiguration();
 SaxEventSource eventSource = new XercesSaxEventSource(input, parser);
 //
 // Create a SaxIterator from a XercesSaxEventSource
 //
 XmlIterator iter = new SaxIterator(eventSource);
 while (iter.advance()) { ...
 

Fields inherited from interface org.greybird.xmliter.SaxEventSource

NAMESPACES_FEATURE

Constructor Summary

XercesSaxEventSource(org.xml.sax.InputSource inputSource)
Creates a Xerces SAX event source using the standard parser configuration class.

XercesSaxEventSource(org.xml.sax.InputSource inputSource, org.apache.xerces.xni.parser.XMLPullParserConfiguration xniParser)
Creates a Xerces SAX event source using the a given parser configuration class.

Method Summary

void	close(boolean completeParsing) Closes the event source to free up resources and stops generating events.
boolean	generateEvents() Generates a subset of SAX events and returns true if more events are still available.
static boolean	isAvailable() Returns whether the standard configuration implementation of the Xerces Native Interface pull-parser is available.
void	setContentHandler(org.xml.sax.ContentHandler contentHandler) Sets the content handler to receive SAX events.

Methods inherited from class java.lang.Object

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

Constructor Detail

XercesSaxEventSource

public XercesSaxEventSource(org.xml.sax.InputSource inputSource)
                     throws java.io.IOException,
                            org.xml.sax.SAXException,
                            org.apache.xerces.xni.XNIException

Creates a Xerces SAX event source using the standard parser configuration class.

A new instance of the org.apache.xerces.parsers.StandardParserConfiguration class will be used as the parser configuration.

Parameters:

inputSource - is the input document to be parsed.

XercesSaxEventSource

public XercesSaxEventSource(org.xml.sax.InputSource inputSource,
                            org.apache.xerces.xni.parser.XMLPullParserConfiguration xniParser)
                     throws java.io.IOException,
                            org.xml.sax.SAXException,
                            org.apache.xerces.xni.XNIException

Creates a Xerces SAX event source using the a given parser configuration class.

The setInputSource() method of the given parser will be called before parsing begins.

Parameters:

inputSource - is the input document to be parsed.

xniParser - is a Xerces Native Interface pull-parser.

Method Detail

isAvailable

public static boolean isAvailable()

Returns whether the standard configuration implementation of the Xerces Native Interface pull-parser is available. If this method returns true, then using the XercesSaxEventSource(InputSource) constructor will succeed.

setContentHandler

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

Description copied from interface: SaxEventSource

Sets the content handler to receive SAX events.

This method is called by SaxIterator before it calls generateEvents().

Not all handler methods need be called by a generator. The methods used are as follows and all other method calls are ignored.

• ContentHandler.characters()
• ContentHandler.startElement()
• ContentHandler.endElement()
• ContentHandler.startPrefixMapping()
• ContentHandler.endPrefixMapping()
• ContentHandler.setDocumentLocator()

Specified by:

setContentHandler in interface SaxEventSource

generateEvents

public boolean generateEvents()
                       throws java.io.IOException,
                              XmlIteratorException

Description copied from interface: SaxEventSource

Generates a subset of SAX events and returns true if more events are still available.

Specified by:

generateEvents in interface SaxEventSource

Following copied from interface: org.greybird.xmliter.SaxEventSource

Throws:

java.io.IOException - if an error occurs retrieving input data.

XmlIteratorException - if an error occurs processing input data.

close

public void close(boolean completeParsing)
           throws java.io.IOException,
                  XmlIteratorException

Description copied from interface: SaxEventSource

Closes the event source to free up resources and stops generating events.

Even when completeParsing is true, no events should be generated by this method or by subsequent calls to generateEvents().

Specified by:

close in interface SaxEventSource

Following copied from interface: org.greybird.xmliter.SaxEventSource

Parameters:

completeParsing - is true if parsing and reading of the input source should be completed during close, or false to abort parsing and reading.

Throws:

java.io.IOException - if an error occurs retrieving input data.

XmlIteratorException - if an error occurs processing input data.