llvm-gcc-4.2/libjava/classpath/doc/README.jaxp - llvm-archive - Git at Google

 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.stream.* ... StAX pull parser and SAX-over-StAX driver
 . 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
 . org.relaxng.datatype.* ... RELAX NG pluggable datatypes API

 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

   GNU StAX:
    -Djavax.xml.stream.XMLEventFactory=gnu.xml.stream.XMLEventFactoryImpl
    -Djavax.xml.stream.XMLInputFactory=gnu.xml.stream.XMLInputFactoryImpl
    -Djavax.xml.stream.XMLOutputFactory=gnu.xml.stream.XMLOutputFactoryImpl

   GNU SAX-over-StAX:
    -Djavax.xml.parsers.SAXParserFactory=gnu.xml.stream.SAXParserFactory

   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.


 Validation
 ===================================================

 Pluggable datatypes
 ---------------------------------------------------
 Validators should use the RELAX NG pluggable datatypes API to retrieve
 datatype (XML Schema simple type) implementations in a schema-neutral
 fashion. The following code demonstrates looking up a W3C XML Schema
 nonNegativeInteger datatype:

   DatatypeLibrary xsd = DatatypeLibraryLoader
     .createDatatypeLibrary(XMLConstants.W3C_XML_SCHEMA_NS_URI);
   Datatype nonNegativeInteger = xsd.createDatatype("nonNegativeInteger");

 It is also possible to create new types by derivation. For instance,
 to create a datatype that will match a US ZIP code:

   DatatypeBuilder b = xsd.createDatatypeBuilder("string");
   b.addParameter("pattern", "(^[0-9]{5}$)|(^[0-9]{5}-[0-9]{4}$)");
   Datatype zipCode = b.createDatatype();

 A datatype library implementation for XML Schema is provided; other
 library implementations may be added.
	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.stream.* ... StAX pull parser and SAX-over-StAX driver
	. 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
	. org.relaxng.datatype.* ... RELAX NG pluggable datatypes API

	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

	GNU StAX:
	-Djavax.xml.stream.XMLEventFactory=gnu.xml.stream.XMLEventFactoryImpl
	-Djavax.xml.stream.XMLInputFactory=gnu.xml.stream.XMLInputFactoryImpl
	-Djavax.xml.stream.XMLOutputFactory=gnu.xml.stream.XMLOutputFactoryImpl

	GNU SAX-over-StAX:
	-Djavax.xml.parsers.SAXParserFactory=gnu.xml.stream.SAXParserFactory

	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.


	Validation
	===================================================

	Pluggable datatypes
	---------------------------------------------------
	Validators should use the RELAX NG pluggable datatypes API to retrieve
	datatype (XML Schema simple type) implementations in a schema-neutral
	fashion. The following code demonstrates looking up a W3C XML Schema
	nonNegativeInteger datatype:

	DatatypeLibrary xsd = DatatypeLibraryLoader
	.createDatatypeLibrary(XMLConstants.W3C_XML_SCHEMA_NS_URI);
	Datatype nonNegativeInteger = xsd.createDatatype("nonNegativeInteger");

	It is also possible to create new types by derivation. For instance,
	to create a datatype that will match a US ZIP code:

	DatatypeBuilder b = xsd.createDatatypeBuilder("string");
	b.addParameter("pattern", "(^[0-9]{5}$)\|(^[0-9]{5}-[0-9]{4}$)");
	Datatype zipCode = b.createDatatype();

	A datatype library implementation for XML Schema is provided; other
	library implementations may be added.