This document contains installation instructions and other notes that may help you use this software library more effectively. See also the JAXP FAQ for more information.
Note:
If you are reading this page online, this is the most current version of the release notes. If this page was downloaded as part of the release bundle, please see the JAXP Documentation page for the most current version of the release notes.
This release is contained in six JAR files:
The information in this section pertains to the Xerces technology:
javax.xml.parsers,
org.xml.sax,
and org.w3c.dom
DOM Level 2 Core packages, you can use the library in a manner independent
of the underlying implementing parser.setValidating methods
of javax.xml.parsers.DocumentBuilderFactory
or javax.xml.parsers.SAXParserFactory.
ErrorHandler must be set. See the
setErrorHandler methods of javax.xml.parsers.DocumentBuilder
or org.xml.sax.XMLReader.
More information on known bugs and recent fixes can be found at the Apache Xerces site (The release notes for the latest Xerces version are at http://xml.apache.org/xerces2-j/releases.html.)
This section discusses known schema processing bugs, limitations, and implementation-dependent operations.
Note:
The exact value at which maxOccurs poses a problem depends on the
machine and the
amount of memory allocated to the Java Virtual Machine.
JAXP 1.1 is built into J2EE 1.3 and J2SE 1.4. Since JAXP 1.2 contains a different parser, there are some differences in functionality that is not specified by the standard. This section highlights the major differences.
Note:
JAXP is intended as an implementation-independent API layer. However, it is still possible to make use of parser-specific features, either intentionally or unintentionally. Portable applications (those that do not rely on parser-specific features) will not be affected by these differences.
The JAXP 1.1 parser recognizes Java encoding names in an XML header. For example, in this header:
<?xml version="1.0" encoding="UTF8"?>the JAXP 1.1 parser recognizes the Java encoding name UTF8 as valid. However, in XML the standard encoding name uses a hyphen, as in UTF-8.
Since XML documents are intended for maximum portability, the JAXP 1.2 parser diagnoses the use of UTF8 as an error.
Note:
The Java encoding name is still UTF8, so you continue to use that value when invoking APIs in the java.io and java.lang packages -- as, for example, when writing:out = new OutputStreamWriter(System.out, "UTF8");
On the other hand, the java.nio package more properly recognizes UTF-8. (And all of Java's core packages recognize UTF-16.)
While XML does not allow recursive entity definitions, it does permit nested entity definitions, which produces the potential for Denial of Service attacks on a server which accepts XML data from external sources. For example, a SOAP document like the following that has extremely deeply nested entity definitions can consume 100% of CPU time and a lot of memory in entity expansions.
<?xml version="1.0" encoding ="UTF-8"?>
<!DOCTYPE foobar[
<!ENTITY x100 "foobar">
<!ENTITY x99 "&x100;&x100;">
<!ENTITY x98 "&x99;&x99;">
...
<!ENTITY x2 "&x3;&x3;">
<!ENTITY x1 "&x2;&x2;">
]>
<SOAP-ENV:Envelope xmlns:SOAP-ENV=...>
<SOAP-ENV:Body>
<ns1:aaa xmlns:ns1="urn:aaa" SOAP-ENV:encodingStyle="...">
<foobar xsi:type="xsd:string">&x1;</foobar>
</ns1:aaa>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
A system that doesn't take in external XML data need not be concerned with issue, but one that does can utilize one of the following safeguards to prevent the problem:
The JAXP RI contains 2 XSLT engines that are part of the Xalan implementation. This section of the Release Notes describes:
Note:
XSLT is supported by the JAXP transform package. Seejavax.xml.transformfor details on accessing basic XSLT functionality in an implementation-independent manner.
Xalan is the default XSLT parsing engine that is used when you use the JAXP transform package. More information on can be found at the Apache Xalan site.
For the latest information on other known bugs and recent fixes, see the Xalan "Read Me" at http://xml.apache.org/xalan-j/readme.html.
The XSLTC transformer generates a transformation engine, or translet, from an XSL stylesheet. This approach separates the interpretation of stylesheet instructions from their runtime application to XML data.
XSLTC works by compiling a stylesheet into Java byte code (translets), which can then be used to perform XSLT transformations. This approach greatly improves the performance of XSLT transformations where a given stylesheet is compiled once and used many times. It also generates an extremely lightweight translet, because only the XSLT instructions that are actually used by the stylesheet are included.
The known bugs and limitations are:
To check on the open bugs in the current Apache xml-xalan/java repository, follow the instructions below:
In both Xalan and XSLTC, a problem can occur when using a custom class loader with a transformation factory.
Transformation factories in JAXP always prefer the use of the "context class loader" to the use of the "system class loader". Thus, if an application uses a custom class loader, it may need to set the custom class loader as the context class loader for transformation factory to use it. Setting a custom class loader on the current thread can be done as follows:
try {
Thread currentThread = Thread.currentThread();
currentThread.setContextClassLoader(customClassLoader);
}
catch (SecurityException e) {
// ...
}
If the application is multi-threaded, the custom class loader may need to be set in all threads (every time a new thread is created). A security exception is thrown if an application does not have permission to set the context class loader.
This issue applies to both Xalan and XSLTC.
By default, JAXP transformations use the Xalan XSLT engine. To direct the application to use the XSLT engine in XSLTC, one way is to set the TransformerFactory property as follows:
javax.xml.transform.TransformerFactory=
org.apache.xalan.xsltc.trax.TransformerFactoryImpl
This mechanism lets you determine which transformer you use when you start the app. However, changing this property in a servlet container, for example, affects every other servlet in the container, so it may be unwise to use that option. (To prevent the problems that can attend such global overrides, future implementations of Tomcat in the Java Web Services Developer Pack may well preclude such property settings.)
When you can't use a system property to select the transformation engine, you can either instantiate the factory in your program directly, with code like this:
new org.apache.xalan.xsltc.trax.TransformerFactoryImpl(..)
Or, to get back runtime control, you can pass the name of the factory as an argument to the application, and use the ClassLoader to create a new instance of it.
Similarly, you can ensure you are using the Xalan implementation with this setting (or else direct the application to instantiate the factory class, as above):
javax.xml.transform.TransformerFactory=
org.apache.xalan.processor.TransformerFactoryImpl
The JAXP transformation API includes a "Smart Transformer" which automatically switches between Xalan and XSLTC processors within your application. It uses Xalan to create your Transformer objects, and XSLTC to create your Templates objects.
To use the switch, you use this setting for the factory system property:
javax.xml.transform.TransformerFactory=
org.apache.xalan.xsltc.trax.SmartTransformerImpl
For one-time transformations or transformations that require extensions supported by Xalan, and not XSLTC, you would use Transformer objects. For a repeated transformation where performance is critical, you would use Templates objects.
Note:
Again, it may or may not be wise (or possible) to control the factory setting with a system property. See the previous section for ideas on directing the application to instantiate a specific factory class.
When an application is running on a web server, such as the Java Web Services Developer Pack (JWSDP), with security enabled, the following permissions must be set:
permission java.io.FilePermission "/${webserver.home}/common/endorsed/xercesImpl.jar", "read"; permission java.io.FilePermission "/${webserver.home}/common/endorsed/xalan.jar", "read"; permission java.util.PropertyPermission "javax.xml.parser.SAXParserFactory", "read, write"; permission java.util.PropertyPermission "javax.xml.transform.TransformerFactory", "read, write"; permission java.util.PropertyPermission "user.dir", "read"; permission java.util.PropertyPermission "file.separator", "read"; permission java.util.PropertyPermission "line.separator", "read"; permission java.util.PropertyPermission "JavaClass.debug", "read"; permission java.lang.RuntimePermission "createClassLoader"; permission java.lang.RuntimePermission "accessDeclaredMembers";Note:
If read permission is not set for xercesImpl.jar, a potentially misleading error message is reported. A FactoryConfigurationError is thrown that says
"Provider org.apache.crimson.jaxp.SAXParserFactoryImpl not found",
instead of
"Provider org.apache.xerces.jaxp.SAXParserFactoryImpl not found".
Performance of Xerces parser improved significantly.
XSLTC was not included as part of this release, which was destined solely for the J2EE platform.
Finally, this release fully supports the proposed 1.2 JAXP specification,
which implements document validation using W3C XML Schema.
The Xalan XSLTC processor was also added in this release. (It is used to compile a stylesheet into a transformation engine (translet) that is ready to run.)
This release fully supports the proposed 1.2 JAXP specification, which implements document validation using W3C XML Schema.
The parser supports W3C XML Schema but does not support all aspects of the proposed JAXP 1.2 specification. In particular, the ability to enforce that an instance document conforms to a particular schema has not been implemented. However, the validation portions of the specification can be used along with schema hints in the instance document.