WHAT IS THIS

GNUJAXP includes interfaces and implementations for basic XML processing
in Java, some general purpose SAX2 utilities, and transformation.

The standard distribution includes the full source code.  The current
software is available at:
    http://www.gnu.org/software/classpathx/jaxp

See INSTALL for installation instructions.

JAVA PACKAGES
    
. javax.xml.* ... JAXP 1.2 interfaces
. org.xml.sax.* ... SAX2 (r2pre3, extensions 1.1beta) interfaces
. org.w3c.dom.* ... DOM Level 2 interfaces

. gnu.xml.aelfred2.* ... SAX2 parsers (+ optional validator, and JAXP glue)
. gnu.xml.dom.* ... DOM level 2 (XML) implementation (and JAXP glue)
. gnu.xml.pipeline.* ... SAX2 event pipeline support
. gnu.xml.util.* ... various XML utility classes
. gnu.xml.libxmlj.transform.* ... JNI bindings to libxslt

LICENSING

Briefly, most software in this package is distributed under the GNU
General Public License with the "library exception" that  permits its
usage even in statically linked environments.  That licensing is more
permissive than the "LGPL".

See the LICENSE file for more information.

CONFORMANCE TESTING
    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.

    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 1 (and Level 2 Events) Tests
	The "domunit 0.0.6" tests use the JAXP API to hook up a DOM
	implementation to a parser (out of scope for DOM Level 2).
	Those DOM unit tests are mostly related to Level 1, except
	for a few relating to the Level 2 events module.

	All of these tests pass.

	However, you may want to be aware that Entity nodes, and all
	EntityReference nodes not created by parsing a document, will
	have no children.  Since you should as a rule avoid both these
	node types, you probably won't run into related problems.

----------------------------------------------

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

Currently there is only an implementation for the `JAXP API for XML
Transformations' subset - package javax.xml.transform - and only a
partial implementation. It should be complete enough to work for a
number of use cases, though. See below for a list of limitations and
unsupported features.

The main focus of LibxmlJ so far was support for GNU Gjdoc, which is
now rather complete. Aside from its use in Gjdoc, It hasn't been
tested at all, and has a number of known bugs.

CAVEAT: LibxmlJ's current incarnation is incomplete and partly
incorrect and may leak memory. Highly experimental. Not for production
use.


Usage
------------------------------------------------------------------------

See INSTALL for installation instructions.

To enable use of LibxmlJ for JAXP transformations:

 System.setProperty("javax.xml.transform.TransformerFactory",
                    "gnu.xml.libxmlj.transform.TransformerFactoryImpl");

You can also specifiy the factory by using the VM command line or one
of the other methods described in the documentation for
javax.xml.transform.TransformerFactory.newInstance().

Make sure that `gnujaxp.jar' and `libxmlj.jar' are on your CLASSPATH
and the shared library can be found (i.e. is configured via ldconfig
or located on the LD_LIBRARY_PATH).


Usage with Gcj
------------------------------------------------------------------------

You can create native executables from Java JAXP/XSLT applications
using gcj, GNU JAXP and LibxmlJ like this:

	gcj --output=./yourapplication \
	    --main=your.MainClass \
            --fjni \
	    /path/to/your/application.jar \
	    /path/to/gnujaxp.jar \
	    /path/to/libxmlj.jar \
	    -Djavax.xml.transform.TransformerFactory= \
	        gnu.xml.libxmlj.transform.TransformerFactoryImpl \
            -lxml2 -lxslt -lxmlj

Note that this requires gcj 3.3.

Note that you may have to specify the source codes (the .java files)
for the classes contained in the jar files listed above in order for 
gcj 3.3 to link stuff properly.

The resulting executable will depend on libxmlj.so, which in turn
depends on libxml2.so and libxslt.so.


Missing Features
------------------------------------------------------------------------ 

See BUGS for known bugs.

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, LibxmlJ therefore still has the single thread
bottleneck.
