Hello,
Last year, Ilene Seelemann put some effort into producing a list of
the API's that should be considered to be public, another list of those
that should be considered experimental, and a third list of those that
should be considered purely internal to Xalan-Java. The idea was that
this would provide some guidance to users on the extent to which they can
rely on particular API's from one release of Xalan-Java to the next.
Xerces-J has something similar on its web-site.[1]
I spent a little time putting the final touches on Ilene's document,
and have presented it below. If no one objects, I'd like to include the
following information in the web site for the Xalan-J 2.6.0 release.
If anybody feels he or she hasn't had sufficient time to consider
this, or objects to any of the specific details, I'll hold off until the
next release.
------------------------------------------------------------------
Supported Interfaces in Xalan-Java
----------------------------------
Public Interfaces
-----------------
A public interface of Xalan-Java is an API that a typical client developer
should code against. Such interfaces are usually based upon World-Wide
Web Consortium (W3C) recommendations, such as XSLT 1.0 and XPath 1.0, or
Java Specification Requests (JSR's) with a status of "Final Release", such
as JAXP.
The Xalan-Java team will support use of public interfaces, and will
attempt to fix severe bugs in such interfaces
A particular version of a public interface will be supported for all the
maintenance drops of a particular version and release of Xalan-Java (i.e.,
a change in just the third digit of the version number). At the point a
new release of Xalan-Java is made available (i.e., a change in the first
or second digit of the version number), such interfaces could change to
reflect the latest standard specifications.
The public interfaces of Xalan-Java are:
o JAXP 1.2 interfaces found in the javax.xml.parsers and
javax.xml.transform packages.
o The XPath API, defined by the classes
. org.apache.xpath.XPathAPI
. org.apache.xpath.CachedXPathAPI
o API's for using, configuring or defining a serializer, from the
org.apache.xml.serializer package:
. OutputPropertiesFactory
. SerializerFactory
. Serializer
o Properties files for configuring a serializer.
. org/apache/xml/serializer/output_xml.properties
. org/apache/xml/serializer/output_html.properties
. org/apache/xml/serializer/output_text.properties
o Command-line interfaces for performing transformations:
. Xalan-Java Command-line utility
. Compiling translets from the command line
. Running translets from the command line
Experimental interfaces
-----------------------
Interfaces and classes that are designated experimental reflect recent
World-Wide Web Consortium (W3C) draft recommendations or draft Java
Specification Requests (JSR's). Such an API is based upon a specification
that is subject to change, and so is itself subject to change as the
relevant standards body makes changes to the specification.
If and when the specification upon which the API is based reaches its
final published form, the API could become a Public interface in a
subsequent release of Xalan-Java. The Xalan-Java team could instead
decide to simply withdraw the API, if it decided that making the API a
public interface would not be appropriate.
As the name suggests, experimental interfaces are provided in order to
give users the opportunity to experiment with new features so that they
can provide feed-back on those features. They should not be used in
production-level code.
The experimental interfaces of Xalan-Java are:
o The DOM Level 3 XPath API found in the org.apache.xpath.domapi package.
Internal interfaces
-------------------
All other classes are considered to be part of the internal interface of
Xalan-Java. Some such classes or members of such classes may themselves
be designated as public using the Java keyword, but that is a consequence
of the internal organization of Xalan-Java.
Users who have complex and specific needs, such as the need to build their
own XSLT or XPath processors, might use these internal interfaces, but
their use is not supported. In addition these interfaces are subject to
change without notice.
------------------------------------------------------------------
Thanks,
Henry
[1] http://xml.apache.org/xerces2-j/api.html
------------------------------------------------------------------
Henry Zongaro Xalan development
IBM SWS Toronto Lab T/L 969-6044; Phone +1 905 413-6044
mailto:[EMAIL PROTECTED]
