Select language:

Background documentation 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'.

 

 

 

Was this page helpful to you?