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

1 files changed, 168 insertions, 0 deletions

diff --git a/doc/README.jaxp b/doc/README.jaxp
new file mode 100644
index 000000000..e06729947
--- /dev/null
+++ b/doc/README.jaxp
@@ -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.