Interface if_ixml_event
The iXMLEvent interface represents events signaled by the XML parser when operating in the eventing mode.
To find out the type of an event, call getType(). Types are represented by constants defined in the iXMLEvent::EventTypes enumeration.
Each event has an associated DOM node. This node can be accessed via getNode() if necessary. Only read-only methods should be called on the corresponding node though, calling update methods might lead to undesired and undefined effects.
To allow convenient and efficient access to the most commonly used node information, the methods getName(), getValue(), getParent() and getAttributes() have been added redundantly to the iXMLEvent interface, even though they directly map to the corresponding node interface (i.e. iXMLEvent::getName() calls iXMLEvent::getNode()->getName()).
Depending on the type of event and the point in time (pre or post) only part of the Event interface's or associated DOM interface's methods return defined values. Calling iXMLEvent::getAttributes() for a CommentPre/Post event returns null, since comments don't support attributes! Calling getValue() for a TextPre event returns null, since at this point in time the value has not yet been parsed; calling getValue() for a TextPost event will return the value of course.
Please be aware that even though access to the associated DOM node is available, there does not necessarily exist a complete DOM tree for a parser run. If DOM generation has been disabled for the parser (via iXMLParser::setDomGenerating (false)) no such tree exists completely at any point in time. The only valid assumption to make is that there are always all nodes from the current event's associated node upwards to the root node (Document node) defined. No sibling nodes exist, so calling getNext() on a node will always return null.
If DOM generation has been enabled (via iXMLParser::setDOMGenerating(true)) the DOM tree is accessible. The extend of the DOM tree is of course limited to what has been parsed from the document so far.
specializes
enumerations
methods
enumeration EventTypes
The values of the EventTypes enumeration are used to identify the various types of events.
interface
if_ixml_event
values
co_event_document_pre = 0x00000001L
The event DocumentPre is signaled when the document's XML prolog has been parsed. At this point in time information about the XML version, the used character encoding and the standalone property of the XML document is available.
co_event_document_post = 0x00000002L
The event DocumentPost is signaled when the complete document has been parsed. If DOM generation was enabled for this parser run, the DOM tree can be accessed by querying the associated Document node via the getNode() method of this interface.
co_event_attribute_pre = 0x00000004L
The event AttributePre event is signaled when the start of an attribute has been detected by the parser. At this point in time only the name of the attribute, not the value of the attribute is known.
co_event_attribute_post = 0x00000008L
The event AttributePost event is signaled when an attribute (name and value) has been completely parsed. At this point in time both the attribute's name and its value are known and can be queried via the getName() and the getValue() methods of this interface.
co_event_element_pre = 0x00000010L
The event ElementPre event is signaled when the start of an element has been detected by the parser. This event applies to both "regular" element start tags as well as start tags for empty elements. At this point in time only the name of the element is known, but attributes and element content are still undefined.
co_event_element_pre2 = 0x00000020L
The event ElementPre2 event is signaled when the closing delimiters of a "regular" element start tag or an empty element tag has been detected by the parser, i.e. when all possible attributes have been parsed for an element. At this point in time - in addition to the name of the element - all attributes have been parsed and can be accessed via getAttributes.
co_event_element_post = 0x00000040L
The event ElementPost event is signaled when closing delimiters of a "regular" element end tag or an empty element tag has been detected by the parser and a match of the end tag's element name and the corresponding start tag's element name has been found. At this point in time - in addition to the name of the element and all attributes - the content of the element has been parsed (e.g. other elements or text etc.). If DOM generation is enabled for this parser run, access to the element's content is available by first retrieving the associated DOM node by a call to getNode() and then using the returned node's interface to access the child nodes representing the element's content. If DOM generation is disabled though, the content of the element can't be accessed at this point in time.
co_event_text_pre = 0x00000080L
The event TextPre event is signaled as soon as the parser detects text content in an XML document. At this point in time the actual text is not yet (completely) parsed.
co_event_text_post = 0x00000100L
The event TextPost event is signaled when the parser has finished parsing a continuous area of text content in an XML document. At this point in time the actual text content can be queried via getValue().
co_event_comment_pre = 0x00000200L
The event CommentPre event is signaled when the parser detects the start tag for an XML comment. At this point in time the content of the comment (the comment text) is not yet known.
co_event_comment_post = 0x00000400L
The event CommentPost event is signaled when the parser has finished parsing a comment and detected the comment end tag. At this point in time the content of the comment can be accessed via getValue().
co_event_pi_unparsed_pre = 0x00000800L
The event PIUnparsedPre event is signaled when the parser has detected an unparsed processing instruction. At this point in time only the processing target is known and can be retrieved via getName().
co_event_pi_unparsed_post = 0x00001000L
The event PIUnparsedPost event is signaled when the parser has finished parsing a unparsed processing instruction and detected the processing instruction end tag. At this point in time the content of the processing instruction can be accessed via getValue(), the processing instruction target can be retrieved via getName().
co_event_pi_parsed_pre = 0x00002000L
The event PIParsedPre event is signaled when the parser has detected a parsed processing instruction. At this point in time only the processing target is known and can be retrieved via getName().
co_event_pi_parsed_post = 0x00004000L
The event PIParsedPost event is signaled when the parser has finished parsing a parsed processing instruction and detected the processing instruction end tag. At this point in time the content of the processing instruction can be accessed in form of attributes via getAttributes(), the processing instruction target can be retrieved via getName().
co_event_cdata_section_pre = 0x00008000L
The event CDATASectionPre event is signaled when the parser detects a CDATA section. At this point in time the content of the CDATA section is not yet known.
co_event_cdata_section_post = 0x00010000L
The event CDATASectionPost event is signaled when the parser has finished parsing a CDATA section. At this point in time the content of the CDATA section can be retrieved via getValue().
co_event_document_type_pre = 0x00020000L
The event DocumentTypePre event is signaled when the parser detects the beginning of a document type definition (DTD) in an XML document.
co_event_document_type_post = 0x00030000L
The event DocumentTypePost event is signaled when the parser has finished parsing the document type definition (DTD) in an XML document. At this point in time all entity, notation, attribute list and element declarations have been processed and can be retrieved via the DocumentType node associated with this event. Use getNode() to get to this node.
co_event_entity_ref_pre = 0x00080000L
The event EntityRefPre event is signaled when the parser detects a general entity reference. At this point in time the name of the referenced entity is not yet known.
co_event_entity_ref_post = 0x00100000L
The event EntityRefPost event is signaled when the parser has finished parsing the entity reference. At this point in time the name of the referenced entity can be queried via getName().
co_event_cond_dtd_section_pre = 0x00200000L
The event CondDTDSectionPre event is signaled when the parser detects a conditional DTD section. At this point in time the type (include or ignore) of the conditional DTD section is already known! This allows a client application to include or ignore the following data in its processing.
co_event_cond_dtd_section_post = 0x00400000L
The event CondDTDSectionPost event is signaled when the parser has finished parsing a conditional DTD section.
co_event_element_decl_pre = 0x00800000L
The event ElementDeclPre event is signaled when the parser detects an element declaration in the DTD (document type definition).
co_event_element_decl_post = 0x01000000L
The event ElementDeclPost event is signaled when the parser has finished parsing an element declaration in the DTD (document type definition). At this point in time the content specification (content model) for the element is available and can be accessed via getContentSpec(). Further information and access to the content particles is possible by first navigating to the associated node via getNode() and then using the methods of the ElementDecl interface.
co_event_att_list_decl_pre = 0x02000000L
The event AttListDeclPre event is signaled when the parser detects an attribute list declaration in the DTD (document type definition).
co_event_att_list_decl_post = 0x04000000L
The event ElementDeclPost event is signaled when the parser has finished parsing an element declaration in the DTD (document type definition). At this point in time all attribute declarations for this attribute list declaration have been parsed. Use the associated AttListDecl node to gain access to these attribute declarations. The getName() method of this interface provides the name of the element (!) to which this attribute list belongs.
co_event_attribute_decl_pre = 0x02000000L
The event AttributeDeclPre event is signaled when the parser detects an attribute declaration in an attribute list declaration.
co_event_attribute_decl_post = 0x04000000L
The event AttributeDeclPost event is signaled when the parser has finished parsing an attribute declaration in an attribute list declaration. At this point in time the complete attribute declaration has been parsed and information about value type, attribute defaulting or enumeration values is available. The getName() method of this interface provides the name of the attribute (!) to which this attribute declaration belongs.
co_event_entity_decl_pre = 0x08000000L
The event EntityDeclPre event is signaled when the parser detects an entity declaration in a DTD (document type definition).
co_event_entity_decl_post = 0x10000000L
The event EntityDeclPost event is signaled when the parser has finished parsing an entity declaration in the DTD (document type definition). At this point in time the complete entity declaration has been parsed and information about system or public ID (for external entities) or the entity value (for internal entities) is available.
co_event_notation_decl_pre = 0x20000000L
The event NotationDeclPre event is signaled when the parser detects a notation declaration in a DTD (document type definition).
co_event_notation_decl_post = 0x40000000L
The event NotationDeclPost event is signaled when the parser has finished parsing a notation declaration in the DTD (document type definition). At this point in time the complete notation declaration has been parsed and information about the system or public ID is available.
abap signature
constants:
co_event_document_pre type I value 1,
co_event_document_post type I value 2,
co_event_attribute_pre type I value 4,
co_event_attribute_post type I value 8,
co_event_element_pre type I value 16,
co_event_element_pre2 type I value 32,
co_event_element_post type I value 64,
co_event_text_pre type I value 128,
co_event_text_post type I value 256,
co_event_comment_pre type I value 512,
co_event_comment_post type I value 1024,
co_event_pi_unparsed_pre type I value 2048,
co_event_pi_unparsed_post type I value 4096,
co_event_pi_parsed_pre type I value 8192,
co_event_pi_parsed_post type I value 16384,
co_event_cdata_section_pre type I value 32768,
co_event_cdata_section_post type I value 65536,
co_event_document_type_pre type I value 131072,
co_event_document_type_post type I value 196608,
co_event_entity_ref_pre type I value 524288,
co_event_entity_ref_post type I value 1048576,
co_event_cond_dtd_section_pre type I value 2097152,
co_event_cond_dtd_section_post type I value 4194304,
co_event_element_decl_pre type I value 8388608,
co_event_element_decl_post type I value 16777216,
co_event_att_list_decl_pre type I value 33554432,
co_event_att_list_decl_post type I value 67108864,
co_event_attribute_decl_pre type I value 33554432,
co_event_attribute_decl_post type I value 67108864,
co_event_entity_decl_pre type I value 134217728,
co_event_entity_decl_post type I value 268435456,
co_event_notation_decl_pre type I value 536870912,
co_event_notation_decl_post type I value 1073741824.
method get_attributes
Returns an iXMLNamedNodeMap containing the attributes associated with this event's logical element. Only iXMLElement and iXMLPIParsed nodes actually have attributes associated with them; in all other cases null is returned.
interface
if_ixml_event
return value
Returns an iXMLNamedNodeMap containing the associated node's attributes or null if the node does not support attributes.
abap signature
method get_attributes
returning
value(rval) type ref to if_ixml_named_node_map.
method get_name
Returns the name (local part) of the logical element associated with this event.
interface
if_ixml_event
return value
Returns the logical element's name.
abap signature
method get_name
returning
value(rval) type string.
method get_namespace
Returns the namespace (prefix) of the logical element associated with this event or null if no namespace (prefix) exists.
deprecated
This method has been replaced by the method get_namespace_prefix(). It is still supported for compatibility reasons, but we recommend to switch to the replacement method, since get_namespace() may not be supported any more in a future release.
interface
if_ixml_event
return value
Returns the logical element's namespace (prefix) or null.
abap signature
method get_namespace
returning
value(rval) type string.
method get_namespace_prefix
Returns the namespace prefix of the logical element associated with this event or null if no namespace prefix exists.
interface
if_ixml_event
return value
Returns the logical element's namespace prefix or null.
abap signature
method get_namespace_prefix
returning
value(rval) type string.
method get_node
Returns the DOM node associated with this event's logical element. Even though DOM generation might be disabled for the current parser run, internally a DOM representation of the current logical element and all its direct and indirect parents is created. This method allows to get access to this DOM node. Be aware that not all information usually available when DOM generation is enabled might be available (e.g. information about sibling nodes might be unavailable).
interface
if_ixml_event
return value
Returns the DOM node for the logical element associated with this event.
abap signature
method get_node
returning
value(rval) type ref to if_ixml_node.
method get_parent
Even if DOM creation is disabled for a particular parser run, the XML parser creates an internal representation of the XML document that allows to retrieve DOM information about the direct and indirect parents of the logical element associated with the current event. This is necessary to allow e.g. that a text event can be processed in the context of the corresponding element it belongs to. This method allows to retrieve the parent node in the DOM for the current event. Be aware though that not the complete DOM information might be available if DOM generation is switched off for this parsing run (e.g. information about sibling nodes is not available).
interface
if_ixml_event
return value
Returns the parent node for the logical element associated with this event.
abap signature
method get_parent
returning
value(rval) type ref to if_ixml_node.
method get_type
Returns the type of this event (see iXMLEvent::EventTypes).
interface
if_ixml_event
return value
Returns the event's type.
abap signature
method get_type
returning
value(rval) type I.
method get_value
Returns the value associated with this event's logical element (e.g. the attribute value for an EventAttributePost event). Not all logical elements support the notion of a value, in which case this method returns a null-string
interface
if_ixml_event
return value
Returns the value defined for the logical element associated with this event, or null if no such value is defined.
abap signature
method get_value
returning
value(rval) type string.
method query_interface
Queries the specified interface.
interface
if_ixml_event
parameters
iid
The interface ID of the interface to query.
return value
Returns a reference to the queried interface or null if no such interface is supported.
abap signature
method query_interface
importing
iid type I
returning
value(rval) type I.