| Important information about XML4J |

On November 9, 1999, the Apache Software Foundation announced the creation of the xml.apache.org project for Open Source XML solutions. As part of that announcement, IBM announced that it was donating its XML4J, XML4C and LotusXSL technologies to the xml.apache.org project. The parsing technologies have been renamed Xerces, and the LotusXSL technology has been renamed Xalan. IBM is shifting its XML parsing development resources to work on the Xerces parsers. The objective is to use the Xerces code base as the foundation for XML4J and XML4C. This version of XML4J is based on the Apache Xerces version 1.2.0 codebase.

| What's the difference between XML4J and Xerces? |

This version of XML4J has been tested internally at IBM, beyond the testing that is done by the xml.apache.org project. In addition, we are providing a compatibility jar for customers migrating from the XML4J 2.0.x native API. The TX compatibility APIs are no longer present in the XML4J 3.0.x series.

Please note that the names of the main .jar files have changed from xml4j.jar to Xerces.jar and from xml4jSamples.jar to XercesSamples.jar

| What part of the API is public, and what is subject to change? |

To answer this question, let us clearly define the terms we use for API status:

- Public - This is the API that the typical client developer should code against. An attempt will be made to fix any severe bugs in this API. Also, much of this API that we define as "public" has reached W3C Recommendation status or a similar status in xml-dev working group. Not much change in these interfaces is expected.
- Experimental - These interfaces and classes reflect the latest W3C specifications and SAX specifications from the xml-dev working group. Since these specifications are not finalized, the interfaces are subject to change. As some of these experimental specifications find their way through the working groups to the highest level, such as W3C Recommendation, they will be upgraded to the "Public" category.
- Internal - These classes are considered to be internal to Xerces, even though they may be public and have public methods. They can be used by developers who have complex and specific needs, such as building their own XML Parser. However, please note that the architecture is subject to change.

API status | API contents (packages, interfaces, classes and methods) | Comments

Public

DOM Level 1 interfaces (found in org.w3c.dom, org.w3c.dom.html)
SAX Level 1 interfaces (found in org.xml.sax. and subpackages)
org.apache.xerces.parsers.SAXParser, org.apache.xerces.parsers.DOMParser

The DOM1 and SAX1 Interfaces are stable, and they are identical to the specifications.
The DOMParser and SAXParser are Xerces-specific, because currently there is no universal API for parser access and configuration.
This issue is being discussed in the DOM Level 3 working group, and Xerces will provide feedback and will track the progress in this area.

Experimental

DOM Level 2 (DOM2) interfaces (found in org.w3c.dom and subpackages) The DOM2 interfaces have been implemented in the same interfaces as DOM1, but as new methods.
These new DOM2 methods are clearly identified in the Javadoc API documentation as "Since: DOM Level 2 ".
In addition, you may refer to the DOM2 specification, and more specifically, to Appendix A which describes the changes between DOM1 and DOM2.
SAX Level 2 (SAX2) interfaces (found in org.xml.sax. and subpackages). You can identify the SAX2 differences by visting: changes between SAX2 and SAX1.

The DOM2 interfaces are in the Candidate Recommendation (CR) phase. This phase allows for implementors like Xerces to provide feedback about the API. Therefore some parts of the API may change, but the specification is pretty far along in the process toward final Recommendation.
The SAX2 interfaces have changed significantly from "beta1" to the current "beta2", which is implemented in this release. It is unclear whether they may change significantly again before becoming finalized.

Internal | All other packages are considered to be internal. | The internal Xerces architecture may change.

Please note that as an Apache Open Source project, the Xerces community is very interested in your questions and feedback regarding the whole API, not only that part designated above as public.

If you have specific questions, patches, or feedback regarding the Xerces API or code, you may visit the Apache Web site, and sign up for the mailing list. Otherwise more basic questions, or questions specific to XML4J, can be sent to AlphaWorks discussion forum.

| What APIs should I use for new development? |

All new development should use the org.apache.xerces.parsers.* classes. The four "compatibility" parser classes have been replaced by these two classes:

`org.apache.xerces.parsers.SAXParser`
`org.apache.xerces.parsers.DOMParser`

The control over validation has been changed to be a feature of the parser, rather then requiring separate classes.

The future direction for the parser instantiation classes is a parser instantiation API that will result from the W3C's DOM Level 3 effort, which is just getting underway.

Also, to make sure your code is as stable as possible, whever possible, please use the interfaces specified in the Public section of the table in the former section (e.g. DOM1, SAX1). The table will be kept up to date to highlight when new interfaces and classes are given Public status (e.g. DOM2, SAX2).

| What is the purpose of the com.ibm.xml.parsers.* compatibility classes? |

The com.ibm.xml.parsers.* classes exist so that existing users of XML4J 2.x can simply change their classpath and use the new parser without re-compiling their client code.

However, please note that these classes have been deprecated since the XML4J EA 3.0 release, are currently still deprecated, and may be removed sometime in the future.

In order to use the 2.0.x compatibility classes, you need to include the xml4j.jar jar file in your CLASSPATH, in addition to the Xerces.jar. There are four classes in the jar:
`com.ibm.xml.parsers.SAXParser com.ibm.xml.parsers.ValidatingSAXParser com.ibm.xml.parsers.NonValidatingDOMParser com.ibm.xml.parsers.DOMParser`

Note: In order to keep compatibility and not break existing code, the XML4J SAXParser, and the ValidatingSAXParser have set the following feature to be false: `setFeature( "http://xml.org/sax/features/namespaces", false );`

This feature is set to true in the Xerces org.apache.xml.parsers.SAXParser to comply with SAX Level 2.

| Is IBM making any additional support guarantees with XML4J? |

| IBM is not making any additional support guarantees for XML4J. In particular, IBM is not certifying that XML4J is Y2K compliant. XML4J makes no internal date calculations.

| Change history |

- December 9, 1999: version 3.0.0EA3 First version derived from Xerces-J code base. Supply XML4J 2.0.x compatibility API.
- March 10, 2000: version 3.0.1 This version is derived from the Xerces 1.0.3 release. It continues to include the deprecated XML4J 2.0.x compatibility API as a separate jar.
- September 20, 2000: version 3.1.0 This version is derived from the Xerces 1.2.0 release. It continues to include the deprecated XML4J 2.0.x compatibility API as a separate jar.