GXPARSE hosted by SourceForge.net Logo

ca.gorman.xml.parse
Interface Listener<T extends Parser>

All Superinterfaces:
CharacterListener<T>, DtdListener<T>, ElementListener<T>, EntityListener<T>, MessageListener<T>, PrefixListener<T>, SkippedEntityListener<T>
All Known Implementing Classes:
AbstractErrorListener, AbstractListener, CoroutineCheckListener, DumpListener, SkipListener

public interface Listener<T extends Parser>
extends CharacterListener<T>, DtdListener<T>, ElementListener<T>, EntityListener<T>, MessageListener<T>, PrefixListener<T>, SkippedEntityListener<T>

Combined listener interface for XML processing applications that are driven by an XML push Parser.

This interface borrows ideas from, and has considerable similarity to, David Megginson's SAX interface, as embodied in class org.xml.sax.ext.DefaultHandler2 and the interfaces

The principal differences from event based parser interfaces like SAX are:

Most Listener methods receive String parameters, usually the same as the parameters received by corresponding SAX methods, because the String parameters correspond exactly to data in the XML imput file. This creates a bit more work in the application, but it also gives more flexibility in processing because there is no need to undo a transformation that would otherwise hide some characteristics of the input data from the application. David Megginson may have had a similar reason for returning String parameters in the SAX interface.

A number of Listener methods are inherited from sperclasses to support delegation of the methods from a subclass of Listener. More of the methods may be moved to new superclasses in the future.


Method Summary
 void cdata(T parser, CurrentMarkedSection cdata)
           Receive a CDATA marked section.
 void comment(T parser, CharSequence charSequence)
           Report an XML comment anywhere in the document.
 void doDocument(T parser, CurrentDocument document)
           Receive a request to handle a document that is being parsed.
 Input getExternalSubset(T parser, String name, String baseURI)
           Allows applications to replace a missing external subset.
 void processingInstruction(T parser, String target, String data)
           Receive notification of a processing instruction.
 Input resolveEntity(T parser, String name, String publicId, String baseURI, String systemId)
           Allow the application to resolve external entities.
 
Methods inherited from interface ca.gorman.xml.parse.CharacterListener
characters, ignorableWhitespace
 
Methods inherited from interface ca.gorman.xml.parse.DtdListener
attributeDecl, doDtd, elementDecl, externalEntityDecl, internalEntityDecl, notationDecl, unparsedEntityDecl
 
Methods inherited from interface ca.gorman.xml.parse.ElementListener
doElement
 
Methods inherited from interface ca.gorman.xml.parse.EntityListener
doEntity
 
Methods inherited from interface ca.gorman.xml.parse.MessageListener
error, fatalError, warning
 
Methods inherited from interface ca.gorman.xml.parse.PrefixListener
endPrefixMapping, startPrefixMapping
 
Methods inherited from interface ca.gorman.xml.parse.SkippedEntityListener
skippedEntity
 

Method Detail

cdata

void cdata(T parser,
           CurrentMarkedSection cdata)
           throws ListenerException,
                  IOException

Receive a CDATA marked section. The method is invoked at the beginning of the CDATA section. The method must invoke content handler exactly once to parse the CDATA section. Consequently, this method has control only before and after the parser reads the CDATA section

Parameters:
parser - The Parser that invoked this method
cdata - CurrentMarkedSection instance with a content handler to parse the centent of the entity.
Throws:
ListenerRuntimeException - if this method does not invoke the content handler exactly once before returning.
ListenerException
IOException

doDocument

void doDocument(T parser,
                CurrentDocument document)
                throws ListenerException,
                       IOException

Receive a request to handle a document that is being parsed. The method is invoked just before the parser begins parsing. The method must invoke content handler exactly once to parse the content of the document. Consequently, this method has control only before and after the actual parsing operation.

Parameters:
parser - The Parser that invoked this method
document - CurrentDocument instance with a content handler to parse the centent of the document.
Throws:
ListenerRuntimeException - if this method does not invoke the content handler exactly once before returning.
ListenerException
IOException

getExternalSubset

Input getExternalSubset(T parser,
                        String name,
                        String baseURI)
                        throws ListenerException,
                               IOException

Allows applications to replace a missing external subset.

This method is invoked when there is a DOCTYPE declaration that does not define an external subset. Returning an Input that provides wan external subset has the same effect as if the document text had originally included the external subset.

This method is also invoked when the root element has been encountered, but no DOCTYPE declaration has been seen. Returning an Input that provides an external subset has the same effect as if a DOCTYPE declaration with an external subset had preceded the root element.

Warning: Returning an external subset modifies the input document. By providing definitions for general entities, it can make a malformed document appear to be well formed.

Parameters:
parser - The Parser that invoked this method
name - Identifies the document root element. This name comes from a DOCTYPE declaration (where available) or from the actual root element
baseURI - The absolute URI of the document, or null if the URI was not given to the parser
Returns:
An Input object describing the input source for the external subset, or null to request that the parser open a regular URI connection to the system identifier.
Throws:
ListenerException
IOException

processingInstruction

void processingInstruction(T parser,
                           String target,
                           String data)
                           throws ListenerException,
                                  IOException

Receive notification of a processing instruction.

Parameters:
parser - The Parser that invoked this method
target - The processing instruction target.
data - The processing instruction data, or null if none was supplied. The data does not include any whitespace separating it from the target.
Throws:
ListenerException
IOException

resolveEntity

Input resolveEntity(T parser,
                    String name,
                    String publicId,
                    String baseURI,
                    String systemId)
                    throws ListenerException,
                           IOException

Allow the application to resolve external entities.

Parameters:
parser - The Parser that invoked this method
name - Either "[dtd]" for the external subset, or a name starting with "%" to indicate a parameter entity, or else the name of a general entity
publicId - The public identifier of the external entity being referenced, or null if none was supplied
baseURI - The absolute URI against which a relative systemID would be resolved, or null if none was supplied
systemId - The absolute or relative URI that identifies the external entity being referenced.
Returns:
An Input object describing the new input source, or null to request that the parser open a regular URI connection to the system identifier.
Throws:
ListenerException
IOException

comment

void comment(T parser,
             CharSequence charSequence)
             throws ListenerException,
                    IOException

Report an XML comment anywhere in the document.

In some implementations, charSequence may reference data that is not resident in memory. In such cases, the amount of data may be large enough to cause the CharSequence.toString() method to throw OutOfMemoryError.

Parameters:
parser - The Parser that invoked this method
charSequence - A CharSequence containing the characters in the comment.
Throws:
ListenerException
IOException

GXPARSE download

GXPARSE Generic XML Stream Parser API and supporting tools.   Release $Name: gxparse-sf-alpha-2_0 $
Copyright 2003-2004 Ian E. Gorman
Released under GNU Lesser General Public License