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