Online documentation - Websydian v6.0 |
Users Guide | Patterns Reference | WebsydianExpress | Search |
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 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.
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.
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.
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. |
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.
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.
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...
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.
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.
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.
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. |
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. |