Quick: XML Made Easy

XML offers a rich and extensible form for representing data, based on a simple idea: tagged text.

Quick offers a way to convert XML files into a structure of objects, using the classes of your choice.

Quick can generate new classes, when needed. It has an simple API. And it does not complicate your programs in any way. Quick will work with most of your code, unmodified.

To use Quick, you will need to learn some XML. And you will need to learn a little about binding schema.

Quick is Open Source. The CVS repository can be found at 
 
 

Contents

• What is XML? (A Simplified View)
• What is Quick?
• Data-Centric Programming
• QDML and the List Example
• QJML, a Java Binding Schema
• Exploring the Quick API
  • Creating a List Document
  • Processing a List Document
• The Quick Internal Markup Language (QIML)
• Getting Started with Quick
• The Quick Development Kit (QDK)
  • Converting a DTD to XML
  • Converting a DTD to a QDML Schema
  • Converting QDML to QJML
  • The QJML Wizard
  • Generating Java classes from QJML
  • Converting QJML to QIML
  • Generating DTDs
  • Looking Inside--Quick's own QIML file
• Links
• Support

     <address>
          <name>JXML, Inc.</name>
          <street>17 Trowbridge St., Apt 17</street>
          <city>Cambridge</city>
          <state>MA</state>
          <zip>02138</zip>
     </address>

But instead of thinking of XML as tagged text, it is better to think of it as a syntax for representing various types of data, where each type of data must conform to a particular model. For the above example, we could say that we have a data model with 6 elements:

• Address: Contains 5 elements: "name", "street", "city", "state", and "zip".
• Name: The name of a person or company.
• Street: The street address.
• City: The name of a city.
• State: A 2-letter State code.
• Zip: A 5-digit zip code.

