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.
java.endorsed.dirs
property is not set to a directory that has the old xercesImpl.jar and xalan.jar files.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.)
More information on the limitations of Xerces technology can be found
at http://xml.apache.org/xerces2-j/limitations.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:
entityExpansionLimit or by
setting the parser property http://apache.org/xml/properties/entity-expansion-limit.
Both properties accept a java.lang.Integer. The
parser throws a fatal error once it has reached the entity expansion
limit. By default, entityExpansionLimit is set to 64,000.
The limit set using http://apache.org/xml/properties/entity-expansion-limit
overrides the limit set with the system property.
You can set the entity expansion limit or element attribute
limit by using code similar to the following:
DocumentBuilderFactory dfactory = DocumentBuilderFactory.newInstance();
dfactory.setAttribute( "http://apache.org/xml/properties/entity-expansion-limit",
new Integer("100000"));
dfactory.setAttribute("http://apache.org/xml/properties/elementAttributeLimit",new
Integer(20));
DocumentBuilder docBuilder = dbFactory.newDocumentBuilder();
elementAttributeLimit or by setting the http://apache.org/xml/properties/elementAttributeLimit
property on the
parser. Both properties accept Integer values. By default elementAttributeLimit
is set to 10,000. When the
parser property, http://apache.org/xml/properties/elementAttributeLimit
is set, it overrides the system property. The parser throws a fatal
error if the number
of attributes in a element exceeds the limit. 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 interpretive XSLT transformation engine. More information on Xalan interpretive transformer 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.
XSLTC is the default transformation engine that is used when you use the JAXP transform package from JAXP 1.2.6_01
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 XSLT engine in XSLTC. To direct the application to use the XSLT engine in Xalan, one way is to set the TransformerFactory property as follows:
javax.xml.transform.TransformerFactory=
com.sun.org.apache.xalan.internal.processor.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 com.sun.org.apache.xalan.internal.processor.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 XSLTC transformer with this setting (or else direct the application to instantiate the factory class, as above):
javax.xml.transform.TransformerFactory=
com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl
When an application is running on a web server, such as the Tomcat 5, 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".
org.apache.xalan.* package is now called
com.sun.org.apache.xalan.internal.* .org.apache.xerces.* package is now called com.sun.org.apache.xerces.internal.*
.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.