[cp-patches] Add documentation for jaxp implementations

[Mark Wielaard]

Hi,

This adds the documentation from GNU JAXP. I have only slightly edited
it to mention that this is now a proper part of GNU Classpath.

The doc/README.jaxp file gives a good overview of the new packages,
conformance and usage (how to switch between the implementations).

2005-01-02  Mark Wielaard  <address@hidden>

       * ChangeLog.gnujaxp.1: New (historic) ChangeLog file.
       * ChangeLog.gnujaxp.2: Likewise.
       * ChangeLog.libxmlj: Likewise.
       * Makefile.am (EXTRA_DIST): List new ChangeLog files.
       * INSTALL: Add libxml2 and libxslt requirements for --enable-xmlj.
       * doc/README.jaxp: New file.
       * doc/Makefile.am (EXTRA_DIST): List new README.jaxp
       * native/jni/xmlj/BUGS: New file.
       * native/jni/xmlj/Makefile.am (EXTRA_DIST): List new BUGS file.

The old ChangeLog files have been added to keep the history of the old
projects. But new changes should be listed in the main ChangeLog file.

Committed,

Mark

Index: INSTALL
===================================================================
RCS file: /cvsroot/classpath/classpath/INSTALL,v
retrieving revision 1.23
diff -u -r1.23 INSTALL
--- INSTALL     17 Dec 2004 16:00:32 -0000      1.23
+++ INSTALL     2 Jan 2005 16:49:05 -0000
@@ -36,13 +36,24 @@
         - The kjc compiler is supported with configure but we have
           been unable to successfully compile with it.
 
-       For building the JNI native libraries, the following are required
-        unless --disable-gtk-peer is used as an argument to configure.
+       For building the gtk+ AWT peer JNI native libraries, the following
+       are required unless --disable-gtk-peer is used as an argument to
+       configure.
 
         - GTK+ 2.4.x (or higher)
         - libart_lgpl 2.1.0
         - gdk-pixbuf
 
+       For building the xmlj JAXP implementation (dsabled by default, use
+       configure --enable-xmlj) you need the following installed:
+       - The XML C library for Gnome (libxml2)
+         http://www.xmlsoft.org/
+         Minimum version of libxml2 required: 2.6.8
+
+       - The XSLT C library for Gnome (libxslt)
+         http://www.xmlsoft.org/XSLT/
+         Minimum version of libxslt required: 1.1.11
+
        For building the documentation you will need
 
        - texinfo 4.2 or higher.
Index: Makefile.am
===================================================================
RCS file: /cvsroot/classpath/classpath/Makefile.am,v
retrieving revision 1.39
diff -u -r1.39 Makefile.am
--- Makefile.am 23 Dec 2004 22:38:42 -0000      1.39
+++ Makefile.am 2 Jan 2005 16:49:05 -0000
@@ -6,7 +6,8 @@
 
 native: lib
 
-EXTRA_DIST = HACKING BUGS THANKYOU mauve-classpath LICENSE ChangeLog-2003
+EXTRA_DIST = HACKING BUGS THANKYOU mauve-classpath LICENSE ChangeLog-2003 \
+             ChangeLog.gnujaxp.1 ChangeLog.gnujaxp.2 ChangeLog.libxmlj
 
 #DISTCHECK_CONFIGURE_FLAGS = --enable-gjdoc
 
Index: doc/Makefile.am
===================================================================
RCS file: /cvsroot/classpath/classpath/doc/Makefile.am,v
retrieving revision 1.4
diff -u -r1.4 Makefile.am
--- doc/Makefile.am     21 Dec 2002 05:39:06 -0000      1.4
+++ doc/Makefile.am     2 Jan 2005 16:49:05 -0000
@@ -1,5 +1,7 @@
 SUBDIRS = api
 
+EXTRA_DIST = README.jaxp
+
 info_TEXINFOS = hacking.texinfo vmintegration.texinfo
 
 %.dvi : %.texinfo