One way to define the data model for an XML markup language is to use a DTD, which deals mostly with the structure of an XML document. Here's the DTD for the data model we defined above:

     <!ELEMENT address (name,street,city,state,zip)>
     <!ELEMENT name (#PCDATA)>
     <!ELEMENT street (#PCDATA)>
     <!ELEMENT city (#PCDATA)>
     <!ELEMENT state (#PCDATA)>
     <!ELEMENT zip (#PCDATA)>

• An XML document is a file of tagged text.
• It is relatively easy for a program to extract information from an XML document.
• XML is a syntax for representing various types of data.
• XML is a family of markup languages which use the same syntax.
• An XML markup language has a data model which defines the content of each element in that language.
• A DTD is one way to define the data model of an XML markup language.
• DTDs deal mostly with the structure of an XML document.

Quick does not use XML DTDs, but uses a schema language, QJML, to define markup languages and their relationship to Java classes. Once you have specified an XML markup language in QJML, you can use Quick to perform a number of activities:

• Validate the structure and content of an XML document.
• Convert XML documents into structures of application-specific objects.
• Convert structures of objects into XML.
• Convert a structure of objects into another structure based on a different set of classes.

• XML namespaces and
• Mixing text and elements at the same level within the content of another element (MIXED content).

Quick also includes a wild-card facility to support the processing of documents which contain undefined elements.

But perhaps the most important feature of Quick is its support for validating the content of an XML document. This is handled by the inclusion of programmer-supplied JavaBean PropertyEditors in the QJML binding schema.

The design goals of Quick were:

1. Make it easy to use without limiting its usefulness, and
2. Make it easy to learn.

In this section we covered the key features of Quick.

 
 

When developing programs which use XML documents to exchange data, one of the first steps is to design the data model for those documents.

Once the data model has been specified, work can then proceed on the implementation of the Java classes for the objects which comprise the internal representation of the XML documents. As an internal representation, these objects need to correspond closely to the various elements and data items contained by the XML documents.

Indeed, when developing a program which exchanges XML documents with other programs, the data model specification will either be a cooperative effort, since it impacts the design of all the programs participating in those exchanges, or the data model specification will have already been completed.

In contrast, when using XML documents as a file format for persistant data, fewer developers will be involved in the specification of the data model. But even in this case, the data model should not be specific to a particular version of the program that produces it. Rather, the data model should reflect the overall application.

There are two advantages to using an application-based data model for persistant data (instead of using a data model that is specific to the implementation of the program which produces the persistant data):

• Less effort will be needed for a new version (or an alternative implimentation) of the program to access the old data; and
• Less effort will be needed to use the data in ways that were not previously anticipated. (This often happens with successful projects.)

In this section, the key point covered is the importance of designing an XML data model, rather than deriving the data model from the design of the program.

 
 

Here is a sample of an XML document, a simple list, that we would like to process:

    <list>
        <item>XML should be easy to use.</item>
        <item>Quick keeps it simple, too.</item>
    </list>

• List: Contains a repeating "item" element.
• Item: Contains a line of text.

    <!ELEMENT list (item*)>
    <!ELEMENT item (#PCDATA)>

The information expressed in a DTD can also be expressed in a QDML document. (A QDML schema is itself an XML document.) Here is the QDML schema for list documents:

    <qdml>

        <element name="list">
            <child element="item"
                   optional="True"
                   repeating="True"/>
        </element>

        <element name="item"
                 content="PCDATA"/>

    </qdml>

On second glance, we see that XML elements can take two different forms, and that elements can have attributes.

What we saw before were elements which had content, be it text or other elements. Elements which have content are expressed using a start and end tag:

    <myElement>The content of my element.</myElement>

    <myElement/>

• Attributes can be part of a start tag or a combined tag, but are never part of an end tag.
• Unlike elements, the order of attributs is not significant.
• An attribute can not be used twice in the same element.
• Attributes should generally not be used in elements which have text content, since this capability is sometimes not supported.
• When formatting documents for display, it is often difficult to display the data contained in attributes.

    <qdml>

        <element name="list">
            <child element="item"
                   optional="True"
                   repeating="True"/>
        </element>

        <element name="item"
                 content="PCDATA"/>

    </qdml>

• QDML: Contains several "element" elements.
• Element: Sometimes contains a "child" element, and has the following attributes:
• Name
• Content
• Child: Has the following attributes:
• Element
• Optional
• Repeating

• An element with no content can be expressed using a simplified format.
• Elements can have attributes, which can be expressed in any order.
• Unlike attributes, the same kind of element can occur more than once within the content of another element.

    <list>
        <item>A DTD or Schema</item>
        <item>may describe a Data Model,</item>
        <item>but how do they help with</item>
        <item>processing XML documents?</item>
    </list>

    <qjml root="list">

        <element name="list">
            <targetClass>java.util.ArrayList</targetClass>
            <child element="item"
                   optional="True"
                   repeating="True"
                   class="com.jxml.quick.access.QListAccess"/>
        </element>

        <element name="item"
                 content="string"/>

    </qjml>

Once you have written a QJML binding schema, processing the XML documents described by that schema is easy.

In this section, the key point is that QJML will make it easy to process XML documents.

 
 

First, we need a few import statements:

import java.util.*;

We need this import statement for the List example, since we will be using ArrayList.

import java.io.*;

This import statement lets us catch an IOException, which might be thrown when an XML document is read.

import com.jxml.quick.*;

We will be calling static methods on the Quick class and referencing the QDom interface, which are all part of the Quick package.

import org.xml.sax.*;

The methods on the Quick class throw a SAXException, which is part of the SAX package, when an error is encountered.

import org.xml.sax.helpers.*;

QDom objects are used by Quick to hold structures of objects, and related meta data (element IDs).

Before we begin processing XML documents, we need to process the appropriate QJML binding schema.

Here is the initialization code needed for List documents:

QDoc listSchema=Quick.parseQJML("list.qjml");

Here we parse the QJML binding schema for the List markup language. The parse results are placed in a newly created QDoc object.

Creating a List Document

        ArrayList list1=new ArrayList();
        list1.add("This is a list");
        list1.add("with three");
        list1.add("items.");

        QDoc listDoc1=Quick.createDoc(list1,listSchma);
        String xml1=Quick.express(listDoc1);

        System.out.println(xml1);

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <list>
        <item>This is a list</item>
        <item>with three</item>
        <item>items.</item>
    </list>

Processing a List Document

        QDoc sampleDoc=Quick.parse(listSchema,"sample.list");
        ArrayList sampleList=(ArrayList)Quick.getRoot(sampleDoc);

        int sampleSize=sampleList.size();
        int i;
        for (i=0;i<sampleSize;++i)
        {
            System.out.println(sampleList.get(i));
        }

    XML should be easy to use.
    Quick keeps it simple, too.

Quick has an internal binding schema, QIML, whose elements correspond to various classes of the Quick engine. When parsing a QJML document, Quick translates the data structure to QIML and uses that to compose an assemblage of objects capable of operating on documents of the type defined by the QJML document.

But instead of converting a QJML file into a QIML data structure each time a program is run, the QJML2QIML utility can be used to create a .qiml file. Quick can then use the .qiml file instead of the .qjml file.

So why have both QJML and QIML? Well, QIML is really the internal data structure used by Quick. QIML is not friendly. The transformation between QJML and QIML is where a lot of the friendliness of QJML is handled.

But there is also a very good reason for having Quick accept QIML files. The QJML binding schema is not exactly a standard. QJML was intended as something easy to implement, but easier to use than QIML. (An early alpha of Quick was based on QIML, and it was impossible to use!) But there are, no doubt, much superior alternatives to QJML. With Quick accepting QIML files, we now have the opportunity of using a different binding schema and converting it directly to QIML, rather than be limited to using QJML directly. (QIML has interesting capabilities like inheritance, which are missing from QJML.)

1. Quick requires JDK1.3, so your first step may be to download a new JDK from JavaSoft.
2. Next you will need to download the quick and quick util zip files and unzip them.
3. The quick directory includes the Quick3rt.jar file; the quickutil directory includes the Quick3util.jar file. Make sure these jar files are included in your CLASSPATH.

Windows users:

Add the quickutil\bin directory included in the download to your PATH. The bin directory has a .bat file for each of the QDK utilities. Besides,

     dtd2qdml x.dtd x.qdml

is a lot easier to type than

     java com.jxml.quick.util.dtd2qdml.DTD2QDML x.dtd x.qdml

Advanced users:

If you wish to use a SAX parser other than AElfred, then add a file named SAXParserClassName.txt to your classpath and put one line of text in that file--the fully qualified name of your SAX parser class.

Quick includes utilities for creating QDML schema, QJML binding schema, DTDs, and even Java source code.

If you are starting with a DTD, you can do the following:

1. Run dtd2qdml to translate your DTD into a QDML schema file.
2. Run qdml2qjml to translate the QDML schema into a QJML binding schema.
3. Edit the QJML file, replacing the generated names with something more meaningful.
4. Run qjml2java to create the stub classes for your application.

Converting a DTD to XML

DTD2XML is a utility for converting DTD files into XML. Here's the command line:

        java com.jxml.quick.util.dtd2xml.DTD2XML X.dtd X.xml

Converting a DTD to a QDML Schema

DTD2QDML is a utility for converting DTD files to QDML schema. Here's the command line:

        java com.jxml.quick.util.dtd2qdml.DTD2QDML X.dtd X.qdml

DTD2QDML will print warning messages when either mixed mode elements or the ANY construct are encountered, as these do not translate directly into QDML.

Converting QDML to QJML

QDML2QJML is a utility for converting QJML schema to QJML binding schema. Here's the command line:

        java com.jxml.quick.util.qdml2qjml.QDML2QJML X.qdml root package X.qjml

x.qdml is the QDML file to be converted,

root is the root element,

package is the package containing the Java classes for the various elements, and

x.qjml is the name of the QJML file to be created.

QDML2QJML tries to guess how the various elements will be mapped into Java classes. For some applications, the generated QJML file will be good enough. But for other applications, the generated file is only a starting point.

The QJML Wizard

The QJML Wizard is a tool for editing and validating the QJML files needed by Quick.

The QJML Wizard is somewhat forgiving of the file you are editing--it allows you to edit QJML files which are missing various elements and attributes. This means that you can use DTD2QDML to create a QDML file, change the root element from QDML to QJML, and then use the QJML Wizard to add the required binding information. (A bit more pre-editing may be needed if the DTD has elements with MIXED content.)

Here's the command line for running the QJML Wizard:

        java com.jxml.quick.qtil.qjmlWizard.wizard.Main

The wizard display includes an element tree on the left and an attribute list on the right. The contents of the element buffer (used for element cut and paste operations) apears in the line above the element tree. There is also an error list below the element tree and attribute list. Errors are reported for the selected portion of the element tree, including all subordinate elements.

When you select an element in the element tree, the attributes are shown on the right. Select an attribute and a dialog box pops up for editing.

Adding new elements is done in a few simple steps:

1. Click on the New Element menu.
2. Click on the type of element you want to create (targetEditor, targetClass, targetFactory, element, attribute, value, child, selection, or sequence). Try creating an element.
3. For all element types except for selection or sequence, a dialog box now apears requesting entry of a single mandatory value. (An element's tag name, for example.)
4. After entering the requested information, the element buffer shows the new element that has been created. Now select the place in the element tree where you want to put this new element.
5. After selecting a place in the element tree, click on the Paste Element menu.
6. Depending on the type of element you have created and the type of element you selected in the element tree, different paste operations are available (Before, After, Replace, Update, Add). Only legal operations are active--just click on the appropeiate type of paste operation and the new element is added to the tree.
7. You can now edit the attributes of the new element, or add additional elements.

Generating Java classes from QJML

QJML2Java is a utility for generating Java classes from a QJML file. Here's the command line:

        java com.jxml.quick.util.qjml2java.QJML2Java [-cqprtf1] [-gpackage.name] schema.qjml output_folder

• -c requests the generation of clone methods,
• -q requests the generation of code to implement the QAware interface,
• -p requests the generation of qParent variables and supporting logic (requires -q),
• -r requests the generation of print logic,
• -t requests the generation of xPath methods,
• -f requests the generation of full constructor methods.
• -1 requests the generation of a single class per element. (By derfault, a _Quick class is generated which contains all the generated logic and a second class is generated as a place to put all the hand-written code.)
• -gpackage.name requests that only classes for the specified package be generated.
• schema.qjml is the QJML file to be processed, and
• output_folder is the path name of the directory tree where the Java files are to be written.

Converting QJML to QIML

QJML2QIML is a utility for converting QJML files to QIML. Here's the command line:

        java com.jxml.quick.util.qjml2qiml.QJML2QIML X.qjml X.qiml

DTD Generation

QJML and QIML are used by Quick, but are non-standard. This is because Quick needs to have binding information as well as a schema. So if you're using Quick, you have been developing a QJML binding schema. But when working with others, you need a DTD. So here's the command line to convert a QJML file into a DTD:

        java com.jxml.quick.util.qjml2dtd.QJML2DTD X.qjml X.dtd

        java com.jxml.quick.util.qiml2dtd.QIML2DTD X.qiml X.dtd

Looking Inside--Quick's own QIML file

QIML2XML is a utility for generating a QIML file from the Quick runtime's internal structures. Here's the command line:

        java com.jxml.quick.util.qiml2xml.QIML2XML X.qiml

• Quick API
• Examples
• Timesheet
• List
• Batch
• QDOM
• types (Release 1.1)
• href (Release 1.1)
• href2 (Release 1.1.2)
• content (Release 1.1.1)
• content2 (Release 1.1.4)
• idref (Updated Release 1.1.4)
• map (Release 1.2)
• Schema Definitions
  • QDML Schema
    <!DOCTYPE qdml SYSTEM "http://jxquick.sourceforge.net/qdml.dtd">
  • QJML Binding Schema
    <!DOCTYPE qjml SYSTEM "http://jxquick.sourceforge.net/qjml.dtd">
  • QIML Binding Schema
    <!DOCTYPE qiml SYSTEM "http://jxquick.sourceforge.net/qiml.dtd">
• Mark Wutka's DTDParser
  • Home Page
  • Source Forge Project Summary
• OSAGE - Persistence Plus XML
  • Home Page
  • Source Forge Project Summary
• QARE XML Portal
  • Home Page
  • Source Forge Project Summary

After you Download Quick, we suggest the following:

News about the latest Quick release.
Quick Forum for general discussion.
QARE Forum Quick Agent Runtime Environment--a new project to use Quick and agent technology to process XML over HTTP.
Bug Tracking for support requests, bug submissions, and suggestions for new/missing features.

As you become familiar with Quick, we encourage your participation in its development:

Quick Source Forge Project Summary
CVS Repository for Quick Utilities and Examples
CVS Repository for the Quick Runtime
Task Manager A collection of project proposals.

Your participation in the development of Quick is welcome!

 <JXML>  <Download>  <QDML>  <QJML>  <QARE>