Home / Downloads / XML Designer / Help

XML Designer

XML Designer is a software component that enables parsing, navigation, construction, validation, storing and retrieving from different locations of an XML-document.
All software code is written in ANSI C++ programming language using platform-independent approach.
For Windows developers we created COM in-proc server as a wrapper around C++ library.

1. XML parsing

XML Designer is able to parse XML-documents located on local/intranet disks as well as remote/internet files by using HTTP protocol.
If XML-document contains a reference to another resource such as DTD file, then XML Designer will recognize the location and download resource automatically.
XML Designer will also determine a related path to the resources to download.

There are four different cases how XML Designer parses the XML resources using load method:
a. Parse XML-resource as it is without external grammar: load("test.xml", "");
b. Parse XML-resource according to the specified external grammar in DTD format: load("test.xml", "test.dtd");
c. Parse external grammar and create empty document: load("", "test.dtd");
d. Create empty document without external grammar: load("", "");

2. XML navigation

XML Designer encapsulates internal DOM structures and allows users to navigate through document by selecting desirable nodes. The internal "cursor" will be moved according to the user navigation commands:
a. selectDocument method sets the "cursor" at the document node.
b. selectRoot method sets the "cursor" at the root element if the root presents.
c. selectNextSibling method sets the "cursor" at the next XML node at the same level. For example, if current node is an attribute, the next node will also be an attribute.
d. selectPrevSibling method sets the "cursor" at a previous XML node at the same level.
e. selectFirstAttribute method sets the "cursor" at the first attribute if current node is an element with attributes.
f. selectLastAttribute method sets the "cursor" at the last attribute if the current node is an element with attributes.
g. selectAttributeByName method tries to find and set the "cursor" at an attribute with specified name.
h. selectFirstChild method sets the "cursor" at the first child if current node is an element or a document with child nodes.
i. selectLastChild method sets the "cursor" at the last child if current node is an element or a document with child nodes.
j. selectParent method sets the "cursor" at the parent node if current node has a parent, for example, a document node doesn't have a parent.
k. hasAttributes method checks the presence of attributes, current node must be an element.
l. hasChildren method checks the presence of child nodes, current node must be an element or a document.
m. getType method returns a type of the node at the "cursor".
n. getName method returns a name of the node at the "cursor". The name has different meaning for different types. Comment doesn't have the name, for processing instruction the value is PITarget, for others, the name means name.
o. getValue method returns a value of the node at the "cursor". The value has different meaning for different types. For text the value is a text property, for comment it is a text of the comment, for processing instruction it is a chardata, for attribute the value means value, document and element don't have the value.
p. getXPath method helps to understand the current "cursor" position in form of XPATH from root element to the current element like "root/el1/el2/current".
q. selectXPath method tries to find the specified path from a current element to a new "cursor" position in form "current/el1/el2/target".
r. error method returns the desription of the last occured error.

If any navigation method can't find the requested node, then it returns false and the current node remains at the old place. Otherwise the "cursor" will be moved to the new position and the method returns true.

3. XML construction.

XML Designer allows users to build a new XML document or modify loaded external XML resources. Developers can restrict document syntax by applying external grammar. There are three base methods to add new XML-nodes (elements, attributes, comments, processing instructions).
a. addChild method inserts a new node beneath the current node as a last child.
b. insertSibling method inserts the new node right before the current node as a sibling.
c. appendSibling method inserts the new node right after the current node as a sibling.
All construct methods have first three parameters - type, name and value of new inserted xml node.
For element and document types - value parameter is ignored.
For text, comment and CDATA types - name parameter is ignored.
d. merge method inserts an external XML Designer content starting with a "source cursor" beneath a "target cursor" position.

If a construction method fails to insert the new node, then it returns false. Otherwise "cursor" position will be moved at the new inserted node if the last parameter dontMove is false.

4. XML validation.

XML Designer provides two levels of validation. If an external grammar is specified, then only a permitted node can be added to the document. Also a user can call validate method to check grammar model (look at DTD syntax).
a. validate method can check either only current element or recursively.

