GXPARSE hosted by SourceForge.net Logo

ca.gorman.xml.parse
Class AbstractListener<T extends Parser>

java.lang.Object
  extended by ca.gorman.xml.parse.AbstractListener<T>
All Implemented Interfaces:
CharacterListener<T>, DtdListener<T>, ElementListener<T>, EntityListener<T>, Listener<T>, MessageListener<T>, PrefixListener<T>, SkippedEntityListener<T>
Direct Known Subclasses:
AbstractErrorListener

public abstract class AbstractListener<T extends Parser>
extends Object
implements Listener<T>

Provides Listener methods that do nothing.


Constructor Summary
protected AbstractListener()
           
 
Method Summary
 void attributeDecl(T parser, String eName, String aName, String type, String valueDefault, String value)
           Report an attribute type declaration.
 void cdata(T parser, CurrentMarkedSection cdata)
           Receive a CDATA marked section.
 void characters(T parser, CharSequence charSequence)
           Receive notification of characters.
 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.
 void doDtd(T parser, CurrentDtd dtd)
           Receive a request to handle a DTD that is being being parsed.
 void doElement(T parser, CurrentElement element)
           Receive a request to handle a element that is being parsed.
 void doEntity(T parser, CurrentEntity entity)
           Process an entity, including the entity content.
 void elementDecl(T parser, String name, String model)
           Report an element type declaration.
 void endPrefixMapping(T parser, String prefix)
           End the scope of a prefix-URI mapping (still under development, design may change).
 void error(T parser, String description, Location location, Exception exception)
           Receive notification of a recoverable error.
 void externalEntityDecl(T parser, String name, String publicId, String systemId)
           Report a parsed external entity declaration.
 void fatalError(T parser, String description, Location location, Exception exception)
           Receive notification of a non-recoverable error.
 Input getExternalSubset(T parser, String name, String baseURI)
           Allows applications to replace a missing external subset.
 void ignorableWhitespace(T parser, CharSequence charSequence)
           Receive notification of ignorable whitespace characters.
 void internalEntityDecl(T parser, String name, String value)
           Report an internal entity declaration.
static
<T extends Parser>
AbstractListener<T>
newInstance()
           
 void notationDecl(T parser, String name, String publicId, String systemId)
           Receive notification of a notation declaration event.
 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.
 void skippedEntity(T parser, String name)
           Receive notification of a skipped entity.
 void startPrefixMapping(T parser, String prefix, String uri)
           Begin the scope of a prefix-URI Namespace mapping (still under development, design may change).
 void unparsedEntityDecl(T parser, String name, String publicId, String systemId, String notationName)
           Receive notification of an unparsed entity declaration event.
 void warning(T parser, String description, Location location, Exception exception)
           Receive notification of a warning.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AbstractListener

protected AbstractListener()
Method Detail

newInstance

public static <T extends Parser> AbstractListener<T> newInstance()

doDocument

public void doDocument(T parser,
                       CurrentDocument document)
                throws ListenerException,
                       IOException
Description copied from interface: Listener

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.

Specified by:
doDocument in interface Listener<T extends Parser>
Parameters:
parser - The Parser that invoked this method
document - CurrentDocument instance with a content handler to parse the centent of the document.
Throws:
ListenerException
IOException

startPrefixMapping

public void startPrefixMapping(T parser,
                               String prefix,
                               String uri)
                        throws ListenerException,
                               IOException
Description copied from interface: PrefixListener

Begin the scope of a prefix-URI Namespace mapping (still under development, design may change).

Specified by:
startPrefixMapping in interface PrefixListener<T extends Parser>
Parameters:
parser - The Parser that invoked this method
prefix - The Namespace prefix being declared.
uri - The Namespace URI the prefix is mapped to.
Throws:
ListenerException
IOException

endPrefixMapping

public void endPrefixMapping(T parser,
                             String prefix)
                      throws ListenerException,
                             IOException
