Henry and Ilene -- FWIW, I think you've both done a really fine job on this. It's very clear and complete. I say, put it in with 2.6.0.
Gary > -----Original Message----- > From: Henry Zongaro [mailto:[EMAIL PROTECTED] > Sent: Tuesday, February 24, 2004 6:22 PM > To: [EMAIL PROTECTED] > Subject: Public API's of Xalan-Java > > > 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] >