5. XML persistence.

XML Designer saves the current document on a local disk.
a. save method saves the entire current document on the local disk.

6. XML Designer properties.

XML Designer recognizes few major XML encoding schemas automatically:
- UTF-8
- UTF_16 (big and little ending)
- UCS_4 (all possible byte orders)

However storing documents is possible only in UTF-8 encoding.
XML Designer in form of COM in-proc server can run only in APARTMENT thread model.
There is no need for additional libraries or COM components to be installed for XML Designer full functionality.

7. Performance. Usually, XML Designer demonstrates amazing 10Mb/sec speed during a parsing and 15Mb/sec for storing on the local disk on 1GHz processor. The required memory is just slightly exceeded the initial XML file size ~150%. Such characteristics are outstanding in comparison with the existing parsers.

8. Portability.

The base code including HTTP loader is written in ANSI C++. The Linux version is also available.

9 .Examples:

How to get instance of XMLDesigner?

C++:
xmlaccess acc;
xml_designer* nav = acc.get_xml_designer();

C#:
XmlComLib.XmlDesigner obj = new XmlComLib.XmlDesigner();
if (obj == null)
// handle error

VB:
Dim obj as New XmlComLib.XmlDesigner
If obj is Nothing Then
' handle error
End If

How to parse document without external grammar?

C++:
if (!obj->load("C:\\test.xml", 0))
// handle error here

C#:
if (!obj.load("C:\\test.xml", null))
// handle error here

VB:
If Not obj.load("C:\test.xml", "") Then
' handle error
End If

How to parse document with external grammar?

C++:
if (!obj->load("C:\\test.xml", "C:\\test.dtd"))
// handle error here

C#:
if (!obj.load("C:\\test.xml", "C:\\test.dtd"))
// handle error here

VB:
If Not obj.load("C:\test.xml", "C:\test.dtd") Then
' handle error
End If

How to create empty document with external grammar?

C++:
if (!obj->load(0, "C:\\test.dtd"))
// handle error here

C#:
if (!obj.load(null, "C:\\test.dtd"))
// handle error here

VB:
If Not obj.load("", "C:\test.dtd") Then
' handle error
End If

How to create empty document without external grammar?

C++:
if (!obj->load(0, 0))
// handle error here

C#:
if (!obj.load(null, null))
// handle error here

VB:
If Not obj.load("", "") Then
' handle error
End If

selectDocument

C++:
obj->selectDocument()


C#:
obj.selectDocument();


VB:
obj.selectDocument


selectRoot

C++:
if (!obj->selectRoot())
// handle error
else
// selection succeeded

C#:
if (!obj.selectRoot())
// handle error
else
// selection succeeded

VB:
If Not obj.selectRoot Then
' handle error
Else
' selection succeeded
End If

selectNextSibling

C++:
if (!obj->selectNextSibling())
// handle error
else
// selection succeeded

C#:
if (!obj.selectNextSibling())
// handle error
else
// selection succeeded

VB:
If Not obj.selectNextSibling Then
' handle error
Else
' selection succeeded
End If

selectPrevSibling

C++:
if (!obj->selectPrevSibling())
// handle error
else
// selection succeeded

C#:
if (!obj.selectPrevSibling())
// handle error
else
// selection succeeded

VB:
If Not obj.selectPrevSibling Then
' handle error
Else
' selection succeeded
End If

selectFirstAttribute

C++:
if (!obj->selectFirstAttribute())
// handle error
else
// selection succeeded

C#:
if (!obj.selectFirstAttribute())
// handle error
else
// selection succeeded

VB:
If Not obj.selectFirstAttribute Then
' handle error
Else
' selection succeeded
End If

selectLastAttribute

C++:
if (!obj->selectLastAttribute())
// handle error
else
// selection succeeded

C#:
if (!obj.selectLastAttribute())
// handle error
else
// selection succeeded

