iberxml

This document details the capabilities of the iberxml XML library. The library did not warrant separate architecture, user and developer guides, so all information is to be found here.

Introduction

During the design of IberAgents, JDOM was initially used, as it is much simpler than the original DOM specification. However, as time went by, the lack of some features and a number of bugs made it more and more cumbersome.

What we needed was the simplest interface for manipulating XML documents in code. That is how iberxml was started. Over time, as more capabilities were needed, they were added but in a way that did not preclude the original simple XML management.

Online documentation for IberAgents is to be found in the architecture guide, user guide and supported features. The status of the framework contains modifications for iberxml too.

Architecture

All classes gravitate around the com.iberxml.Element object. We have tried to shift as much functionality to other classes as possible, so it is basically the entry point for the user.

Element Contents

An Element may contain many types of things: text, xml comments or other elements. There are also some specialized contents such as CData sections (literal text). All of these inherit from the abstract class com.iberxml.Part. The element thus becomes a container for parts, which is where text, sub-elements... are stored.

An Element may also contain attributes; they are stored separately.

Exception Handling

Internally, iberxml uses com.iberxml.XmlException and derivatives to signal error conditions. However, we did not want to burden users with constant exception handling. Except when parsing, these exceptions are only thrown when absolutely necessary, and only as RuntimeException.

Features

A lot of features are present in this small library.

XML Parsing and Generation

Parsing can be done using just the embedded custom com.iberxml.parse.Parser; however, you can also use a SAX parser with com.iberxml.parse.XMLSaxParser.

Generation can be customized using a com.iberxml.gen.Generator. Basic XML generation can be done with Element.toString().

Namespaces

Namespace support is complete. All namespaces in an element are parsed and stored; when a new entity is added, it may contain a prefix or even a namespace URI.

Two classes, com.iberxml.namespace.QualifiedName and com.iberxml.namespace.PrefixedName provide the necessary connection between a namespace URI and the prefix by which it is represented in a document.

License

iberxml is distributed under the GNU General Public License.

Why Use iberxml

At this point you are probably wondering: why another XML library? The quick answer is: it was not so much trouble, and it was fun. Yet, iberxml has some features that made it worth it.

Memory footprint is quite low even when parsing huge documents. Elements and attributes are indexed in a hash map, so that searches are very fast. Finally, it is free software; you can modify it at will, and you have to distribute source code along with the binaries.

User Guide

This section contains a brief introduction on how to create iberxml elements in code. The result of Element.toString() is shown below each example.

Creating an Element

To create a new element, just pass the element name to the constructor.

	Element element = new Element("bizarre");
		--> <bizarre />

Now you can populate it with more elements:

	element.addElement("world");
		--> <bizarre>
		-->   <world />
		--> </bizarre>
	element.addElement("here", "we are");
		--> <bizarre>
		-->   <world />
		-->   <here>we are</here>
		--> </bizarre>

Elements can also be created directly with some text contents:

	Element element = new Element("bizarre", "world");
		--> <bizarre>world</bizarre>

Or the text can be added later:

	Element element = new Element("bizarre");
	element.addText("world");
		--> <bizarre>world</bizarre>

Attributes can be added at any point.

	Element element = new Element("greetings");
	element.addText("odd people");
	element.addAttribute("type", "international");
		--> <greetings type="international">odd people</greetings>

Traversing Elements

We will use the following element to illustrate this section.

<bizarre type="mine">
  <world />
  <here>we are</here>
</bizarre>

Once we have an element, we can get to any sub-element easily.

	Element sub = element.getElement("world");
		--> <world />
	sub = element.getElement("not-here");
		--> null
	ArrayList list = element.getElements("here");
		--> ( <here>we are</here> )

Likewise with attributes.

	value = element.getAttributeValue("type");
		--> "mine"
	String value = element.getAttributeValue("neither-here");
		--> null

Namespaces

It is a simple task to create elements with namespaces and add things; but namespaces must be defined before the element is generated.

	Element element = new Element("iber:hello");
		--> exception: namespace not found
	Element element = new Element("iber:hello");
	element.addNamespace("iber", "http://iberagents.ib-ia.com/");
		--> <iber:hello />
	element.addAttribute("iber:logo", "contents");
		--> <iber:hello iber:logo="contents"/>

You can also use the classes PrefixedName and QualifiedName to traverse elements with namespaces. For the first you need to know the prefix of a namespace in this element; for the second the URI that defines the namespace. Continuing with the element created above:

	PrefixedName name = new PrefixedName("iber", "logo");
	String value = element.getAttribute(name);
		--> "contents"
	QualifiedName name = new QualifiedName("http://iberagents.ib-ia.com/", "logo");
	value = element.getAttribute(name);
		--> "contents"

Conclusion

Have fun with iberxml. We gratefully accept any contributions from third parties. Please contact us for any discussions, bug reports, or just to say hello.