Package ca.gorman.xml.parse

Generic XML stream parser API that makes it much easier to use event-based parsers like SAXParser.

See:
Description

Interface Summary

Attribute	Attribute, as presented to the application by the parser.
Catalog	Catalog (still under development, design may change).
CharacterListener<T extends Parser>	Character listener interface for XML processing applications that are driven by an XML push Parser.
CurrentDocument	Java Document instance representing the XML document that is being parsed.
CurrentDtd	Java Dtd instance representing the DTD for the XML document that is being parsed.
CurrentElement	Java Element instance that represents the element being parsed, and the top element on the parser element stack.
CurrentEntity	Java Entity representing the entity that is being parsed.
CurrentMarkedSection	Java MarkedSection instance representing the marked section that is being parsed.
Document	Java Document instance representing the XML document that is being parsed.
Dtd	DTD instance.
DtdListener<T extends Parser>	DTD Listener interface for XML processing applications that are driven by an XML push Parser.
Element	Element, as presented to the application by the parser.
ElementListener<T extends Parser>	Listener interface for XML element notification.
ElementMapper<T extends Parser>	An ElementListener that maps XML element names to element handlers and invokes the appropriate handler for each element.
Entity	Entity, as presented to the application by the parser.
EntityListener<T extends Parser>	Listener interface for XML entity notification.
Global	Tagging interface for a class that serves as a global set of data and methods available to all Listener methods.
Listener<T extends Parser>	Combined listener interface for XML processing applications that are driven by an XML push Parser.
Location	Provides information about the parser's current location.
MarkedSection	Java MarkedSection instance representing an XML marked section.
MessageListener<T extends Parser>	Message listener interface for XML processing applications that are driven by an XML push Parser.
NamespaceMapper<T extends Parser>	An ElementMapper that maps XML element names in one or more XML namespaces to element handlers and invokes the appropriate handler for each element.
Parser<T extends Global>	XML stream parser that invokes Listener methods to drive an XML processing application.
ParserFactory<T extends Global>	Factory for new Parser instances.
PrefixListener<T extends Parser>	Namespace prefix Listener interface for XML processing applications that are driven by an XML push Parser.
SkippedEntityListener<T extends Parser>	Skipped entity listener interface for XML processing applications that are driven by an XML push Parser.

Class Summary

AbstractErrorListener<T extends Parser>	Listener for warnings, recoverable errors, and fatal errors.
AbstractListener<T extends Parser>	Provides Listener methods that do nothing.
AbstractMessageListener<T extends Parser>	Listener that reports warnings, recoverable errors, and fatal errors to a Writer or to System.err.
Input	Supports several different ways of naming an XML input source.

Exception Summary

ElementMapper.InvalidHandlerException	Exception thrown when doElement maps an XML name to a Java identifier that cannot be used to invoke an element handler.
ElementMapper.NotFoundException	Exception thrown when doElement maps an XML name to a Java identifier that is not defined by the application.
ListenerException	Superclass for exceptions thrown from Listener methods by by application code.
ListenerRuntimeException	Superclass for unchecked exceptions thrown from the API that supports the Listener interface.
NamespaceMapper.NamespaceMapException	Exception thrown when an error is detected in the mapping of namespaces.
ParseException	Superclass for exceptions thrown from the Parser implementation.
ParserFactory.ParserConfigurationException	Exception thrown when a Parser cannot be created.
ReparsedContentException	Unchecked exception thrown when a method that is required to return control to the Parser by invoking parsecontent or skipContent trys to do so more than once.
UnparsedContentException	Unchecked exception thrown when a method that is required to invoke either parsecontent or skipContent fails to do so.

Error Summary

ParserFactory.FactoryConfigurationError

Error thrown when a ParserFactory cannot be created.

Package ca.gorman.xml.parse Description

Generic XML stream parser API that makes it much easier to use event-based parsers like SAXParser.

The API maintains most of the advantages of the event-based parser used to support an implementation, and adds the advantage of much lower cost for application development and maintenance. The API also benefits from the advantages of a supporting event-based parser, such as reliability, speed, and compliance to standards. The one disadvantage of the API is a somewhat reduced processing speed, because the new API adds another layer of processing between the application and the event-based XML parser, and because the new API provides enhanced services that some applications will not use.

The methods invoked by the Parser are defined in the Listener interface.

This package extends and modifies David Megginson's Simple API for XML (SAX). The new API provides a generic Listener that receives XML objects constructed by a generic Parser that reads a stream of data.

The principal differences from event-based parsers like SAX are:

• The extended API reduces development and maintenance cost by simplifying the required programming;
  • application programmers do not have to manage element nesting.
  • information (like attribute values) is retained until the information is no longer relevant.
  • information (like the parent of the current element) is available through a set of query methods.
• The extended API is closer to the view of an XML document as a sequential stream with a superimposed structure of nested XML objects:
  • The extended API presents XML elements and entities as single objects to be handled by one method, instead of presenting the start and end of each element or entity to be handled by separate start and end methods.
  • Each element or entity event requires exactly one parser callback to handle the data that would have been handled by the events between a start event and an end event.
  • The stream-based approach used by SAX to handle input is extended to handling the output.
  • The view of an XML-based processor whose state is controlled by the hierarchy of open elements from the document root to the current element element is extended to include pushing and popping the current destination of output.
• Supplementary classes in package ca.gorman.io extend the sequential stream-based model to applications in which the input sequence differs from the output sequence. Applications can process IDREF and IDREFS the need for code to manage temporary memory or random accesss (to either the input or the output).
• The extended API is defined as a set of generic classes and interfaces to reflect the fact that SAX is a very general API, applicable in virtually the same form to other parsers like James Clark SP parser. Implementation for other parsers can be done by using package ca.gorman.xml.parse.toolkit to support packages like ca.gorman.parse.xml.sax.

Package Specification

Treats a XML document dynamically, as a flow, rather than as a collection of static objects. An XML element defines a state, which influences the handling of a character flow within that element. Child elements define a substate, extending or modifying the state defined by the outer element. Each element method is entered once the parser has obtained the start tag for that element. The element method makes any necessary changes to the flow state, and then requests the parser to continue. When the parser reaches the end tag for that element, the element method continues from the point where it surrendered control to the parser, restores the original flow state, and exits. Methods for child elements and character handlers operate in the environment set up (or modified) by the method that handles the parent element.

Related Documentation

The following sources may assist you in deciding whether the software meets your requirments:

• SAX
• XML
• XML Catalog.

See Also:

ca.gorman.xml.parse.toolkit, ca.gorman.xml.parse.sax, ca.gorman.xml.parse.util