Online documentation - Websydian v6.0

Users Guide | Patterns Reference | WebsydianExpress | Search

 

Parser Compatibilities


Introduction

Websydian TransacXML uses XML parsers from different vendors in order to support XML processing on the Java and Windows platforms. Currently the Websydian TransacXML implementation uses the Xerces2 Java parser from Apache Organization and the Microsoft XML Parser.

Even though both parsers conform to the DOM standard there are some differences in the behavior of the two implementations. Websydian TransacXML tries to hide these changes for the developer but this is unfortunately not always possible.

This document describes the platform dependent aspects of using the TransacXML patterns. Usually this document applies when an application that uses TransacXML is moved from one platform to another - and thereby uses another parser.

White Spaces

White spaces is the term for the tab, space, and newline characters that occur in a document. White spaces that occurs between elements are also part of the XML document. This means that white spaces are treated as text nodes in the document (see example).

 

...
<Elem>Text data 1</Elem>
<Elem>Text data 2</Elem>
...

If an XML document contains the above text it will result in the following nodes being created in the XML tree structure:

The above figure shows that the newline character between the two Elem elements is treated as an independent node. Typically this is not what is intended as the newline character is only inserted for readability.

...
<Elem>Text data 1</Elem><Elem>Text data 2</Elem>
...

To give a correct node tree the XML file should contain the text above.

The parser can be configured to ignore or preserve these white spaces. Currently the two parsers are not setup by default to behave in the same way regarding handling of white spaces. Please refer to the following sections for details.

  This implies that if an application is moved from Java to Windows or vice versa then the application might not behave in the same way unless the parser options is set to the same for both platforms.

Java Parser

By default the parsers are set to not to validate documents. For the Java parser this implies that it is not capable of ignoring white spaces since the ignore white space option requires that the validation option is set to true.

To enable ignoring of white spaces the following options should be set:

See the documentation of XmlParsers.JavaParser.SetOption for information on how to do this.

MSXML Parser

The parser ignores white spaces by default. To change this set the option PreserveWhiteSpace to True.

See the documentation of XmlParsers.MSXML.SetOption for information on how to do this.

Namespaces

Websydian TransacXML contains functions that support namespaces as specified by the DOM Level 2 standard. Unfortunately the MSXML parser does not support namespaces as specified by the DOM standard, and this gives some differences in how Websydian TransacXML supports namespaces on the Java platform and on Windows.

The table below explains where the MSXML parser does not conform to the DOM Level 2 standard regarding namespaces.

Function Comment
DomInterfaces.Document.createAttributeNS Behaves as specified by the DOM standard.
DomInterfaces.Document.createElementNS
DomInterfaces.Node.prefix_get
DomInterfaces.Node.namespaceURI
DomInterfaces.Node.localName_get
DomInterfaces.Document.ImportNode
DomInterfaces.Element.getAttributeNS
DomInterfaces.Element.getAttributeNodeNS
DomInterfaces.Document.getElementsByTagNameNS These functions are not supported properly by MSXML and do therefore not behave as specified by the DOM level 2 standard on the Windows platform.

The functions are supposed to take a namespace string as an input. Instead of the namespace string this parameter should be set to the prefix of the node.

 

DomInterfaces.Element.getElementByTagNameNS
DomInterfaces.Element.removeAttributeNS
DomInterfaces.Element.setAttributeNodeNS
DomInterfaces.Element.setAttributeNS
DomInterfaces.NamedNodeMap.getNamedItemNS
DomInterfaces.NamedNodeMap.removeNamedItemNS
DomInterfaces.NamedNodeMap.setNamedItemNS
DomInterfaces.Node.prefix_set Not supported by the MSXML parser.

NamedNodeMap

The NamedNodeMap interface is used to hold a collection of nodes. However, since the DOM specification does not define any specific order of the nodes in this collection, code that indexes a NamedNodeMap collection should not rely on the order of the nodes.

If this advice is not followed then please remember that the behavior of the application might change if the application is changed to use another parser, e.g. from MSXML to the Java parser.

The DOM specification also defines a NodeList collection where the order of the nodes is part of the specification, so in these cases it is safe to write code that relies upon the order of the nodes in the NodeList collection.

Null Values

According to the DOM specification some methods can return a Null value. CA Plex cannot represent Null values so TransacXML uses alternative methods. Please see the following sections on how Null values are handled by TransacXML.

Node Null Values

Many methods in the DOM specification can return a node; e.g. Element.getAttributeNode(). However in some cases it is not possible to return a node, e.g. if the specified attribute node does not exist, and then the DOM specification states that a null value should be returned.

In Websydian DOM this null value translates to the number 0 and the value object NULL contains this literal value when comparing the return value. E.g.

if DomInterfaces.Element.getAttributeNode/Output<objectattr> != <ObjectAttr.NULL>

... do something with the attribute node...

String Null Values

For methods that return a string value some of these will return a null value if the string object does not exist. This happens for the Notation.publicId attribute. In TransacXML string null values are not supported so the Notation.publicId_get function returns the empty string in this case.

The reason for this is that the CA Plex runtime does not support null values for string objects, but also that the MSXML parser on this issue does not conform with the DOM specification, because it returns the empty string when a null should be returned.

Error Codes

All call to DOM functions return a status code in the field ExceptionCode. A value of 0 means that the call succeeded. Any other value indicates an error.

DOM Error Codes