VB:
If Not obj.selectLastAttribute Then
' handle error
Else
' selection succeeded
End If

selectAttributeByName

C++:
if (!obj->selectAttributeByName("price"))
// handle error
else
// selection succeeded

C#:
if (!obj.selectAttributeByName("price"))
// handle error
else
// selection succeeded

VB:
If Not obj.selectAttributeByName("price") Then
' handle error
Else
' selection succeeded
End If

selectFirstChild

C++:
if (!obj->selectFirstChild())
// handle error
else
// selection succeeded

C#:
if (!obj.selectFirstChild())
// handle error
else
// selection succeeded

VB:
If Not obj.selectFirstChild Then
' handle error
Else
' selection succeeded
End If

selectLastChild

C++:
if (!obj->selectLastChild())
// handle error
else
// selection succeeded

C#:
if (!obj.selectLastChild())
// handle error
else
// selection succeeded

VB:
If Not obj.selectLastChild Then
' handle error
Else
' selection succeeded
End If

selectParent

C++:
if (!obj->selectParent())
// handle error
else
// selection succeeded

C#:
if (!obj.selectParent())
// handle error
else
// selection succeeded

VB:
If Not obj.selectParent Then
' handle error
Else
' selection succeeded
End If

hasAttributes

C++:
if (!obj->hasAttributes())
// attributes not detected
else
// attributes detected


C#:
if (!obj.hasAttributes())
// handle error
else
// selection succeeded

VB:
If Not obj.hasAttributes Then
' attributes not detected
Else
' attributes detected
End If

hasChildren

C++:
if (!obj->hasChildren())
// children not detected
else
// children detected


C#:
if (!obj.hasChildren())
// handle error
else
// selection succeeded

VB:
If Not obj.hasChildren Then
' children not detected
Else
' children detected
End If

getType

C++:
xmlNodeType type = obj->getType()
switch(type)
{
case ELEMENT_NODE: // this is element
case ATTRIBUTE_NODE: // this is attribute
case TEXT_NODE: // this is text
case CDATA_SECTION_NODE: // this is cdata section
case ENTITY_REFERENCE_NODE: // this is entity reference (part of grammar, not available directly)
case ENTITY_NODE: // this is entity (part of grammar, not available directly)
case PROCESSING_INSTRUCTION_NODE: // this is processing instruction
case COMMENT_NODE: // this is comment
case DOCUMENT_NODE: // this is document itself
case DOCUMENT_TYPE_NODE: // this is build in grammar
case DOCUMENT_FRAGMENT_NODE: // this is fragment of element (not supported)
case NOTATION_NODE: // this is notation (part of grammar, not available directly)
}


C#:
XmlComLib.xmlType type = obj.getType()
switch(type)
{
case XmlComLib.xmlType.ELEMENT_NODE: // this is element
case XmlComLib.xmlType.ATTRIBUTE_NODE: // this is attribute
case XmlComLib.xmlType.TEXT_NODE: // this is text
case XmlComLib.xmlType.CDATA_SECTION_NODE: // this is cdata section
case XmlComLib.xmlType.ENTITY_REFERENCE_NODE: // this is entity reference (part of grammar, not available directly)
case XmlComLib.xmlType.ENTITY_NODE: // this is entity (part of grammar, not available directly)
case XmlComLib.xmlType.PROCESSING_INSTRUCTION_NODE: // this is processing instruction
case XmlComLib.xmlType.COMMENT_NODE: // this is comment
case XmlComLib.xmlType.DOCUMENT_NODE: // this is document itself
case XmlComLib.xmlType.DOCUMENT_TYPE_NODE: // this is build in grammar
case XmlComLib.xmlType.DOCUMENT_FRAGMENT_NODE: // this is fragment of element (not supported)
case XmlComLib.xmlType.NOTATION_NODE: // this is notation (part of grammar, not available directly)
}


