Anfang des Inhaltsbereichs

Objektdokumentation Package Event  Dokument im Navigationsbaum lokalisieren

Definition

The iXML library implements two modes of operation for the XML parser:

  1. a mode in which the parser creates a DOM (document type definition) representation of the XML document and
  2. a mode in which the parser signals the occurrence of certain logical elements in the XML document in form of so-called events as they are encountered during the parsing process. A logical element is e.g. an attribute, an element, a notation or entity declaration, a processing instruction etc.

Use

The Event package contains all definitions necessary for the eventing mode approach to XML parsing with the iXML library.

Each event distinguished two points in time:

  1. the time at which it can be told, what logical element (or node) has been found by the parser - the pre-event
  2. the time at which the complete logical element has been parsed - the post-event.

In addition to the distinction between pre- and post-events, there are different events for different logical elements. For each logical element or node class defined by the DOM, there is one matching event with two points in time at which it can occur. To make this concept more clear, here an example: the DOM defines a node type Attribute, which represents element attributes in an XML document. For this node type exists a matching event type with two points in time (pre and post), i.e. there is an event AttributePre and AttributePost. AttributePre is signaled, if the parser encounters an attribute in the XML input stream (i.e. when a name has been parsed in a start tag and the following character is an equal sign (=)). The event AttributePost is signaled, when the parser has finished parsing the attribute, i.e. the attribute's value has been parsed. The same concept applies to all logical elements - or node types - in a similar way.

Structure

The package Event contains the following interfaces:

if_ixml_event

Integration

An event is implemented as an interface - the iXMLEvent interface. Signaling an event to the caller means returning a reference to an iXMLEvent interface.

To find out what type of event an iXMLEvent interface reference represents, call iXMLEvent::getType(). This call will return the event's type (see iXMLEvent::EventTypes for more details).

For each iXMLEvent interface instance exists a corresponding DOM node instance. This DOM node stores the information that is relevant for the particular event (e.g. the name and value of an attribute). To get to the DOM node (or DOM interface to be more precise) associated with an Event interface, you can call the Event::getNode() method.

In order to avoid this step of indirection when accessing event related information (e.g. the element's name) a few convenience methods have been added to the Event interface: getName() to retrieve the logical element's name, getValue() to retrieve the logical element's value, getAttributes() to retrieve the associated attributes (if defined) and getParent() to find a node's parent node.

You have to be aware though that these methods are not always meaningful for a particular event (or associated node); e.g. calling getAttributes() on a CommentPre/Post event is undefined since comment nodes don't have attributes, or calling getValue() on a TextPre event is undefined since at this point in time the value of the Text node has not yet been parsed. To find out what information is available for each event and point in time, please refer to the Event::EventTypes documentation.

Calling update methods (e.g. setAttribute()) on the node associated with an event might lead to undesired and undefined results; it is therefore strongly discouraged! Calling read-only methods (e.g. Text::isWSOnly()) is allowed of course.