The DOM error codes is in the range 1 - 15 and a description of each of the DOM error codes can be found here.

If a function returns an error code in the above range, the function can be looked up here in order to find out why the call failed.

E.g. if DomInterfaces.Document.createEntityReference returned error code 5 one looks up here and finds that this is the error INVALID_CHARACTER_ERR. In the specification for createEntityReference it can be seen that this error occurs if the name parameter contains an illegal character.

Java Error Codes

100 A NullPointerException occurred. This error should not occur and you should contact Soft Design if you encounter this error.
101 The DOM implementation uses a reference pointer to access nodes in an internal store. This error happens if a reference pointer is used in the wrong context. E.g. if Document.createComment is used on a reference pointer to an Element node (should be a Document node).
102 Happens if the DOM implementation does not know the reference pointer used as input to a function. Typically this happens if the null reference (0) is used as input to a function.
103 An error occurred while loading a document. Retrieve the error description for details.
104 An error occurred while trying to save a document. Retrieve the error description for details.
105 Returned by XPath.selectNodes and XPath.selectSingleNode if they failed in resolving the given XPath expression.
106 A call was made to DomServices.ErrorPop but the error stack is empty.

Windows Error Codes

4097 Error An unexpected error occurred in a DOM function. Lookup the error description for details.
4098 InvalidArgument An illegal value was used. E.g. a negative numeric where a positive was expected.
4099 UnableToLoadLibrary Unable to load the Websydian TransacXML dll (WsydXml11.dll). Please make sure that this dll is in the application folder or in the system path.
4100 UnableToLoadLibraryFunction Not used.
4101 InitializationError Unable to initialize the COM library or the initialization function (DomServices.InitializeDom) has been called too many times without any calls to the DomServices.TerminateDom function.
4102 CreateDocumentFailed The call to DomServices.CreateDocument failed. This can happen if the DomServices.InitializeDOM has not been called before this function or if the MSXML parser is not installed on the machine.
4103 OutOfMemory Unable to allocate memory. Please increase memory resources.
4104 CouldNotObtainHashCode Unable to calculate a reference pointer for the specified interface.
4105 GlobalXMLElementStoreNullPointer Illegal null pointer to the internal reference store. Occurs if any of the DOM functions are invoked before DomServices.InitializeDom is called.
4106 XMLElementStoreElementNullPointer Null reference used when a reference to an XML node was expected.
4107 IllegalObjectStoreReference A reference to a document was not valid. This typically happens if the null reference (0) was used for an object store reference.
4108 XMLElementStoreNotFound Could not find the document object.
4109 IllegalObjectReference A reference to a node was not valid. This typically happens if the null reference (0) was used as a reference to a DOM object.
4110 XMLElementStoreElementNotFound Could not find the XML element based on the given reference pointer. This can happen if a reference from one document is used in another document.
4111 XMLStringNullPointer Not used.
4112 XMLElementStoreElementNotDeleted Could not delete an XML element from the reference store.
4113 XMLElementStoreNotEmpty Tried to delete a document that still contained element references.
4114 XMLElementsNotEqual Two different XML elements use the same reference pointer.
4115 NotAValidNode The XML element is not a Node object.
4116 NotAnDocumentElement The XML element is not a Document object.
4117 NotAnElementNode The XML element is not an Element object.
4118 NotAnAttributeElement The XML element is not an Attribute object.
4119 NotANotationElement The XML element is not a Notation object.
4120 NotAPIElement The XML element is not a Processing Instruction object.
4121 NotACharacterDataElement The XML element is not a Character Data object (Text, CDataSection, or Comment).
4122 NotADocumentTypeElement The XML element is not a Document Type object.
4123 NotAnEntityElement The XML element is not an Entity element.
4124 ElementStoreElementNotNode The XML element is not a valid XML node.
4125 ElementStoreElementNotNodeList The XML element is not a Node List object.
4126 ElementStoreElementNotNodeMap The XML element is not a Named Node Map object.
4127 ElementStoreElementNotImplementation The XML element is not a DOM Implementation object.
4128 ErrorStackFull The error stack is full.
4129 ErrorStackEmpty The error stack is empty. Happens if DomServices.ErrorPop is called and there are no error messages to retrieve.
4130 SaveFailed Unable to save the XML document.
4131 AppendDataFailed Call to CharacterData.appendData failed.
4132 DeleteDataFailed Call to CharacterData.deleteData failed.
4133 InsertDataFailed Call to CharacterData.insertData failed.
4134 ReplaceDataFailed Call to CharacterData.replaceData failed.
4135 NormalizeFailed Call to Element.normalize failed.
4136 RemoveAttributeFailed Call to Element.removeAttribute failed.
4137 SetAttributeFailed Call to Element.setAttribute failed.
4138 InterfaceNullPointer A null pointer was used when a pointer to an XML COM interface was expected.
4139 InvalidInterfaceType The XML COM interface did not have a valid node type.
4140 OperationNotSupported It is illegal to set the prefix of a node in the MSXML parser (Node.prefix_set).
4141 OptionNotSupported The option specified for XmlParsers.MSXML.SetOption is not supported.
4142 SetOptionFailed Unable to set the specified option in the function XmlParsers.MSXML.SetOption.
4143 DLLNotLoaded DomServices.TerminateDom is called without any previous calls to DomServices.InitializeDom.
4144 NotATextNode The XML element is not a text object.