Interface if_ixml
The iXML class is the origin from
where to start with the iXML libary. It serves both as a factory for the
elementary objects Document, Parser and StreamFactory and as a "handle"
defining the processing context - or session - of subsequent API
calls.
Depending on the runtime environment, the iXML class is implemented in two separate ways internally: On an SAP NW AS ABAP, in which object instances might switch processes, the iXML class itself can be moved from one work process to the other. Therefore all data allocated within the class has to be allocated dynamically in the Extended Memory area. A typical example would be Name and Atom tables that have to be moved around with the iXML instance itself. In order to make this concept work, each session has to create its own iXML instance.
One of the implications of this approach is the fact, that documents of different sessions cannot share common Name and Atom objects. In order to be more memory efficient in environments where Documents cannot move between processes, a different solution is implemented: Here iXML implements a singleton, effectively sharing common objects similar to global variables between all processing contexts or session. This means e.g. that two Document instances share the same Name and Atom tables.
enumerations
· iXMLType
methods
· activate
· create
· create_document
· create_encoding
· create_parser
· create_renderer
· create_stream_factory
· get_version
· has_feature
· set_conversion_behaviour
enumeration iXMLType
The values of the iXMLType enumeration are used to give the library a hint on how the iXML factory is going to be used with XML documents. This is done for optimization reasons.
interface
if_ixml
values
co_multiple_documents = 0x00000000L
This iXML factory is used for more than one XML document (default).
co_single_document = 0x00000001L
This iXML factory is used for a single XML document only.
co_single_small_document = 0x00000002L
This iXML factory is used for a single, small XML document only.
co_single_large_document = 0x00000003L
This iXML facotry is used for a single, large XML document only.
abap signature
constants:
co_multiple_documents type I value 0,
co_single_document type I value 1,
co_single_small_document type I value 2,
co_single_large_document type I value 3.
method activate
Activates this iXML instance.
This method must only be called in an ABAP kernel environment, where separate iXML instances are used for separate sessions. In a normal process environment only a single iXML instance (singleton) exists per process and is shared by all clients. Calling activate() in such an environment is allowed, but has no effect internally.
interface
if_ixml
abap signature
method activate.
method create
Creates an instance of the iXML class and returns an interface pointer to the instance. This method must only be called in an ABAP kernel environment.
interface
if_ixml
parameters
type [ default 0 ]
One of the iXMLType values indicating the type of use (optimization hint)
return value
Returns an interface pointer for the newly created iXML instance.
abap signature
class-method create
importing
type type I default 0
returning
value(rval) type ref to if_ixml.
method create_document
This method creates a new Document instance and returns an interface pointer to this instance.
interface
if_ixml
return value
Returns an interface pointer to the newly created document instance.
abap signature
method create_document
returning
value(rval) type ref to if_ixml_document.
method create_encoding
This method creates a new Encoding instance and returns an interface pointer to this instance.
interface
if_ixml
parameters
character_set
The name of the character set for the new encoding.
byte_order
The byte order to use when representing characters in this encoding (see AEncoding::ByteOrder).
return value
Returns an interface pointer to the newly created encoding instance.
abap signature
method create_encoding
importing
character_set type string
byte_order type I
returning
value(rval) type ref to if_ixml_encoding.
method create_parser
This method creates a new Parser instance and returns an interface pointer to this instance.
interface
if_ixml
parameters
stream_factory
The stream factory to be used by the parser for creation of streams, if external entities are referenced in the parsed document.
istream
The XML input stream to parse.
document
The document instance into which to parse the XML input stream. Even if no DOM representation of the XML document is to be created, a Document instance is required to store information about the XML document during the parsing step.
return value
Returns an interface pointer to the newly created XML parser instance.
abap signature
method create_parser
importing
stream_factory type ref to if_ixml_stream_factory
istream type ref to if_ixml_istream
document type ref to if_ixml_document
returning
value(rval) type ref to if_ixml_parser.
method create_renderer
This method creates a new Renderer instance and returns an interface pointer to this instance.
interface
if_ixml
parameters
ostream
The XML output stream into which to render.
document
The document instance to render into the XML output stream.
return value
Returns an interface pointer to the newly created XML renderer instance.
abap signature
method create_renderer
importing
ostream type ref to if_ixml_ostream
document type ref to if_ixml_document
returning
value(rval) type ref to if_ixml_renderer.
method create_stream_factory
This method creates a new StreamFactory instance and returns an interface pointer to this instance.
interface
if_ixml
return value
Returns an interface pointer to the newly created stream factory instance.
abap signature
method create_stream_factory
returning
value(rval) type ref to if_ixml_stream_factory.
method get_version
Returns the version information of this iXML implementation as an integer, where the version is represented as 10 * major version + minor version (e.g. 1.0 -> 10).
interface
if_ixml
return value
Returns the version of this iXML implementation.
abap signature
method get_version
returning
value(rval) type I.
method has_feature
Test if the DOM implementation implements a specific feature.
interface
if_ixml
parameters
feature
The package name of the feature to test. In Level 1, the legal values are "HTML" and "XML" (case-insensitive).
version
This is the version number of the package name to test. In Level 1, this is the string "1.0" If the version is not specified, supporting any version of the feature will cause the method to return true.
return value
Returns true if the specified feature is supported.
abap signature
method has_feature
importing
feature type string
version type string
returning
value(rval) type boolean.
method set_conversion_behaviour
This method sets the conversion behaviour to be used at all the interfaces of iXML when passing strings to ABAP.
interface
if_ixml
parameters
fail_on_error [ default ' ' ]
True if a conversion error should result in an exception
replacement_char [ default '#' ]
Replacement character to be used for all non-convertable characters (US-ASCII character range only!)
codepage [ default '*' ]
SAP codepage number or * to use the current ABAP codepage
return value
Returns one of the following return codes:
ixml_mr_dom_ok = 0
The specified codepage has been set.
ixml_mr_dom_invalid_arg = 0x00020003L
One of the arguments is invalid.
abap signature
method set_conversion_behaviour
importing
fail_on_error type boolean default ' '
replacement_char type ixml_c1 default '#'
codepage type string default '*'
returning
value(rval) type I.