Welcome to xml-commons

xml-commons is focussed on common code and guidelines for xml projects. The first focus will be to organize and have common packaging for the various externally-defined standards code relating to XML - things like the DOM, SAX, and JAXP interfaces.

As the xml-commons community forms, we also hope to serve as a holding area for other common xml-related utilities and code, and to help promulgate common packaging, testing, documentation, and other guidelines across all xml.apache.org subprojects.

As the community forms, we need to formalize these guidelines, especially to differentiate "requirements" from suggested "guidelines".

Shane's starting proposals:

xml-commons is an unusual project in several ways.

First, it encompasses two kinds of code: External and Apache.

Secondly, xml-commons mainly focuses on providing code and services to other xml.apache.org projects instead of shipping it's own 'standalone' project.

Third, it will also tend to be more focussed on smaller, interoperable modules of code and a very high degree of stability.

In some ways, the forming of xml-commons is the seed of a catalyst to improve cross-project coordination throughout xml.apache.org. One potential goal is to get all xml.apache.org projects to take their xml standards oriented code - like DOM, SAX and JAXP - from specific marked builds of xml-commons, instead of each project using different versions of these files.

External code: xml-commons will serve as an Apache-controlled copy of externally-defined standards-based files. This way, we can try to manage common versions of these important xml standards-based files and interfaces. Read more.

Apache code: xml-commons will serve as a shared repository for common xml-oriented utilities or building blocks that several other xml.apache.org projects wish to use. The first example is org.apache.env.Which, and environment checking utility that scans your environment and reports common versions of xml-related files. The next likely submission is an entity resolver that could be plugged into any xml parsing, transforming, or processing project. Read more.

Directory tree (proposed)