Description copied from interface: PrefixListener

End the scope of a prefix-URI mapping (still under development, design may change).

Specified by:
endPrefixMapping in interface PrefixListener<T extends Parser>
Parameters:
parser - The Parser that invoked this method
prefix - The prefix that was being mapped.
Throws:
ListenerException
IOException

doElement

public void doElement(T parser,
                      CurrentElement element)
               throws ListenerException,
                      IOException
Description copied from interface: ElementListener

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

The start tag information remains available during the entire scope of the method, via methods in CurrentElement.

When several elements are nested, the current element will be at the top of an element stack. The parent element, and successive ancestors back to the document element, can be obtained by invoking getParent. The element data (including attributes) of every element remains available as long as that element is on the element stack.

All content processing is done from the parser by invocation of Listener methods. For example, subordinate elements are delivered via new invocations of doElement and character input is delivered via the characters method. The precise effect of those methods (e.g. direction of characters to a Writer or to a StringBuffer) can be controlled by changing the state of the application upon entry to the doElement and restoring the previous application state just prior to exit.

When multiple invocations of this method are active, the invocation of the method for each parent element is suspended, pending return from the content handler that was invoked by that method. Since all Listener methods are invoked in the application thread, and the parser thread is properly serialized with the application thread, all programming in the application thread can be done as if there were only one active thread. It is only necessary to be aware of the sequence of execution, as in the following example of a parent element and a child element that contains only PDCATA:

  1. Enter parent method and invoke content handler in parent method. One element (final The parent) is on the element stack.
  2. Invoke content handler in parent method
  3. Enter child method and invoke content handler in child method. Two elements (parent and child) are on the element stack.
  4. Invoke content handler in child method
  5. Invoke character handler. Two elements (parent and child) are on the element stack.
  6. Return from character handler. Two elements (parent and child) are on the element stack.
  7. Return from content handler in child method and continue in child method. Two elements (parent and child) are on the element stack.
  8. Return from child method. The child element will be popped from element stack.
  9. Return from content handler in parent method and continue in parent method. One element (final The parent) is on the element stack.
  10. Return from parent method. The parent element will be popped from element stack after the return.

Specified by:
doElement in interface ElementListener<T extends Parser>
Parameters:
parser - The Parser that invoked this method
element - CurrentElement instance with a content handler to parse the centent of the element.
Throws:
ListenerException - when the exception has been thrown from a Listener method.
IOException - when an input or output error occurs

characters

public void characters(T parser,
                       CharSequence charSequence)
                throws ListenerException,
                       IOException
Description copied from interface: CharacterListener

Receive notification of characters.

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.

Specified by:
characters in interface CharacterListener<T extends Parser>
Parameters:
parser - The Parser that invoked this method
charSequence - A CharSequence containing the character data from the XML document.
Throws:
ListenerException
IOException

ignorableWhitespace

public void ignorableWhitespace(T parser,
                                CharSequence charSequence)
                         throws ListenerException,
                                IOException
Description copied from interface: CharacterListener

Receive notification of ignorable whitespace characters.

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.

Specified by:
ignorableWhitespace in interface CharacterListener<T extends Parser>
Parameters:
parser - The Parser that invoked this method
charSequence - A CharSequence containing the whitespace from the XML document.
Throws:
ListenerException
IOException

processingInstruction

public void processingInstruction(T parser,
                                  String target,
                                  String data)
                           throws ListenerException,
                                  IOException
Description copied from interface: Listener

Receive notification of a processing instruction.

Specified by:
processingInstruction in interface Listener<T extends Parser>
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

skippedEntity

public void skippedEntity(T parser,
                          String name)
                   throws ListenerException,
                          IOException
Description copied from interface: SkippedEntityListener

Receive notification of a skipped entity.

