diff options
Diffstat (limited to 'gcc-4.4.3/libjava/classpath/doc/README.jaxp')
| -rw-r--r-- | gcc-4.4.3/libjava/classpath/doc/README.jaxp | 204 |
1 files changed, 204 insertions, 0 deletions
diff --git a/gcc-4.4.3/libjava/classpath/doc/README.jaxp b/gcc-4.4.3/libjava/classpath/doc/README.jaxp new file mode 100644 index 000000000..afafb083c --- /dev/null +++ b/gcc-4.4.3/libjava/classpath/doc/README.jaxp @@ -0,0 +1,204 @@ +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 specifying 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, libxmlj 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. + |