The iXMLParser interface provides access to the iXML libraries parsing functionality.
The parser distinguished two modes of operation:
...
1. Event-signaling mode: In this mode of operation, the XML parser does not create an in-memory representation of the XML input as a whole - in form of a DOM (Document Object Model) representation -, but signals the occurrence of logical elements in the XML input to the client application as they are encountered during the parsing process. It is e.g. possible, to signal the occurrence of all element start tags and attributes as well as the occurrence of text content to the client application.
In order to customize which events are to be signaled, the client application can subscribe to a subset or all of the possible events via the setEventSubscription() method.
The event signaling mode supports two different methods of event signaling: one uses a C++ event handler class, which can be user defined (client class implementing the iXML AiXMLEventHandler interface); this approach is used when invoking the parseWithHandler() method of this interface. The other method uses an interator-like approach, signaling events one by one by returning from the iterator's "next" operation, in this case parseEvent() method of this interface. The latter approach has to be used in the ABAP Objects use case.
2. DOM-generating mode: In this second major mode of operation, the XML parser generates an in-memory representation of the whole XML input in form of a tree of nodes, where each node represents a logical element of the XML document. Subclasses of the generic Node class are used to represent the semantical and syntactical differences of the logical elements (e.g. there exists an iXMLAttribute class to represent XML attributes, an iXMLElement class to represent XML Elements, etc.). The DOM representation of an XML document has the advantage, that the nodes' interfaces allow for a subsequent querying and modification of the XML document in a programmatic way and that the resulting XML document can be rendered back into a bytestream representation. In order to use this mode of operation, the method parse() can be invoked on this interface.
· EntityResolutionMode
· NamespaceMode
· ValidationMode
· add_preserve_space_element
· add_strip_space_element
· get_error
· get_event_subscription
· get_namespace_mode
· has_event_subscription
· is_dom_generating
· is_normalizing
· is_supply_attr_defaults
· is_validating
· is_xml_space_aware
· num_errors
· parse
· parse_event
· set_dom_generating
· set_event_subscription
· set_namespace_mode
· set_normalizing
· set_resolve_mode
· set_supply_attr_defaults
· set_validating
· set_xml_space_aware
The values of the EntityResolutionMode enumeration are used to differentiate the levels of entity resolution the parser offers.
if_ixml_parser
values
co_resolve = 1
The XML processor attempts to resolve entity references (default).
co_no_resolve = 2
The XML processor does not attempt to resolve entity references.
co_strict = 4
Failure to resolve an entity reference results in a parser error (default).
co_no_strict = 8
Failure to resolve an entity reference results in a parser warning.
co_no_mark = 16
The XML processor does not mark entity references (default).
co_mark_entity_ref = 32
The XML processor marks entity references as entity-reference nodes.
co_mark_element = 64
The XML processor marks entity references as special element nodes.
co_mark_lexical = 128
The XML processor marks entity references as separate text nodes.
constants:
co_resolve type I value 1,
co_no_resolve type I value 2,
co_strict type I value 4,
co_no_strict type I value 8,
co_no_mark type I value 16,
co_mark_entity_ref type I value 32,
co_mark_element type I value 62,
co_mark_lexical type I value 128.
The values of the ValidationMode enumeration are used to differentiate the levels of DTD validation the parser offers.
if_ixml_parser
values
co_no_validation = 0
Do not validate the XML-Document against the document type definition (DTD)
co_validate = 1
Validate the XML-Document against the document type definition (DTD)
co_validate_if_dtd = 2
Validate the XML-Document against the document type definition (DTD) if a DTD is specified. Otherwise parse the Document in non validating mode.
co_warn_all = 4
The XML processor issues warnings for duplicate attribute-list declarations, for duplicate entity declarations, for duplicate attribute declarations and for forward references to notations and id attribute values.
co_warn_dup_att_list = 8
The XML processor issues a warning when more than one attribute-list declaration is provided for a given element type.
co_warn_dup_attrib_decl = 16
The XML processor issues a warning when more than one attribute definition is provided for a given attribute.
co_warn_dup_entity_decl = 32
The XML processor issues a warning if entities are declared multiple times.
co_warn_forward_decl = 64
The XML processor issues a warning if a notation or id is referenced befor it is declared.
constants:
co_no_validation type I value 0,
co_validate type I value 1,
co_validate_if_dtd type I value 2,
co_warn_all type I value 4,
co_warn_dup_att_list type I value 8,
co_warn_dup_attrib_decl type I value 16,
co_warn_dup_entity_decl type I value 32,
co_warn_forward_decl type I value 64.
The values of the NamespaceMode enumeration are used to differentiate the levels of namespace-awareness the parser offers.
if_ixml_parser
values
co_namespace_unaware = 0
The parser does not recognize qualified names and operates completely namespace unaware.
co_prefix_aware = 1
The parser recognizes qualified names but does not offer any XML Namespace-conforming semantics. This is the parser's default mode as offered with Application Server Releases releases prior to 6.10.
co_namespace_aware = 2
The parser recognizes qualified names and offeres XML Namespace-conforming semantics.
constants:
co_namespace_unaware type I value 0,
co_prefix_aware type I value 1,
co_namespace_aware type I value 2.
Adds a preserve-space element to the parser. A text node is preserved if any of the following apply: - The element name of the parent of the text node is in the set of whitespace preserving element names. - The text node contains at least one non-whitespace charter. As in XML, a whitespace charter is #x20, #x9, #xD or #xA. - An anchestor element of the text node has an xml:space attribute with a value of preserve, and no closer ancestor element has xml:space with a value of default. Otherwise, the text node is stripped.
if_ixml_parser
The name of the element
The elements namecpace prefix or null.
Returns true if the element is succesfully added
method add_preserve_space_element
importing
name type string default '*'
uri type string default ''
returning
value(rval) type boolean.
Adds a strip-space element to the parser. A text node is preserved if any of the following apply: - The element name of the parent of the text node is in the set of whitespace preserving element names. - The text node contains at least one non-whitespace charter. As in XML, a whitespace charter is #x20, #x9, #xD or #xA. - An anchestor element of the text node has an xml:space attribute with a value of preserve, and no closer ancestor element has xml:space with a value of default. Otherwise, the text node is stripped.
if_ixml_parser
The name of the element
The elements namecpace prefix or null.
Returns true if the element is succesfully added
method add_strip_space_element
importing
name type string default '*'
uri type string default ''
returning
value(rval) type boolean.
This method returns the error or warning for the given index, if errors or warnings where issued during the previous parsing process.
if_ixml_parser
The number of the error or warning to return (0..numErrors()-1).
Filters all errors with a severity level less than the one specified (see ParseError::Severity). Only errors with a severity level less than the one specified will be returned. The following values are allowed:
if_ixml_parse_error~co_info
All errors should be considered.
if_ixml_parse_error~co_warning
Don't consider information messages.
if_ixml_parse_error~co_error
Don't consider information messages and warnings.
if_ixml_parse_error~co_fatal_error
Only consider fatal errors, don't report information messages, warnings and errors.
Returns the parse error for the given index (0..numErrors()-1).
method get_error
importing
index type I
min_severity type I default 3
returning
value(rval) type ref to if_ixml_parse_error.
This method returns the currently set event types that get signaled to a caller of parseEvent(). The subscribed events are returned as an OR-combined set of event types (see iXMLEvent::EventType).
if_ixml_parser
The currently set event types for notification.
method get_event_subscription
returning
value(rval) type I.
Returns the level of namespace awareness currently configured for this parser. When running in namespace-aware mode, the parser implementes XML namespace semantics and splits qualified names into local part and namespace prefix. When running namespace-unaware, qualified names are not detected as such and handled as regular names.
if_ixml_parser
Returns the level of namespace awareness currently configured (see iXMLParser::NamespaceMode)
method get_namespace_mode
returning
value(rval) type I.
This method returns whether the given event is included in the currently subscribed events.
if_ixml_parser
The event for which to check subscription (see iXMLEvent::EventType).
Returns true, if the given event is included in the currently subscribed events, false otherwise.
method has_event_subscription
importing
event type I
returning
value(rval) type boolean.
Tests if this parser generates a DOM representation of the parsed XML input.
if_ixml_parser
Returns true if this parser generates a DOM representation of the XML input when parsing, false otherwise
method is_dom_generating
returning
value(rval) type boolean.
Tests if this parser is normalizing the document representation of the parsed XML input. When running in normalize mode, the parser strips all whitespace-only character data from the DOM tree generated that is not pure element content. Furthermore, leading and trailing blanks are removed from character data.
if_ixml_parser
Returns true if this parser runs in normalize mode, false otherwise
method is_normalizing
returning
value(rval) type boolean.
Tests if this parser is supplying default attribute values from the document type definition in non validating mode.
if_ixml_parser
True, if the parser is supplying default attribute values in non validating modes, false otherwise.
method is_supply_attr_defaults
returning
value(rval) type boolean.
Tests if this parser is in validation mode when parsing the XML input. When running in validating mode, the parser validates the document against the document type declaration.
if_ixml_parser
Returns true if this parser is in validation mode, false otherwise.
method is_validating
returning
value(rval) type boolean.
Tests if this parser is aware of xml:space attributes.
if_ixml_parser
True, if the parser is aware of xml:space attributes, false otherwise.
method is_xml_space_aware
returning
value(rval) type boolean.
This method returns the number of parsing errors and warnings that occured during the parsing process of one of the parse methods.
if_ixml_parser
Specifies the minimum severity when determining the number of errors (see ParseError::Severity). Only errors with a severity level greater or equal than the one specified will be counted. The following values are allowed:
if_ixml_parse_error~co_info
All errors should be counted.
if_ixml_parse_error~co_warning
Don't report information messages.
if_ixml_parse_error~co_error
Don't report information messages and warnings.
if_ixml_parse_error~co_fatal_error
Only report fatal errors, don't report information messages, warnings and errors.
Returns the number of parse errors and warnings during the previous parsing of the XML input.
method num_errors
importing
min_severity type I default 3
returning
value(rval) type I.
This method implements the DOM-generating interface to the parser (optimized). No events are signaled to the client application.
parse() returns only, if the end of the XML input has been reached or if a parse error occured.
During the parsing process, this method creates a DOM (document object model) representation of the XML input and stores it in the document instance, associated with this parser instance during construction.
if_ixml_parser
Returns one of the following return codes:
ixml_mr_parser_ok = 0
The document was parsed successfully.
ixml_mr_parser_error = 0x00030004L
A parse error was encountered while parsing the document.
ixml_mr_parser_fatal_error = 0x00030005L
A fatal parse error was encountered while parsing the document.
method parse
returning
value(rval) type I.
This method implements iterator-like access to the parser (push-model-like interface, returns one event at a time).
parseEvent() has to be called repeatedly until either an exception is signaled (in case of a parse error) or a null-event is returned (if the end of the XML input is reached). Each time the method returns to the caller, the next subscribed event is returned and can be processed.
Use setEventSubscription() to configure the set of events about which a caller of parseEvent() gets notified.
In addition to the event notification, the parser can additionally create a DOM representation of the XML input. Whether this is the case, depends on the current setting of iXMLParser::isDOMGenerating().
if_ixml_parser
Returns the next subscribed event, or null if the end of the XML input is reached.
method parse_event
returning
value(rval) type ref to if_ixml_event.
Specifies whether this parser is supposed to generate a DOM representation of the XML input when parsing via parseEvent() and parseWithHandler(). The specified value has no influence on the DOM generation if the parse() method is used.
if_ixml_parser
True, if the parser is supposed to create a DOM representation, false otherwise.
Returns true if this parser generates a DOM representation of the XML input when parsing, false otherwise.
method set_dom_generating
importing
is_generating type boolean default 'X'
returning
value(rval) type boolean.
This method sets the events, the caller of parseEvent() gets notified about.
if_ixml_parser
All events the client wants to get notified about represented as an OR-combined set of event types (see Event::EventType).
method set_event_subscription
importing
events type I.
Specifies the level of XML namespace-awareness that this parser should apply. When running in namespace-aware mode, the parser implementes XML namespace semantics and splits qualified names into local part and namespace prefix. When running namespace-unaware, qualified names are not detected as such and handled as regular names (see iXMLParser::NamespaceMode).
if_ixml_parser
The level of namespace awareness (see iXMLParser::NamespaceMode)
method set_namespace_mode
importing
mode type I.
Specifies whether this parser is supposed to normalize the DOM representation of the XML input when parsing. When running in normalize mode, the parser strips all whitespace-only character data from the DOM tree generated that is not pure element content. Furthermore, leading and trailing blanks are removed from character data.
if_ixml_parser
True, if the parser is supposed to normalize the DOM representation, false otherwise.
Returns true if this parser is in normalizing mode, false otherwise.
method set_normalizing
importing
is_normalizing type boolean default 'X'
returning
value(rval) type boolean.
Specifies the rules for entity-reference resolution that this parser should apply (see iXMLParser::EntityResolutionMode).
if_ixml_parser
The rules for entity resolution (see iXMLParser::EntityResolutionMode)
Returns true.
method set_resolve_mode
importing
flags type I
returning
value(rval) type boolean.
Specifies whether this parser is supposed to supply default attribute values from the document type definition in non validating mode.
if_ixml_parser
True, if the parser is supposed to supply default attribute values in non validating mode, false otherwise.
method set_supply_attr_defaults
importing
supply type boolean default 'X'.
Specifies whether this parser is supposed to validate the XML Document. When running in validating mode, the parser validates the document against the document type declaration. An XML document is valid if it has an associated document type declaration and if the document complies with the constraints expressed in it.
if_ixml_parser
The validation mode (see iXMLParser::ValidationMode).
Returns true if this parser is in validation mode, false otherwise.
method set_validating
importing
mode type I default '1'
returning
value(rval) type boolean.
Specifies whether this parser is supposed to handle xml:space attributes according to the XML specification. xml:space awareness is only used in conjunction with the setPreserveSpaceElement() and setStripSpaceElement() methods.
if_ixml_parser
True, if the parser is supposed to be xml:space attribute aware, false otherwise. By default, a parser is xml:space attribute unaware.
method set_xml_space_aware
importing
is_xml_space_aware type boolean default 'X'.