Xparse-J - XML tools - exploring XML

Xparse-J 1.0 User documentation

What is Xparse-J?

Xparse-J aspires to be the smallest Java XML parser on the planet.

What is Xparse-J good for?

Xparse-J favors compactness over conformance, so it is mainly useful for being embedded in Java applets for simple XML processing tasks, such as parsing RSS as demonstrated in RSSApplet.

Where does Xparse-J come from?

Xparse-J is a literal translation of Xparse, an XML parser in 5k of JavaScript, into Java. I added a helper class JSArray to mimic the Javascript array built-in data structure.

What does Xparse-J do?

Xparse-J reads XML documents from a given string and presents the resulting document as a tree structure comprised of com.exploringxml.xml.Node and com.exploringxml.xml.JSArray. Both Node and JSArray have basic functionality for navigating the document tree and accessing its data. All character encodings that are supported by Java can be processed.

What doesn't Xparse-J do?

Xparse-J does not conform to any standard XML API such as SAX or DOM. Most of their functionality is not needed for simple XML processing tasks, and would substantially increase the size of the parser. If you favor conformance over compactness, have a look at Aelfred and TinyXML, among others. The parser does not read DTDs and the error handling is minimal, so presenting it with documents that have been checked before, e.g. on the server side, is recommended.

How do I incorporate Xparse-J into my applet / application?

Incorporating Xparse-J into your own project is fairly simple:

In binary form:

Get the class jar file from the download section
Add the jar file to your project's CLASSPATH

In source form:

Get the source zip file from the download section
Extract it in your project's source directory
Add the source files to your project

How do I use Xparse-J?

Xparse-J consists of only three classes:

The parser main class: Xparse
The node class making up the XML document: Node
The array class holding child elements, attributes etc.: JSArray

The most important function for reading a document is Xparse.parse(). It takes the string containing the XML document as the sole argument and returns the root node of the parsed XML document.

A node can be navigated using Node.find(path, occurrance), which finds the n-th occurrance of a child node matching the supplied path expression. The path syntax mirrors XPath abbreviated syntax, looking like directory arguments, e.g. "/rss/item/title" specifying the title element of an RSS item.

Every node contains a java.util.Hashtable of attributes, which can be queried and enumerated in the standard Java way. The JSArray member named contents contains the set of child nodes.

JSArray is using a java.util.Vector and offers the typical getter and setter functions JSArray.getElementAt(index) and JSArray.selElementAt(index, object).

Can you give me an example?

Sure. RSSApplet is a small, configurable applet for displaying news in the RSS format, which is derived from XML. The code for loading the document is:

    // read XML document from URL into a string
    URL u = new URL("https://my.machine.com/my/URL");
    InputStreamReader r = new InputStreamReader(u.openStream());
    StringBuffer sb = new StringBuffer();
    int c;
    while ((c = r.read()) != -1) {
      sb.append((char)c);
    }
    // parse string and build document tree
    root = new Xparse().parse(sb.toString());

To find the root node of the RSS document, which could either be rss or RDF, one would say:

    int occur[] = {1};
    Node doc = root.find("RDF", occur);
    if (doc == null) doc = root.find("rss", occur);
    if (doc == null) throw new Exception("<RDF> or <rss> missing, is this an RSS file?");

Extracting the title of the RSS channel would work like this:

    int occur[] = {1, 1};
    Node n = doc.find("channel/title", occur);
    if (n == null) throw new Exception("<channel><title> missing.");
    String channelTitle = n.getCharacters();
    System.out.println("Channel: " + channelTitle);

Where is the Javadoc of Xparse-J?

Right here.

What is the licence of Xparse-J?

Xparse-J is published under the GNU Public License. Feel free to use it in your projects.

Where do I send feedback, suggestions, gripes?

When you are using Xparse-J, I'd like to hear from you. Just send me feedback.

Where can I find useful information on XML?

Congratulations, you've come to the right place ;-)