tXML: Quck Start Guide

Creating an XML document

Creating first XML document

<message>
	Hello, world!
</message>
		
import org.txml.XMLNode;
...

XMLNode node = new XMLNode("message", "Hello, world!");

You can access the name of the XML node by calling getName() method (it will return "message").

The value of the node in our example is string "Hello, world!. One can obtain it by calling getValue() method.

Creating an empty node

<family></family>
		
import org.txml.XMLNode;
...

XMLNode node = new XMLNode("family");

Putting some content in it

<family>
	<dad>
		Father Bear
	</dad>
	<mom>
		Mother Bear
	</mom>
	<child>
		Baby Bear
	</child>
</family>
	
		
import org.txml.XMLNode;
...

public XMLNode createFamily()
{
	XMLNode root = new XMLNode("family");
	root.addNode(new XMLNode("dad", "Father Bear"));
	root.addNode(new XMLNode("mom", "Mother Bear"));
	root.addNode(new XMLNode("child", "Baby Bear"));
	return root;
}

In this example, the root node has content of three children nodes. To iterate through content use getNodeCount() and getNode() methods: 
import org.txml.XMLNode;
...

if(contents.getNodeCount() == 0)
{
	System.out.println("this node does not have any children");
}
else
{
	for(int i = 0; i < content.getNodeCount(); i++)
	{
		XMLNode child = content.getNode(i);
		System.out.println("child name =" + child.getName());
		System.out.println("child value=" + child.getValue());
	}
}

The default conversion to String will output an unformatted XML document (as one, possibly long, string): 
import org.txml.XMLNode;
...

XMLNode node = new XMLNode("message", "Hello, world!");
System.out.println(node);
...
		
<message>Hello, world!</message>

To get a nicely formatted output use the following code: 
import org.txml.XMLNode;
...

XMLNode node = new XMLNode("message", "Hello, world!");
System.out.println(node.toString(""));
...
		
<message>
	Hello, world!
</message>

Parsing XML document

Following code parses XML file and prints parsed tree to the standard output: 
import org.txml.XMLNode;
import org.txml.XMLParser;
...

InputStream input = new FileInputStream("data.xml");
XMLNode tree = XMLParser.parse(input);
System.out.println("tree: \n" + tree.toString("\t"));

The catch: since tXML does not implement the complete XML syntax, you might not be able to parse your XML document successfully. The good news is that tXML can parse any document created by tXML (big surprise!;).

Searching XML document

tXML uses XPath syntax to select sub-set of nodes from an XML document. If you do not know what XPath is, you'll get an idea from the following examples. Again, tXML does not implement XPath (which is rather involved). Instead, it uses the sub-set of its syntax to satisfy practically important queries. By convention, the result of the selection query is returned as a content of <select> node.

Query: /family/child
Input: Output: 
<family>
	<dad>Father Bear</dad>
	<mom>Mother Bear</mom>
	<child>Baby Bear</child>
</family>
		
<select>
	<child>Baby Bear</child>
</select>
		
		XMLNode input = ... // get input tXML tree
		XMLNode output = input.select("family/child");
In English, the query above tells engine to select all XML nodes with the name "child" from the root-level node named "family". Note that the result of selection is put into <select> container.

Query: /family/*
Input: Output: 
<family>
	<dad>Father Bear</dad>
	<mom>Mother Bear</mom>
	<child>Baby Bear</child>
</family>
		
<select>
	<dad>Father Bear</dad>
	<mom>Mother Bear</mom>
	<child>Baby Bear</child>
</select>
		
		XMLNode input = ... // get input tXML tree
		XMLNode output = input.select("family/*");

The wildcard '*' matches any name. Therefore, all children of "root" got selected.

Query: //*
Input: Output: 
<family>
	<dad>Father Bear</dad>
	<mom>Mother Bear</mom>
	<child>Baby Bear</child>
</family>
		
<family>
	<family>
		<dad>Father Bear</dad>
		<mom>Mother Bear</mom>
		<child>Baby Bear</child>
	</family>
	<dad>Father Bear</dad>
	<mom>Mother Bear</mom>
	<child>Baby Bear</child>
</family>
		
		XMLNode input = ... // get input tXML tree
		XMLNode output = input.select("//*");

The pattern '//' will trigger search on any level. Hence, all nodes on all levels got selected.