Specified by:
skippedEntity in interface SkippedEntityListener<T extends Parser>
Parameters:
parser - The Parser that invoked this method
name - The name of the skipped entity. If it is a parameter entity, the name will begin with '%', and if it is the external DTD subset, it will be the string "[dtd]".
Throws:
ListenerException
IOException

notationDecl

public void notationDecl(T parser,
                         String name,
                         String publicId,
                         String systemId)
                  throws ListenerException,
                         IOException
Description copied from interface: DtdListener

Receive notification of a notation declaration event.

Specified by:
notationDecl in interface DtdListener<T extends Parser>
Parameters:
parser - The Parser that invoked this method
name - The notation name.
publicId - The notation's public identifier, or null if none was given.
systemId - The notation's system identifier, or null if none was given.
Throws:
ListenerException
IOException

unparsedEntityDecl

public void unparsedEntityDecl(T parser,
                               String name,
                               String publicId,
                               String systemId,
                               String notationName)
                        throws ListenerException,
                               IOException
Description copied from interface: DtdListener

Receive notification of an unparsed entity declaration event.

Specified by:
unparsedEntityDecl in interface DtdListener<T extends Parser>
Parameters:
parser - The Parser that invoked this method
name - The unparsed entity's name.
publicId - The entity's public identifier, or null if none was given.
systemId - The entity's system identifier.
notationName - The name of the associated notation.
Throws:
ListenerException
IOException

elementDecl

public void elementDecl(T parser,
                        String name,
                        String model)
                 throws ListenerException,
                        IOException
Description copied from interface: DtdListener

Report an element type declaration.

Specified by:
elementDecl in interface DtdListener<T extends Parser>
Parameters:
parser - The Parser that invoked this method
name - The element type name.
model - The content model as a normalized string.
Throws:
ListenerException
IOException

attributeDecl

public void attributeDecl(T parser,
                          String eName,
                          String aName,
                          String type,
                          String valueDefault,
                          String value)
                   throws ListenerException,
                          IOException
Description copied from interface: DtdListener

Report an attribute type declaration.

Specified by:
attributeDecl in interface DtdListener<T extends Parser>
Parameters:
parser - The Parser that invoked this method
eName - The name of the associated element.
aName - The name of the attribute.
type - A string representing the attribute type.
valueDefault - A string representing the attribute default ("#IMPLIED", "#REQUIRED", or "#FIXED") or null if none of these applies.
value - A string representing the attribute's default value, or null if there is none.
Throws:
ListenerException
IOException

internalEntityDecl

public void internalEntityDecl(T parser,
                               String name,
                               String value)
                        throws ListenerException,
                               IOException
Description copied from interface: DtdListener

Report an internal entity declaration.

Specified by:
internalEntityDecl in interface DtdListener<T extends Parser>
Parameters:
parser - The Parser that invoked this method
name - The name of the entity. If it is a parameter entity, the name will begin with '%'.
value - The replacement text of the entity.
Throws:
ListenerException
IOException

externalEntityDecl

public void externalEntityDecl(T parser,
                               String name,
                               String publicId,
                               String systemId)
                        throws ListenerException,
                               IOException
Description copied from interface: DtdListener

Report a parsed external entity declaration.

Specified by:
externalEntityDecl in interface DtdListener<T extends Parser>
Parameters:
parser - The Parser that invoked this method
name - The name of the entity. If it is a parameter entity, the name will begin with '%'.
publicId - The declared public identifier of the entity, or null if none was declared.
systemId - The declared system identifier of the entity.
Throws:
ListenerException
IOException

getExternalSubset

public Input getExternalSubset(T parser,
                               String name,
                               String baseURI)
                        throws ListenerException,
                               IOException
Description copied from interface: Listener

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.

Specified by:
getExternalSubset in interface Listener<T extends Parser>
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

resolveEntity

public Input resolveEntity(T parser,
                           String name,
                           String publicId,
                           String baseURI,
                           String systemId)
                    throws ListenerException,
                           IOException