Index: doc/README.jaxp
===================================================================
RCS file: doc/README.jaxp
diff -N doc/README.jaxp
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ doc/README.jaxp     2 Jan 2005 16:49:05 -0000
@@ -0,0 +1,168 @@
+This file describes the jaxp (xml processing) implementation of GNU Classpath.
+GNU Classpath includes interfaces and implementations for basic XML processing
+in in the java programming language, some general purpose SAX2 utilities, and
+transformation.
+
+These classes used to be maintained as part of an external project GNU JAXP
+but are now integrated with the rest of the core class library provided by
+GNU Classpath.
+
+PACKAGES
+    
+. javax.xml.* ... JAXP 1.3 interfaces
+
+. gnu.xml.aelfred2.* ... SAX2 parser + validator
+. gnu.xml.dom.* ... DOM Level 3 Core, Traversal, XPath implementation
+. gnu.xml.dom.ls.* ... DOM Level 3 Load & Save implementation
+. gnu.xml.xpath.* ... JAXP XPath implementation
+. gnu.xml.transform.* ... JAXP XSL transformer implementation
+. gnu.xml.pipeline.* ... SAX2 event pipeline support
+. gnu.xml.util.* ... various XML utility classes
+. gnu.xml.libxmlj.dom.* ... libxmlj DOM Level 3 Core and XPath
+. gnu.xml.libxmlj.sax.* ... libxmlj SAX parser
+. gnu.xml.libxmlj.transform.* ... libxmlj XSL transformer
+. gnu.xml.libxmlj.util.* ... libxmlj utility classes
+
+In the external directory you can find the following packages.
+They are not maintained as part of GNU Classpath, but are used by the
+classes in the above packages.
+
+. org.xml.sax.* ... SAX2 interfaces
+. org.w3c.dom.* ... DOM Level 3 interfaces
+
+CONFORMANCE
+
+    The primary test resources are at http://xmlconf.sourceforge.net
+    and include:
+
+    SAX2/XML conformance tests
+       That the "xml.testing.Driver" addresses the core XML 1.0
+       specification requirements, which closely correspond to the
+       functionality SAX1 provides.  The driver uses SAX2 APIs to
+       test that functionality It is used with a bugfixed version of
+       the NIST/OASIS XML conformance test cases.
+       
+       The AElfred2 parser is highly conformant, though it still takes
+       a few implementation shortcuts.  See its package documentation
+       for information about known XML conformance issues in AElfred2.
+
+       The primary issue is using Unicode character tables, rather than
+       those in the XML specification, for determining what names are
+       valid.  Most applications won't notice the difference, and this
+       solution is smaller and faster than the alternative.
+
+       For validation, a secondary issue is that issues relating to
+       entity modularity are not validated; they can't all be cleanly
+       layered.  For example, validity constraints related to standalone
+       declarations and PE nesting are not checked.
+
+        The current implementation has also been tested against Elliotte
+        Rusty Harold's SAXTest test suite (http://www.cafeconleche.org/SAXTest)
+        and achieves approximately 93% conformance to the SAX specification
+        according to these tests, higher than any other current Java parser.
+
+    SAX2
+       SAX2 API conformance currently has a minimal JUNIT (0.2) test suite,
+       which can be accessed at the xmlconf site listed above.  It does
+       not cover namespaces or LexicalHandler and Declhandler extensions
+       anywhere as exhaustively as the SAX1 level functionality is
+       tested by the "xml.testing.Driver".  However:
+
+           - Applying the DOM unit tests to this implementation gives
+             the LexicalHandler (comments, and boundaries of DTDs,
+             CDATA sections, and general entities) a workout, and
+             does the same for DeclHandler entity declarations.
+           
+           - The pipeline package's layered validator demands that
+             element and attribute declarations are reported correctly.
+       
+       By those metrics, SAX2 conformance for AElfred2 is also strong. 
+    
+    DOM Level 3 Core Tests
+        The DOM implementation has been tested against the W3C DOM Level 3
+        Core conformance test suite (http://www.w3.org/DOM/Test/). Current
+        conformance according to these tests is 72.3%. Many of the test
+        failures are due to the fact that GNU JAXP does not currently
+        provide any W3C XML Schema support.
+
+    XSL transformation
+        The transformer and XPath implementation have been tested against
+        the OASIS XSLT and XPath TC test suite. Conformance against the
+        Xalan tests is currently 77%.
+
+
+libxmlj
+========================================================================
+
+libxmlj is an effort to create a 100% JAXP-compatible Java wrapper for
+libxml2 and libxslt. JAXP is the Java API for XML processing, libxml2
+is the XML C library for Gnome, and libxslt is the XSLT C library for
+Gnome.
+
+libxmlj currently supports most of the DOM Level 3 Core, Traversal, and
+XPath APIs, SAX2, and XSLT transformations. There is no W3C XML Schema
+support yet.
+
+libxmlj can parse and transform XML documents extremely quickly in
+comparison to Java-based JAXP implementations. DOM manipulations, however,
+involve JNI overhead, so the speed of DOM tree construction and traversal
+can be slower than the Java implementation.
+
+libxmlj is highly experimental, doesn't always conform to the DOM
+specification correctly, and may leak memory. Production use is not advised.
+
+The implementation can be found in gnu/xml/libxmlj and native/jni/xmlj.
+See the INSTALL file for the required versions of libxml2 and libxslt.
+configure --enable-xmlj will build it.
+
+Usage
+------------------------------------------------------------------------
+
+To enable the various GNU JAXP factories, set the following system properties
+(command-line version shown, but they can equally be set programmatically):
+
+  AElfred2:
+   -Djavax.xml.parsers.SAXParserFactory=gnu.xml.aelfred2.JAXPFactory
+
+  GNU DOM (using DOM Level 3 Load & Save):
+   
-Djavax.xml.parsers.DocumentBuilderFactory=gnu.xml.dom.DomDocumentBuilderFactory
+
+  GNU DOM (using AElfred-only pipeline classes):
+   -Djavax.xml.parsers.DocumentBuilderFactory=gnu.xml.dom.JAXPFactory
+
+  GNU XSL transformer:
+   
-Djavax.xml.transform.TransformerFactory=gnu.xml.transform.TransformerFactoryImpl
+
+  libxmlj SAX:
+   
-Djavax.xml.parsers.SAXParserFactory=gnu.xml.libxmlj.sax.GnomeSAXParserFactory
+
+  libxmlj DOM:
+   
-Djavax.xml.parsers.DocumentBuilderFactory=gnu.xml.libxmlj.dom.GnomeDocumentBuilderFactory
+
+  libxmlj XSL transformer:
+   
-Djavax.xml.transform.TransformerFactory=gnu.xml.libxmlj.transform.GnomeTransformerFactory
+
+When using libxmlj, the libxmlj shared library must be available.
+In general it is picked up by the runtime using GNU Classpath. If not you
+might want to try adding the directory where libxmlj.so is installed
+(by default ${prefix}/lib/classpath/) with ldconfig or specifing in the
+LD_LIBRARY_PATH environment variable. Additionally, you may need to specify
+the location of your shared libraries to the runtime environment using the
+java.library.path system property.
+
+Missing (libxmlj) Features
+------------------------------------------------------------------------ 
+
+See BUGS in native/jni/xmlj for known bugs in the libxmlj native bindings.
+
+This implementation should be thread-safe, but currently all
+transformation requests are queued via Java synchronization, which
+means that it effectively performs single-threaded. Long story short,
+both libxml2 and libxslt are not fully reentrant.  
+
+Update: it may be possible to make libxmlj thread-safe nonetheless
+using thread context variables.
+
+Update: thread context variables have been introduced. This is very
+untested though, libxmll therefore still has the single thread
+bottleneck.
Index: native/jni/xmlj/BUGS
===================================================================
RCS file: native/jni/xmlj/BUGS
diff -N native/jni/xmlj/BUGS
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ native/jni/xmlj/BUGS        2 Jan 2005 16:49:06 -0000
@@ -0,0 +1,35 @@
+GNU Jaxp
+------------------------------------------------------------------------
+
+These bugs are for the gnu.xml.libxmlj package.
+
+CAVEAT: LibxmlJ's current incarnation is incomplete and partly
+incorrect. Highly experimental.
+
+- Thread-safe, but effectively runs single-threaded.
+
+- Native code passes incorrect URIs to URIResolver.resolve.
+
+- Default output properties accessible through JAXP always assume XML
+  output (in violation of the XSLT 1.0 specification, section 16)
+  Correction: LibxmlJ always assumes XML output.
+
+- OutputProperties are not properly implemented, compare code and API
+  documentation.
+
+- TransformerFactory.getAttribute() and
+  TransformerFactory.setAttribute() not implemented, i.e. low-level
+  libxslt settings can currently not be accessed from Java.
+
+- TransformerFactory.getFeature() not implemented, i.e. currently no
+  low-level features of libxslt are advertised.
+
+FIXME:
+
+- Make LRU caching configurable.
+
+- Check whether <?xml encoding="..."?> headers are honored.
+
+- DefaultURIResolver uses naive approach.
+
+- TransformerFactory.getAssociatedStyleSheet() unfinished.
Index: native/jni/xmlj/Makefile.am
===================================================================
RCS file: /cvsroot/classpath/classpath/native/jni/xmlj/Makefile.am,v
retrieving revision 1.2
diff -u -r1.2 Makefile.am
--- native/jni/xmlj/Makefile.am 2 Jan 2005 13:50:46 -0000       1.2
+++ native/jni/xmlj/Makefile.am 2 Jan 2005 16:49:06 -0000
@@ -21,3 +21,5 @@
 
 # Don't enable ERROR flags. Code isn't warning free yet.
 AM_CFLAGS = @WARNING_CFLAGS@ @STRICT_WARNING_CFLAGS@ @XML_CFLAGS@ @XSLT_CFLAGS@
+
+EXTRA_DIST = BUGS

signature.asc
Description: This is a digitally signed message part