GXPARSE hosted by SourceForge.net Logo

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

All Known Subinterfaces:
ElementMapper<T>, Listener<T>, NamespaceMapper<T>
All Known Implementing Classes:
AbstractErrorListener, AbstractListener, ClassNamespaceElementMapper, CoroutineCheckListener, DumpListener, ElementClassMapper, NamespacePackageMapper, PackageNamespaceElementMapper, SimpleElementMapper, SkipListener

public interface ElementListener<T extends Parser>

Listener interface for XML element notification.


Method Summary
 void doElement(T parser, CurrentElement element)
           Receive a request to handle a element that is being parsed.
 

Method Detail

doElement

void doElement(T parser,
               CurrentElement element)
               throws ListenerException,
                      IOException

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.

Parameters:
parser - The Parser that invoked this method
element - CurrentElement instance with a content handler to parse the centent of the element.
Throws:
ListenerRuntimeException - if this method does not invoke the content handler exactly once before returning.
ListenerException - when the exception has been thrown from a Listener method.
IOException - when an input or output error occurs
NullPointerException - when any parameter is null

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