Iconara DOM framework

Author:
Theo Hultberg / Iconara
Version:
v2.0

Iconara DOM framework is a Cocoa-framework for accessing, manipulating and outputting XML-data. It's similar to the JDOM and XOM frameworks for Java.

An XML-document can be thought of as a tree of nodes. Nodes can be of different types, an the most common types are elements and text nodes. There are also processing instruction nodes, comment nodes and CDATA-section nodes (escaped text nodes). The whole document is also considered to be a node in itself.

This framework provides access to an XML-document in this way, which is called the Document Object Model, hence DOM. Elements, text and other nodes types can be accessed and manipulated. A document can be created either from a file or programmaticaly by creating and adding node objects. A document can also be written to a file (serialized), and formatted in a way that is suitable.

DOM is a recommendation from the W3C, for more info see http://www.w3c.org.

The framework consist of a number of components: the core API, the core implementation, the builder API, the formatter, the traversal module and the XPath module.

The core API and core implementation are the two most important, and most of the time you can regard these as being one. The core API is defined by a set of protocols defining the different node types and which methods they implement, the node types are node (abstract), document, element, attribute, document fragment, character data (abstract), text, comment, CDATA-section, doctype, processing instruction, attribute and parent. The core implementation is just concrete implementations of these protocols.

The reason for using protocols to define the external API is a question of design; apart for being a clean separation of API and implementation it allows for more than one concrete implementation. There could be, for example, an implementation that saved the data in a database instead of keeping the whole object graph in memory. There is also other DOM or DOM-like implementations for C and Objective-C that could be used as part of this DOM framework, if a wrapper was written. By separating the API from the implementation this becomed much easier to do.

The Objective-C syntax is, in my opinion, a little biased towards classes, protocols don't fit in very well, as the do in Java. Moreover, the names of the core protocols are the same as the names of the core classes, that may be confusing, but I thought it was best to do it that way. You may find the protocol based API a bit annoying, that has not been my intention to do, it is only in the interest of good design.

The builder API defines a common way of creating DOM trees. The builder are implemented as plug-ins to the framework. Currently the only plug-in is a builder that uses the popular open source parser Expat. It is not hard to write implementations for other parsers, for example Apple's NSXML or CFXML parsers, although those two lack namespace support. I would very much like to see contributions in this area. Other parsers that could be wrapped are libxml or Xerces (the C++ version).

The formatter is used to output XML from a DOM tree. The output format can be configured to suit most needs (although not all, I'm afraid).

The traversal module encapsulates a pre- or post-order traversal of the DOM tree, which is useful if your application needs to visit all nodes in a document in order (for example when building a tree-view, pretty-printing, or doing other kinds of processing based on the structure of the tree). It also contains protocols for formally implementing the visitor pattern (which is used in most cases where the traversal is used).

Finally the XPath module enables you to run XPath queries on the DOM tree. The current implementation handles most expressions, but it is not a complete implementation, so look closely at the documentation of the DOMXPath class to see what is and is not possible.

Note:
Iconara DOM is released under the GNU GPL licence, with an exception that allows non-GPL but open source code to use the framework without having to be GPL themselves (see FLOSS.txt). If you want to include the framework in a non-open source application you should contact me and we can discuss alternative licensing. The rationale behind using GPL and not the LGPL or BSD licenses for this framework is based on the notion of quid pro quo. I provide a framework for simplifying your work, and I belive that you should give me due compensation if you want to use it.