www.apache.org >  xml.apache.org >  commons

Welcome to xml-commons!

xml-commons is a new xml.apache.org subproject!

xml-commons is focused on common code and guidelines for xml projects. It's 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.

In this document:
Commons Guidelines

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 focused 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 here.

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 here.

Directory tree (proposed)

    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
        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
DOM, SAX, and JAXP code

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.

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.

Apache-authored code

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).

Where can I download releases?

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

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

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

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 like:

How can I find out more?

We have a project mailing list setup - commons-dev@xml.apache.org. Ask your questions or bring your suggestions there, or to general@xml.apache.org.
Send an email to commons-dev
Subscribe to commons-dev
Unsubscribe from commons-dev

Where can I get the code/CVS?

The xml-commons repository is available thru normal and anonymous CVS, or through this nifty web interface.

See xml.apache.org CVS overview.

List:     xml-apache-general
Subject:  [VOTE] Proposal: new xml-commons subproject for standards-based files
From:     Shane_Curcuru@lotus.com
Date:     2001-04-17 16:08:07

I propose a new xml.apache.org/xml-commons subproject to fulfill the need
for a central repository for various XML standards-based files and common

COMMITTERS-PLEASE-VOTE! Although I'm not sure of the exact voting procedure
for creating whole new subprojects, I'm hoping to see a bunch of +1's to
start with; feel free to either reply-to or use the handy mini-xml ballot

NON-COMMITTERS-PLEASE-DISCUSS! While votes from non-committers are not
binding your discussion and insights are very valuable!

Key: committer="your_apache_login" email="your@preferred.email.address"
  Leave committer blank if you aren't; vote must be +1 | 0 | -1
  Add comment(s) if you like on specific issues

ballot committer="" email=""
  vote issue="xml-subproject-proposal-commons-v1.1" vote
  vote issue="xml-subproject-proposal-commons-v1.1-committers" vote

Proposal: form a new xml.apache.org subproject called xml-commons to
fulfill the below needs.

(0) Rationale:
Many xml.apache.org projects use and ship with sets of similar
externally-defined standards-based code; differences in versioning and
configuration of this code often make developing and using our projects
more difficult.  A common place for all xml.apache.org projects to get DOM,
SAX, JAXP, and other externally-defined code would be a fairly low-cost and
low-maintenance way to alleviate these difficulties.  Having a subproject
and a community focused on cross-xml-subproject issues will also help drive
better cross-project coordination and tooling.

(0.1) Programming Languages: While the coding details of Java/C/Perl/etc
are obviously different, the core concept is the same: a central repository
for all xml.apache.org projects to share common interfaces and utilities.
We should start with xml-commons/java, xml-commons/c, and xml-commons/perl
since these languages are in current use in various xml.apache.org
subprojects today.

(1) Scope of this subproject:

(1.1) Common externally-defined standards:
This includes the packages: org.w3c.dom.**, org.xml.sax.**, and javax.xml.
**  This is designed to essentially be an xml.apache.org-specific holding
place for commonly-used interfaces/headers that are created outside of
Apache.  This subproject should provide guidelines and build scripts to aid
xml.apache.org groups to easily use these common files in a common manner
across all subprojects.  This subproject should provide some basic
versioning abilities so that xml.apache.org projects temporarily using
new/beta/updated/proposed versions of these specs can continue to get their
code from this area.

(1.2) Common xml-oriented utilities:
We should also include additional utilities/common code in this subproject,
like current copies of bsf.jar, stylebook, servlet API classes, etc.  This
could also include code that did originate in an Apache project, that we
wanted to centralize the use of: SystemIDResolver, XML Serializers, etc.

(1.3) General project starting guidelines for future directions/scope:
While the details of guidelines for this work should be finalized by the
community that forms it (along with input from the other xml.apache.org
projects who will be using this code), there are some basics to start with:
- Communicate status regularly with general@xml.apache.org and with other
- Clearly document and checkin 'best practices' for usage of xml-commons
code in other subprojects
- Proactively work with other subprojects to implement and improve our
'best practices'
- Provide upgrade paths and help; deprecate (or equivalent) old API's
before removing, so other subprojects have ample time to upgrade.
- Test and document all non-standards-based code; provide tests/additional
documentation for standards-based code

(1.4) General guidelines for future directions/scope:
Note this is firstly a subproject to make life inside of xml.apache.org
easier, to enable us to more efficiently develop nifty XML projects.  As we
gain experience in developing this subproject, an obvious future direction
for this community will be to work on a potential AXDK (Apache XML
Development Kit) that would be a meta-packaging-project composed out of
several xml projects together.  The AXDK would be a way to make life for
end-users easier: a single package of various Apache XML tools that works
'out of the box'. (AXDK naming credit to kellyc I think?)

(1.5) Interaction with other subprojects
Additional guidelines can be drawn up on general@xml.apache.org for this
subproject, and then documented and checked in.  These should include both
how other xml subprojects should use these resources in their development
cycles, as well as how all xml subprojects should package these resources
when creating public, shipped distributions (to avoid version conflicts,
etc.)  This subproject's community, along with general@xml.apache.org, will
need to draw up guidelines for code within this subproject as well.

(2) Identify the initial source from which the subproject is to be
Standards-based sources would be obtained from the relevant owners/creators
and checked into the project repository. A basic build.xml file and apache
project usage guidelines would need to be created.  Possible legal review
would be needed for licensed files (one solution might be to waive the
Apache license on these files).  For common xml-oriented utilities, the
initial sources can be moved in from other xml.apache.org subprojects (cf.
potential org.apache.xml.utils.SystemIdResolver from xml-xalan).

(3) Identify the xml.apache.org resources to be created

(3.1) mailing list(s)
(ed note: added xml-commons-cvs as well -Shane)

(3.2) CVS repositories

(3.3) Bugzilla
program: Commons
components: External Standards, Common XML Utils

A sub-issue that I'd like people to vote on separately for whichever of the
below option(s) they like best.
(4) Identify the initial set of committers

(4.a) [vote-multiple] kellyc, curcuru, rubys
(4.b) [vote-multiple] one committer from each xml.apache.org subproject
that wants to volunteer, plus at least one PMC member (for projects that
don't get someone volunteered)
(4.c) [vote-multiple] all current xml.apache.org committers



(*) Important cross-reference:
Jakarta is currently working on a similar, yet different, tool/util/common
code area.  While we can steal a lot of their ideas, I think the needs of
xml.apache.org will be different than Jakarta, so we should make our own
community decision on how to do this.  Many thanks to the nice format for a
proposal that I plagarized.  8-)

- Shane shane_curcuru@lotus.com curcuru@apache.org

Below follows the votes cast to create this subproject

---- From open general@xml.apache.org mailing list through 3pm 26-Apr-01 ----
Original proposal at: http://marc.theaimsgroup.com/?l=xml-apache-general&m=98752444702386&w=2
---- 17 Total committer +1 votes, plus 13 +1's for 4.c (allow all xml committers) ----


Info About This Document