Interface if_ixml_parser
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.
enumerations
· EntityResolutionMode
· NamespaceMode
· ValidationMode
methods
· 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
enumeration EntityResolutionMode
The values of the EntityResolutionMode enumeration are used to differentiate the levels of entity resolution the parser offers.
interface
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.
abap signature
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.
enumeration ValidationMode
The values of the ValidationMode enumeration are used to differentiate the levels of DTD validation the parser offers.
interface
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.
abap signature
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.
enumeration NamespaceMode
The values of the NamespaceMode enumeration are used to differentiate the levels of namespace-awareness the parser offers.
interface
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.
abap signature
constants:
co_namespace_unaware type I value 0,
co_prefix_aware type I value 1,
co_namespace_aware type I value 2.
method add_preserve_space_element
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.
interface
if_ixml_parser
parameters
name [ default '*' ]
The name of the element
prefix [ default '' ]
The elements namecpace prefix or null.
return value
Returns true if the element is succesfully added
abap signature
method add_preserve_space_element
importing
name type string default '*'
uri type string default ''
returning
value(rval) type boolean.
method add_strip_space_element
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.
interface
if_ixml_parser
parameters
name [ default '*' ]
The name of the element
prefix [ default '' ]
The elements namecpace prefix or null.
return value
Returns true if the element is succesfully added
abap signature
method add_strip_space_element
importing
name type string default '*'
uri type string default ''
returning
value(rval) type boolean.
method get_error
This method returns the error or warning for the given index, if errors or warnings where issued during the previous parsing process.
interface
if_ixml_parser
parameters
index
The number of the error or warning to return (0..numErrors()-1).
min_severity [ default 3 ]
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.
return value
Returns the parse error for the given index (0..numErrors()-1).
abap signature
method get_error
importing
index type I
min_severity type I default 3
returning
value(rval) type ref to if_ixml_parse_error.
method get_event_subscription
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).
interface
if_ixml_parser
return value
The currently set event types for notification.
abap signature
method get_event_subscription
returning
value(rval) type I.
method get_namespace_mode
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.
interface
if_ixml_parser
return value
Returns the level of namespace awareness currently configured (see iXMLParser::NamespaceMode)
abap signature
method get_namespace_mode
returning
value(rval) type I.
method has_event_subscription
This method returns whether the given event is included in the currently subscribed events.
interface
if_ixml_parser
parameters
event
The event for which to check subscription (see iXMLEvent::EventType).
return value
Returns true, if the given event is included in the currently subscribed events, false otherwise.
abap signature
method has_event_subscription
importing
event type I
returning
value(rval) type boolean.
method is_dom_generating
Tests if this parser generates a DOM representation of the parsed XML input.
interface
if_ixml_parser
return value
Returns true if this parser generates a DOM representation of the XML input when parsing, false otherwise
abap signature
method is_dom_generating
returning
value(rval) type boolean.
method is_normalizing
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.
interface
if_ixml_parser
return value
Returns true if this parser runs in normalize mode, false otherwise
abap signature
method is_normalizing
returning
value(rval) type boolean.
method is_supply_attr_defaults
Tests if this parser is supplying default attribute values from the document type definition in non validating mode.
interface
if_ixml_parser
return value
True, if the parser is supplying default attribute values in non validating modes, false otherwise.
abap signature
method is_supply_attr_defaults
returning
value(rval) type boolean.
method is_validating
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.
interface
if_ixml_parser
return value
Returns true if this parser is in validation mode, false otherwise.
abap signature
method is_validating
returning
value(rval) type boolean.
method is_xml_space_aware
Tests if this parser is aware of xml:space attributes.
interface
if_ixml_parser
return value
True, if the parser is aware of xml:space attributes, false otherwise.
abap signature
method is_xml_space_aware
returning
value(rval) type boolean.
method num_errors
This method returns the number of parsing errors and warnings that occured during the parsing process of one of the parse methods.
interface
if_ixml_parser
parameters
min_severity [ default 3 ]
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.
return value
Returns the number of parse errors and warnings during the previous parsing of the XML input.
abap signature
method num_errors
importing
min_severity type I default 3
returning
value(rval) type I.
method parse
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.
interface
if_ixml_parser
return value
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.
abap signature
method parse
returning
value(rval) type I.
method parse_event
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().
interface
if_ixml_parser
return value
Returns the next subscribed event, or null if the end of the XML input is reached.
abap signature
method parse_event
returning
value(rval) type ref to if_ixml_event.
method set_dom_generating
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.
interface
if_ixml_parser
parameters
is_generating [ default 'X' ]
True, if the parser is supposed to create a DOM representation, false otherwise.
return value
Returns true if this parser generates a DOM representation of the XML input when parsing, false otherwise.
abap signature
method set_dom_generating
importing
is_generating type boolean default 'X'
returning
value(rval) type boolean.
method set_event_subscription
This method sets the events, the caller of parseEvent() gets notified about.
interface
if_ixml_parser
parameters
events
All events the client wants to get notified about represented as an OR-combined set of event types (see Event::EventType).
abap signature
method set_event_subscription
importing
events type I.
method set_namespace_mode
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).
interface
if_ixml_parser
parameters
mode
The level of namespace awareness (see iXMLParser::NamespaceMode)
abap signature
method set_namespace_mode
importing
mode type I.
method set_normalizing
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.
interface
if_ixml_parser
parameters
is_normalizing [ default 'X' ]
True, if the parser is supposed to normalize the DOM representation, false otherwise.
return value
Returns true if this parser is in normalizing mode, false otherwise.
abap signature
method set_normalizing
importing
is_normalizing type boolean default 'X'
returning
value(rval) type boolean.
method set_resolve_mode
Specifies the rules for entity-reference resolution that this parser should apply (see iXMLParser::EntityResolutionMode).
interface
if_ixml_parser
parameters
mode
The rules for entity resolution (see iXMLParser::EntityResolutionMode)
return value
Returns true.
abap signature
method set_resolve_mode
importing
flags type I
returning
value(rval) type boolean.
method set_supply_attr_defaults
Specifies whether this parser is supposed to supply default attribute values from the document type definition in non validating mode.
interface
if_ixml_parser
parameters
supply [ default 'X' ]
True, if the parser is supposed to supply default attribute values in non validating mode, false otherwise.
abap signature
method set_supply_attr_defaults
importing
supply type boolean default 'X'.
method set_validating
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.
interface
if_ixml_parser
parameters
mode [ default '1' ]
The validation mode (see iXMLParser::ValidationMode).
return value
Returns true if this parser is in validation mode, false otherwise.
abap signature
method set_validating
importing
mode type I default '1'
returning
value(rval) type boolean.
method set_xml_space_aware
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.
interface
if_ixml_parser
parameters
is_xml_space_aware [ default 'X' ]
True, if the parser is supposed to be xml:space attribute aware, false otherwise. By default, a parser is xml:space attribute unaware.
abap signature
method set_xml_space_aware
importing
is_xml_space_aware type boolean default 'X'.