VB:
Dim objType as XmlComLib.xmlNodeType
objType = obj.getType
Select Case objType
Case ELEMENT_NODE ' this is element
Case ATTRIBUTE_NODE ' this is attribute
Case TEXT_NODE ' this is text
Case CDATA_SECTION_NODE: ' this is cdata section
Case ENTITY_REFERENCE_NODE: ' this is entity reference (part of grammar, not available directly)
Case ENTITY_NODE: ' this is entity (part of grammar, not available directly)
Case PROCESSING_INSTRUCTION_NODE: ' this is processing instruction
Case COMMENT_NODE: ' this is comment
Case DOCUMENT_NODE: ' this is document itself
Case DOCUMENT_TYPE_NODE: ' this is build in grammar
Case DOCUMENT_FRAGMENT_NODE: ' this is fragment of element (not supported)
Case NOTATION_NODE: ' this is notation (part of grammar, not available directly)
End Select

getName

C++:
const char* name = obj->getName()


C#:
string name = obj.getName()


VB:
Dim objName as String
objName = obj.getName

getValue

C++:
const char* value = obj->getValue()


C#:
string name = obj.getValue()


VB:
Dim objValue as String
objValue = obj.getValue

getXPath

C++:
const char* xPath = obj->getXPath()


C#:
string xPath = obj.getXPath()


VB:
Dim xPath as String
xPath = obj.getXPath

selectXPath

C++:
if (!obj->selectXPath("customid/order/price"))
// handle error
else
// selection succeeded

C#:
if (!obj.selectXPath("customid/order/price"))
// handle error
else
// selection succeeded

VB:
If Not obj.selectXPath("customid/order/price") Then
' handle error
Else
' selection succeeded
End If

How to look through all children and attributes for the current element?

C++:
// looking for attributes
if (obj->selectFirstAttribute())
{
do
{
// read attribute properties
}
while (obj->selectNextSibling());
// return to the current element
obj->selectParent();
}
// looking for children
if (obj->selectFirstChild())
{
do
{
// read child properties
}
while (obj->selectNextSibling());
// return to the current element
obj->selectParent();
}

also the other algorithm is available

// looking for attributes
if (obj->hasAttributes())
{
obj->selectFirstAttribute();
// read attribute properties
while (obj->selectNextSibling())
{
// read attribute properties
}
// return to the current element
obj->selectParent();
}
// looking for children
if (obj->hasChildren())
{
obj->selectFirstChild();
// read child properties
while (obj->selectNextSibling())
{
// read child properties
}
// return to the current element
obj->selectParent();
}


C#:
// looking for attributes
if (obj.selectFirstAttribute())
{
do
{
// read attribute properties
}
while (obj.selectNextSibling());
// return to the current element
obj.selectParent();
}
// looking for children
if (obj.selectFirstChild())
{
do
{
// read child properties
}
while (obj.selectNextSibling());
// return to the current element
obj.selectParent();
}

also the other algorithm is available

// looking for attributes
if (obj.hasAttributes())
{
obj.selectFirstAttribute();
// read attribute properties
while (obj.selectNextSibling())
{
// read attribute properties
}
// return to the current element
obj.selectParent();
}
// looking for children
if (obj.hasChildren())
{
obj.selectFirstChild();
// read child properties
while (obj.selectNextSibling())
{
// read child properties
}
// return to the current element
obj.selectParent();
}


VB:
' looking for attributes
If obj.selectFirstAttribute Then
Do
' read attribute properties
Loop While obj.selectNextSibling
' return to the current element
obj.selectParent
End If
' looking for children
If obj.selectFirstChild Then
Do
' read child properties
Loop While obj.selectNextSibling
' return to the current element
obj.selectParent
End If

also the other algorithm is available

' looking for attributes
If obj.hasAttributes Then
obj.selectFirstAttribute ' read attribute properties
While obj.selectNextSibling
' read attribute properties
Wend
' return to the current element
obj.selectParent
End If
' looking for children
If obj.hasChildren Then
obj.selectFirstChild
' read child properties
While obj.selectNextSibling
' read child properties
Wend
' return to the current element
obj.selectParent
End If

