★ wanayoo — archive 1999 http://wdvl.com/Authoring/Languages/XML/Java/java-projectx.html

XML and Java: Java Project X (formerly XML Library from JavaSoft)

Ken Sall

December 9, 1998

URL: http://developer.javasoft.com/developer/earlyAccess/xml/index.html

Release Notes: http://developer.java.sun.com/developer/earlyAccess/xml/relnotes.html

In mid September 1998, JavaSoft released an early access [1] version of the XML Library, a Java API that includes extremely fast parsing (validating or non-validating), in-memory object model tree for manipulating and writing XML structured data, XML JavaBeans, support for DOM, SAX, and XML Namespaces, and more. The XML Library may be used with any JDK 1.1 conformant system, including JDK 1.2 conformant systems. The initial Early Access release consisted of five packages, two of which are based on SAX and two of which are based on the DOM. [At the time of this writing, the javadoc for these packages was not yet online, so we cannot link to the package definitions.]

In late November 1998, JavaSoft changed the name of XML Library to "Java Project X" when they released their second early access release ["ea2"]. The above URLs apply to the latest release.

Parsing Packages

com.sun.xml.parser: This package holds two fast XML parsers (one validates, the other does not) and various support classes including an entity resolver that has basic catalog and MIME type interpretation support.
org.xml.sax: SAX (Simple API to XML) is an event-driven parser API, which supports most of the widely available XML parsers.
org.xml.sax.helpers: This package contains simple "helper" classes which can help programmers get started using the SAX APIs.

Object Model Packages

com.sun.xml.tree: This package supports in-memory XML documents in the form of a parse tree compliant with the W3C DOM Level 1 Recommendation, and which exposes XML namespace information as defined by the current XML namespace draft.
org.w3c.dom: The Document Object Model (DOM) is a Recommendation of the World Wide Web Consortium, defining an OMG-IDL API for XML data and HTML documents, and mapping them to Java (and JavaScript).

Some of the capabilities provided by the XML Library include (but are not limited to):

Simple File Parsing and Redisplay;
Building XML Documents with DOM;
XML Namespace Support (not part of DOM 1.0, but a W3C Working Draft);
XML Validation Service;
XML Beans for Swing JTree Display (element customizations);

The XML Library comes with XML and API examples and javadoc documentation (may not yet be on-line but is included with the download). Below is an example from Sun's Early Access release.

/*
 * @(#)main.java        1.2 98/08/31
 *
 * Copyright (c) 1998 Sun Microsystems, Inc. All Rights Reserved.
 *
 * Sun grants you ("Licensee") a non-exclusive, royalty free, license to use,
 * modify and redistribute this software in source and binary code form,
 * provided that i) this copyright notice and license appear on all copies of
 * the software; and ii) Licensee does not utilize the software in a manner
 * which is disparaging to Sun.
 *
 * This software is provided "AS IS," without a warranty of any kind. ALL
 * EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY
 * IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR
 * NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN AND ITS LICENSORS SHALL NOT BE
 * LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING
 * OR DISTRIBUTING THE SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR ITS
 * LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT,
 * INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER
 * CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF
 * OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGES.
 *
 * This software is not designed or intended for use in on-line control of
 * aircraft, air traffic, aircraft navigation or aircraft communications; or in
 * the design, construction, operation or maintenance of any nuclear
 * facility. Licensee represents and warrants that it will not use or
 * redistribute the Software for such purposes.
 */

import java.io.File;
import com.sun.xml.tree.XmlDocument;
import com.sun.xml.tree.XmlDocumentBuilder;
import org.xml.sax.SAXException;
import org.xml.sax.SAXParseException;

public class main
{
    //
    // Reading and writing an XML document stored in a file.
    //
    public static void main (String argv [])
    {
        String          uri;
        XmlDocument     doc;

        if (argv.length != 1) {
            System.err.println ("Usage: cmd filename");
            System.exit (1);
        }

        try {
            // turn the filename into a fully qualified URL
            uri = "file:" + new File (argv [0]).getAbsolutePath ();

            // turn it into an in-memory object
            doc = XmlDocumentBuilder.createXmlDocument (uri);

            // and write it out
            doc.write (System.out);

        } catch (SAXParseException err) {
            System.out.println ("** Parsing error"
                + ", line " + err.getLineNumber ()
                + ", uri " + err.getSystemId ());
            System.out.println("   " + err.getMessage ());
            err.printStackTrace ();

        } catch (SAXException e) {
            Exception   x = e;
            if (e.getException () != null)
                x = e.getException ();
            x.printStackTrace ();

        } catch (Throwable t) {
            t.printStackTrace ();
        }

        System.exit (0);
    }
}

The most significant lines above are:

// turn it into an in-memory object doc = XmlDocumentBuilder.createXmlDocument (uri);

// and write it out doc.write (System.out);

XmlDocumentBuilder.createXmlDocument reads the XML document and creates the in-memory DOM tree, which is an instance of the com.sun.xml.tree.XmlDocument class. The write method of that class traverses the DOM tree and displays the nodes to standard out. The result gives the impression that the program is merely displaying the contents of the input file, but really the building and traversing of the DOM tree is what is going on here. A real application would want to replace write method with some application-specific type of traversal. Consult the XML Library javadocs for details. Essentially this involves creating a TreeWalker object and calling the getNode() method in a loop.

[1] Note: You must establish a free Java Developer Connection account to access this software. Note also that this Java API is certain to change and should not be used for mission-critical projects. However, it is very exciting to see Sun Microsystem's entry into the rapidly growing XML arena. Still, developers should be mindful of the disclaimer that appears in the Sun documentation.

"THIS IS NOT A PRODUCT. The XML library is part of a research and development project and is being released as interesting, but unsupported, technology that may be of use to Java programmers developing web based publishing or messaging systems. Please do not rely on this software for production-quality and/or mission-critical applications. The API is not finalized, and some features may have not been fully implemented in this release."

XML and Java: SAX: Simple API for XML (Parsers)
XML and Java: The Perfect Pair: Part 2: Java APIs for XML
XML and Java: XML Productivity Kit for Java (XPK4J by IBM)