xml.pipeline
Class EventProducer

java.lang.Object
  |
  +--xml.pipeline.EventProducer
Direct Known Subclasses:
DomProducer

public class EventProducer
extends java.lang.Object

This class describes a kind of "producer" end of a SAX event pipeline, which sends all the event callbacks for one "document" to a "consumer". Producers are first set up with one input document; they parse it, and send its events to their consumer. Unless a specific parser is provided, parsing is done with the system default XML parser. That parser normally does not validate its inputs.

Consumers may be arbitrarily complex pipeline networks, branching and joining as required by the application module of which they are a part. Producers may later be given additional input documents to parse, which they'll do without rebinding handlers. (That is, all setup overhead is avoided starting with the second use of that pipeline.)

In that way, simple "one shot" processing pipelines are a natural lead-in to more complex ones accepting multiple documents, as part of work flow or other XML processing systems.

Three chunks of SAX2 configuration are here coupled to the parser setup: error handler, diagnostic locale, and entity resolution. Everything relating to the document itself is sent to a consumer. Consumers automatically have access to the parser's error handler, promoting consistency in error reporting and handling mechanisms.

Note that event pipelines can be used directly, without needing any kind of EventProducer. The producer abstraction is primarily used to group XML "Document" level abstractions into chunks which can be processed together. When working with finer grained abstractions, such as application components which will be combined into a "document", application modules may find it preferable to work directly with the event consumption end of a pipeline.

Version:
$Date: 2000/07/15 00:56:58 $
Author:
David Brownell

Constructor Summary
EventProducer(InputSource i)
          Builds an event producer from the system default SAX parser, in its default configuration, and the specified input source.
EventProducer(java.lang.String uri)
          Uses the specified URI to build an event producer from the system default SAX parser, in its default configuration, and that URI.
EventProducer(XMLReader p, InputSource i)
          Builds an event producer from the specified parser, in its current configuration, and the specified input source.
 
Method Summary
 boolean getFeature(java.lang.String id)
           
 void parseDocument(InputSource source)
          Start firing events to the next stage in the pipeline, returning when the specified inputSource is finished.
 void produce(EventConsumer out)
          Configures the event producer to send events to the specified event consumer, and invokes parseDocument() with the initial input source.
 void setEntityResolver(EntityResolver r)
          Provides the specified entity resolver to the parser.
 void setErrorHandler(ErrorHandler h)
          Provides the specified error handler to the parser; it will later be provided to the event consumer that processes parser events.
 void setFeature(java.lang.String id, boolean value)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

EventProducer

public EventProducer(java.lang.String uri)
              throws SAXException
Uses the specified URI to build an event producer from the system default SAX parser, in its default configuration, and that URI.

EventProducer

public EventProducer(InputSource i)
              throws SAXException
Builds an event producer from the system default SAX parser, in its default configuration, and the specified input source.

EventProducer

public EventProducer(XMLReader p,
                     InputSource i)
Builds an event producer from the specified parser, in its current configuration, and the specified input source. The handlers will generally be changed from the configuration provided here, if the event consumer provides a value for that handler.
Parameters:
p - The parser to use; this should be configured already with an EntityResolver, ErrorHandler, and Locale.
Method Detail

setFeature

public final void setFeature(java.lang.String id,
                             boolean value)
                      throws SAXException

getFeature

public final boolean getFeature(java.lang.String id)
                         throws SAXException

setErrorHandler

public final void setErrorHandler(ErrorHandler h)
Provides the specified error handler to the parser; it will later be provided to the event consumer that processes parser events.

setEntityResolver

public final void setEntityResolver(EntityResolver r)
Provides the specified entity resolver to the parser.

produce

public void produce(EventConsumer out)
             throws SAXException,
                    java.io.IOException
Configures the event producer to send events to the specified event consumer, and invokes parseDocument() with the initial input source. After this returns, the producer is still configured to use that consumer (as when this method was called -- subsequent changes are ignored) and parseDocument may be invoked to send parsing events for additional XML documents.

Certain kinds of event filters are recognized, and can be optimized out by setting appropriate parser options. NSFilter is one such filter; if it is at the front of a pipeline, a producer wrapping a SAX parser may be able to remove it and improve overall performance by requesting that parsers not discard such information, rather than attempting a costly (and potentially error prone) reconstruction.

See Also:
PipelineFactory

parseDocument

public void parseDocument(InputSource source)
                   throws SAXException,
                          java.io.IOException
Start firing events to the next stage in the pipeline, returning when the specified inputSource is finished.

Source code is GPL'd at http://xmlconf.sourceforge.net.