xml-commons/
    README.html - this file
    build.xml - overall build file for top-level items
    xdocs/ - top-level xml format docs about this project itself and our guidelines
        (in whatever format xml.apache.org uses for site)

    docs/ - (not checked in) html format docs created by 'build docs' from xdocs
    java/ - root of all java-related files

        external/ - src root of all source files in java that come from external sources
            for example: the DOM, SAX, and JAXP files
            org/xml/sax/*
            org/w3c/dom/*
            javax/xml/*
        external/build.xml - Ant build file for all external sources

        xdocs/ - xml format docs describing any java files, as needed

        {name}.xml - Ant build file for Apache-defined subproject(s)
            future: resolver.xml: for Norm Walsh's entity resolver submission, when done

        src/ - root of Apache-defined Java code
            src/org/apache/... etc

        which.xml - Ant build file for org.apache.env.Which utility


    c/ - root of all C/C++ related files
        external/ - root of all externally-owned C/C++ sources

    perl/ - root of all Perl related files
        etc.

• We should consider adopting those guidelines from the jakarta-commons project that make sense for our xml projects - keeping in mind that both the kind of projects we build are different than jakarta, and some of our goals are a little bit different.
• Dicsussion and buy-in should happen on the project mailing list before checking in new modules.
• New modules generally shouldn't go in until at least two separate other projects express interest in using the module. I think this is an important difference from jakarta-commons that makes sense in our world. I.e. I'd rather not just throw something in because it seems like it might be useful, I'd rather only put things in that we know will be shared among multiple projects.
• The xml-commons community should come up with guidelines for other xml.apache.org subprojects to use the code that commons has. I.e. suggestions and ways to package this code vis-a-vis the other project's code in a common way.
• Other shared xml.apache.org guidelines? Like documentation format, testing techniques/policies, etc.

xml-commons primary goal is to provide Apache projects with a stable version of XMl-related externally-defined standards-based code. This is mainly the various interfaces that you use when programming XML from JAVA: DOM, SAX and JAXP for now.

This tree is rooted at xml-commons/java/external, and has a build.xml file. Basic documentation from each external project is also checked in.

• Current (Feb-02) status:
• No significant changes from Jan-02
• Current (Jan-02) status:
• DOM L2 - full set of interfaces (including HTML stuff) from w3c.org
• SAX 2.0 from megginson.com, plus minor bugfixes. Note that SAX is currently maintained at http://sax.sourceforge.net/ ( we need to update and cross-check with them soon!)
• JAXP 1.1.3-HEAD from Sun, with current bugfixes by edwingo@apache.org

Issues Jan-02: our current SAX and JAXP code may not pass the current J2EE CTS test suite, since we have bugfixes above what those CTS tests mandate. If you don't know what that is, you don't care; otherwise ask on commons-dev for an update.

xml-commons' secondary goal is to provide a project space for small XML-related utilities that are being used in multiple other xml.apache.org projects. In an effort to simplify and reduce dependency headaches, we'll probably accept new projects only fairly slowly (this is in contrast to the much more open jakarta-commons project). In particular, code submitted here should probably have minimal dependencies: possibly only depending on DOM/SAX/JAXP and Ant (for builds).

• Current (Nov-02) status:
• org.apache.xml.resolver.Resolver: Norm Walsh's entity resolver utility now released as a separate distribution, see Releases.
• Current (Feb-02) status:
• org.apache.env.Which - a simple environment check utility for xml-related items in your JVM's environment: see xml-commons/java/which.xml
• org.apache.xml.resolver.Resolver: Norm Walsh's entity resolver utility now checked in!
• (to be voted in) Jeff Turner's DOCTYPE changer
• Current (Jan-02) status:
• org.apache.env.Which - a simple environment check utility for xml-related items in your JVM's environment: see xml-commons/java/which.xml
• (to be submitted) Norm Walsh's entity resolver utility
• (to be voted in) Jeff Turner's DOCTYPE changer

The xml-commons-resolver-1.0 release 12-Nov-02 is available in our distribution directory and includes:

• This release includes just the 1.0 XmlResolver component, by request from coccoon-dev and others. It is released for users who just want to use the Resolver and don't need the rest of xml-commons. Pending discussion on commons-dev, we believe that future xml-commons releases will be separated out in this manner (external, resolver, which etc).

The xml-commons-1.0.b2 release 06-Feb-02 is available in our distribution directory and includes:

• The previous contents from the 1.0.b1 release (minor javadoc fixes may have been made)
• Various LICENSE.* and README.* files for our external sources
• New code! org.apache.xml.resolver.Resolver: Norm Walsh's entity resolver utility is now checked in and building!

The xml-commons-1.0.b1 release 11-Jan-02 is available in our distribution directory and includes the following code:

• java/build/which.jar containing:
• org.apache.env.Which - a simple environment check utility for xml-related items in your JVM's environment: 1.0 funtionality working
• java/external/build/xml-apis.jar containing:
• DOM Level 2 including all base files and HTML and CSS DOMs; from w3c.org
• JAXP code roughly equivalent to JAXP 1.1.3; for reference releases from Sun, see java.sun.com/xml
• SAX 2.0-r2-prerelease and SAX2-ext-1.0; plus bugfixes to org.xml.sax.helpers.ParserAdapter (make compile in JDK 1.1.x) and AttributesImpl (minor removeAttribute bug); from megginson.com although SAX maintenance has now moved to sax.sourceforge.net

Future 'b' or beta releases leading up to a gold 1.0 release will be discussed on our mailing list. Likely releases might address points such as:

• Improvements or submissions to org.apache.env.Which
• A new submission of an entity resolver from Norman Walsh
• A specific version of backlevel JAXP 1.1 that will work with Sun's J2EE CTS conformance tests, if enough people request it
• Specific versions of SAX, if the xml.apache.org community requests it and wants to update to a newer shipped release of SAX, perhaps SAX 2R2pre3 or later

If you have done 'svn checkout xml-commons' (see below) then you have local sources of all components and all documentation sources. There is a high-level build file that will also call the other sub-build files for each component. Just do 'ant -projecthelp' to get started.

The documentation for the xml-commons project is built using Apache Forrest. If you have Forrest installed then just type 'forrest' in the top-level xml-commons directory. Otherwise see the Apache XML Commons website documentation.

We have a project mailing list ... xml-commons-dev<at>xerces.apache.org ... Ask your questions or bring your suggestions there, or to general<at>xerces.apache.org

• To subscribe to xml-commons-dev ... xml-commons-dev-subscribe<at>xerces.apache.org
• To un-subscribe from xml-commons-dev ... xml-commons-dev-unsubscribe<at>xerces.apache.org
• To send an email to xml-commons-dev ... xml-commons-dev<at>xerces.apache.org

To help you keep up with the changes to the repository, subscribe to ... commits<at>xerces.apache.org

The xml-commons source code is available through the ASF Subversion repository or browse. See SVN overview.

See the separate document History of XML Commons for the proposal to establish the xml-commons project and for the record of the vote on 2001-04-26.

See information about licensing.