Description copied from interface: Listener

Allow the application to resolve external entities.

Specified by:
resolveEntity in interface Listener<T extends Parser>
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

warning

public void warning(T parser,
                    String description,
                    Location location,
                    Exception exception)
             throws ListenerException,
                    IOException
Description copied from interface: MessageListener

Receive notification of a warning.

Specified by:
warning in interface MessageListener<T extends Parser>
Parameters:
parser - The Parser that invoked this method
description - A summary of the warning information (may be an empty String).
location - Information about the location in the input
exception - Additional information from the underlying parser. The information will depend on the Parser implementation. The parameter may be null, and the underlying parser may not have actually thrown an exception.
Throws:
ListenerException
IOException

error

public void error(T parser,
                  String description,
                  Location location,
                  Exception exception)
           throws ListenerException,
                  IOException
Description copied from interface: MessageListener

Receive notification of a recoverable error.

Specified by:
error in interface MessageListener<T extends Parser>
Parameters:
parser - The Parser that invoked this method
description - A summary of the warning information (may be an empty String).
location - Information about the location in the input
exception - Additional information from the underlying parser. The information will depend on the Parser implementation. The parameter may be null, and the underlying parser may not have actually thrown an exception.
Throws:
ListenerException
IOException

fatalError

public void fatalError(T parser,
                       String description,
                       Location location,
                       Exception exception)
                throws ListenerException,
                       IOException
Description copied from interface: MessageListener

Receive notification of a non-recoverable error.

Specified by:
fatalError in interface MessageListener<T extends Parser>
Parameters:
parser - The Parser that invoked this method
description - A summary of the warning information (may be an empty String).
location - Information about the location in the input
exception - Additional information from the underlying parser. The information will depend on the Parser implementation. The parameter may be null, and the underlying parser may not have actually thrown an exception.
Throws:
ListenerException
IOException

cdata

public void cdata(T parser,
                  CurrentMarkedSection cdata)
           throws ListenerException,
                  IOException
Description copied from interface: Listener

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

Specified by:
cdata in interface Listener<T extends Parser>
Parameters:
parser - The Parser that invoked this method
cdata - CurrentMarkedSection instance with a content handler to parse the centent of the entity.
Throws:
ListenerException
IOException

doDtd

public void doDtd(T parser,
                  CurrentDtd dtd)
           throws ListenerException,
                  IOException
Description copied from interface: DtdListener

Receive a request to handle a DTD that is being being parsed. The method is invoked at the start of parsing the DTD and mustinvoke a content handler exactly once to parse the content of the DTD. Consequently, the method has control only before and after the parsing of the DTD.

Specified by:
doDtd in interface DtdListener<T extends Parser>
Parameters:
parser - The Parser that invoked this method
dtd - CurrentDtd instance with a content handler to parse the centent of the DTD.
Throws:
ListenerException
IOException

doEntity

public void doEntity(T parser,
                     CurrentEntity entity)
              throws ListenerException,
                     IOException
Description copied from interface: EntityListener

Process an entity, including the entity content. Parameter entities have '%' prepended to their names, general entities do not.

This method is entered at the beginning of the entity, when the actual data is not yet available. The content is processed when the method calls back (via ParseContent) to the parser. Upon return from the callback, all of the entity has been processed by other Listener methods. For additional information about this method, see the ElementListener.doElement method, which operates in a very similar way.

The primary use of this method is to give special handling to some entities, which will be recognized by the name.

Specified by:
doEntity in interface EntityListener<T extends Parser>
Parameters:
parser - The Parser that invoked this method
entity - CurrentEntity instance with a content handler to parse the centent of the entity.
Throws:
ListenerException
IOException

comment

public void comment(T parser,
                    CharSequence charSequence)
             throws ListenerException,
                    IOException
Description copied from interface: Listener

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.

Specified by:
comment in interface Listener<T extends Parser>
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