addChild

C++:
if (!obj->addChild(ATTRUBUTE_NODE, "price", "$10.2", false))
// handle error
else
// attribute was added
if (!obj->addChild(COMMENT_NODE, 0, "This is default price", true))
// handle error
else
// comment was added

C#:
if (!obj.addChild(XmlComLib.xmlType.ATTRUBUTE_NODE, "price", "$10.2", false))
// handle error
else
// attribute was added
if (!obj->addChild(XmlComLib.xmlType.COMMENT_NODE, 0, "This is default price", true))
// handle error
else
// comment was added

VB:
If Not obj.addChild(ATTRUBUTE_NODE, "price", "$10.2", FALSE) Then
' handle error
Else
' attribute was added
End If
If Not obj.addChild(COMMENT_NODE, "", "This is default price", TRUE) Then
' handle error
Else
' comment was added
End If

insertSibling

C++:
// assume the current xml node is attribute if (!obj->insertSibling(ATTRUBUTE_NODE, "price", "$10.5", false))
// handle error
else
// attribute was added before current


C#:
// assume the current xml node is attribute if (!obj.insertSibling(XmlComLib.xmlType.ATTRUBUTE_NODE, "price", "$10.5", false))
// handle error
else
// attribute was added before current


VB:
If Not obj.insertSibling(ATTRUBUTE_NODE, "price", "$10.5", FALSE) Then
' handle error
Else
' attribute was added before current
End If

appendSibling

C++:
// assume the current xml node is element
if (!obj->appendSibling(COMMENT_NODE, 0, "the next element is custom preferences", false))
// handle error
else
// comment was added after current element


C#:
// assume the current xml node is element
if (!obj.appendSibling(XmlComLib.xmlType.COMMENT_NODE, 0, "the next element is custom preferences", false))
// handle error
else
// comment was added after current element


VB:
If Not obj.appendSibling(COMMENT_NODE, "", "the next element is custom preferences", FALSE) Then
' handle error
Else
' comment was added after current element
End If

merge

C++:
// assume we got two objects
xmlaccess acc;
xml_designer* src = acc.get_xml_designer();
xml_designer* dest = acc.get_xml_designer();
// fill first object src using load function or addChild/insertSibling/appendSibling methods.
src->selectRoot();
if (!dest->merge(src))
// handle error here

C#:
// assume we got two objects
XmlComLib.XmlDesigner src = new XmlComLib.XmlDesigner();
XmlComLib.XmlDesigner dest = new XmlComLib.XmlDesigner();
if (src == null)
// handle error here
if (dest == null)
// handle error here
// fill first object src using load function or addChild/insertSibling/appendSibling methods.
src.selectRoot();
if (!dest.merge(src))
// handle error here

VB:
// assume we got two objects
Dim src as New XmlComLib.XmlDesigner
Dim dest as New XmlComLib.XmlDesigner
If src is Nothing Then
' handle error here
End If
If dest is Nothing Then
' handle error here
End If
' fill first object src using load function or addChild/insertSibling/appendSibling methods.
src.selectRoot
If Not dest.merge(src) Then
' handle error here
End If

validate

C++:
// assume the current xml node is element if (!obj->validate(true))
// handle error
else
// xml structure is valid


C#:
// assume the current xml node is element if (!obj.validate(true))
// handle error
else
// xml structure is valid


VB:
If Not obj.validate(TRUE) Then
' handle error
Else
' xml structure is valid
End If

save

C++:
if (!obj->save("C:\\clone.xml"))
// handle error
else
// xml file was saved


C#:
if (!obj.save("C:\\clone.xml"))
// handle error
else
// xml file was saved


VB:
If Not obj.save("C:\clone.xml") Then
' handle error
Else
' xml file was saved
End If

error

C++:
const char* error = obj->error()


C#:
string error = obj.error()


VB:
Dim err As String
err = obj.error