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:
If you are installing or updating the full Web Services Pack, there are no other configuration steps you need to take. The installation/update process takes care of the details for you. If you are using the Java XML Pack, on the other hand, or if you are using JAXP by itself with the Java 2 platform, then you'll need to follow the instructions below.
If you downloaded the Java XML Pack, the JAR files are in:
<JavaXmlPack_HOME>/jaxp-1.2
Updated versions of the JAR files may also be obtained individually. The remainder of this section tells you where and how.
Three of the JAR files contain Apache implementations of the parser and transformation classes:
These three jar files contain the same packages as the Apache jar files with the same names. That distribution strategy was chosen so that, as bug fix versions become available at the Apache site, they can simply be substituted for the current versions of those files.
The most recently updated versions of those JAR files can be obtained from
However, while those three implementation jar files correspond to
the Apache release, there is a difference in the packaging of the API
jar files. The single Apache jar file, xml-apis.jar
, is broken
up into 3 jar files in JAXP: jaxp-api.jar
, sax.jar,
dom.jar
.
The SAX and DOM APIs are in separate JAR files because they are "endorsed standards" that are built into version 1.4 of the Java platform. That means newer versions of those JAR files can be placed in the endorsed standards directory to update those APIs. (For more information on the SDK's endorsed standards mechanism, see http://java.sun.com/j2se/1.4/docs/guide/standards/.)
Since the packages contained in the jaxp-api.jar
file are not
endorsed standards (and cannot be placed in the endorsed standards directory),
they exist in a separate jar file.
Note:
The Apache API jar file also contains Apache-specific APIs. These are not present in the JAXP release, as they are not integral to the Java APIs for XML Processing (JAXP).
The JAR files that define the SAX and DOM API classes used by the parsers and transformation engines are:
If you upgrade to a version of the parser that uses a different version of those APIs, you would need to replace the JAR file containing the appropriate API. For more information on those APIs, see:
The remaining JAR file defines the JAXP factory classes and transform APIs:
As of version 1.4, those classes are built into the Java 2 platform. Because they are high-level wrapper classes that are not subject to change, it is not necessary to do anything with that JAR file when using Java 1.4. For earlier versions of the Java 2 platform, it always accompanies the other JAR files.
This section tells you what to do with the JAR files, depending on the configuration in which they are being used. The relevant variables are:
Again, if you are using the Web Services installation process to do the update, then you don't have to worry about the updates. But if you are updating individual jar files, copy them to
<JWSDP_HOME>/common/endorsed/
First, be sure to remove xerces.jar from
<TOMCAT_HOME>/common/lib/
The reason for that step is that xerces.jar contains earlier Xerces implementations which will interfere with the operation of JAXP 1.2.
The next step depends on which version of the Java 2 SDK you are using:
Version 1.4 of the Java 2 platform has JAXP 1.1 implementations built in. JAXP 1.1 has a smaller footprint, but JAXP 1.2 implements XML Schema and the transform compiler, XSLTC.
To use the JAXP 1.2 implementation, copy all of the jar files except jaxp-api.jar into
<JAVA_HOME>/jre/lib/endorsed/Note:
The jaxp-api.jar file should not be copied, because it contains high-level factory APIs that are not subject to change.
The jar files must exist in this location to override earlier versions of the
Xalan libraries that are a standard part of the 1.4 platform. (If the endorsed
directory does not exist, you must create it.) Because of that special requirement,
it is not possible to specify these libraries using the -classpath
option on the java/javac command line.
Alternatively, you can use the java.endorsed.dirs
system property
to dynamically add those jar files to the JVM when you start your program. Using
that system property gives you flexibility of using different implementations
for different applications. However, although the system property guarantees
that the specified jars will be searched before the internal classes in the
VM (which are searched before the classpath), the order in which the jar files
are searched is indeterminate. For that reason, there should be no overlaps
in the classes specified using that property. For more information, see the
Endorsed Standards
documentation for the 1.4 version of the Java platform.
Versions of the Java 2 platform prior to 1.4 do not have JAXP built into the platform, so there is no previous implementation to override. You can either put all 6 jar files on the classpath or you can put all 6 jar files into
<JAVA_HOME>/jre/lib/ext/
Placing the JAR files in jre/lib/ext makes them "standard extensions" which are automatically found when you compile and run your Java programs. On the other hand, a directory location gives you no way to determine the order in which the JAR files are searched, so it is frequently preferable to use the classpath.
Note:
You can either put all of the jar files in theext/
directory, or put them all on the classpath, but you should not split them up, in order to make sure that all dependent classes are properly loaded. (Splitting the jar files between the two locations can create
situations where a class in the ext/ directory is not loaded, even though it is referenced on the classpath, as well as situations where a class on the classpath is not found when the extensions are loaded.)
Starting with JAXP RI 1.2.0, the parser implementation changed from the Apache Crimson parser to Xerces Java 2. This release contains Xerces-J 2.0.1_01 (Xerces 2.0.1 final with controlled bug fixes). More information can be found at the Apache Xerces site.
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
.
For the latest information on known bugs and recent fixes, read the Xerces release notes at http://xml.apache.org/xerces2-j/releases.html.
This section discusses known schema processing bugs, limitations, and implementation-dependent operations.
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.)
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 in this release by the JAXP transform package. Seejavax.xml.transform
for details on accessing basic XSLT functionality in an implementation-independent manner.
This implementation includes xalan-j 2.3.1_01 (Xalan version 2.3.1 with controlled bug fixes for XSLTC only). More information can be found at the Apache Xalan site. This is the default XSLT parsing engine that is used when you use the JAXP transform package.
For the latest information on known bugs and recent fixes, see the Xalan "Read Me" at http://xml.apache.org/xalan-j/readme.html.
The Xalan XSLTC transform compiler 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.
XSLTC does not yet support the following features of the XSL Transformations (XSLT) Version 1.0:
XSLTC supports a number of features that are not required by the XSLT 1.0 specification, but which are supported by a number of other XSLT processors:
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:Java="http://xml.apache.org/xslt/Java" xmlns:Java-system="http://xml.apache.org/xslt/Java/java.lang.System">
<xsl:template match="/"> <xsl:value-of select="Java:java.lang.System.currentTimeMillis()"/> <xsl:value-of select="Java-system:currentTimeMillis()"/> </xsl:template> </xsl:stylesheet>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xsltc-extension="http://xml.apache.org/xalan/xsltc" xmlns:some-extension="http://some-extension" version="1.0">
<xsl:template match="/"> <xsl:variable name="rtf"> <docelem> <elem1>elem1</elem1> <elem2>elem2</elem2> </docelem> </xsl:variable>
<!-- Use nodeset as XSLTC extension --> <xsl:value-of select="xsltc-extension:nodeset($rtf)/docelem/elem1"/>
<!-- Use nodeset as standard function --> <xsl:value-of select="nodeset($rtf)/docelem/elem1"/> </xsl:template> </xsl:stylesheet>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xsltc="http://xml.apache.org/xalan/xsltc" xsl:version="1.0">
<xsl:template match="/"> <xsl:text>This goes to standard output</xsl:text> <xsltc:output file="blob.xml"> <xsl:text>This ends up in the file 'blob.xml'</xsl:text> </xsltc:output> </xsl:template> </xsl:stylesheet>
The known bugs and limitations are:
If you need this option, it is available from the current version of XSLTC at Apache.TransformationFactory tfac = new TransformationFactory(); tfac.setAttribute("disable-inlining", new Boolean(true))
or by using the setXMLReader method on the SAXSource:SAXParserFactory pfactory= SAXParserFactory.newInstance(); pfactory.setNamespaceAware(true); // Very important! XMLReader reader = pfactory.newSAXParser().getXMLReader(); SAXSource saxsource = new SAXSource(reader, new InputSource(inputFilename)); transformer.transform(saxsource, new StreamResult(System.out));
SAXParserFactory pfactory= SAXParserFactory.newInstance(); pfactory.setNamespaceAware(true); // Very important! XMLReader reader = pfactory.newSAXParser().getXMLReader(); SAXSource saxsource = new SAXSource(inputfilename); saxsource.setXMLReader(reader); transformer.transform(saxsource, new StreamResult(System.out));
To check on the open bugs in the current Apache xml-xalan/java repository, follow the instructions below:
The localization resource packages org.apache.xalan.res and org.apache.xpath.res adopt a non-standard approach for resource bundles. In addition, localizable content is embedded in code, making full localization extremely difficult to achieve.
To track the status of this bug, monitor bug# 4452624 at http://developer.java.sun.com/developer/bugParade
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 Web Services 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 Switch" which enables automatic switching between Xalan and XSLTC processors within your application. It uses Xalan to create your Transformer objects, and uses 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 Web Services Development 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".
The parser implementation changed from Xerces 2.0.0_01 to Xerces-J 2.0.1_01
(Xerces 2.0.1 final with controlled bug fixes). The Xalan XSLT processor
implementation was updated to xalan-j 2.3.1_01 (Xalan version 2.3.1 with
controlled bug fixes).
Finally, this release fully supports the proposed 1.2 JAXP specification,
which implements document validation using W3C XML Schema.
The parser implementation changed from Xerces 2.0.0 beta3 to Xerces-J 2.0.0_01 (Xerces 2.0.0 final with controlled bug fixes). The Xalan XSLT processor implementation was updated to xalan-j 2.3.0_01 (Xalan version 2.3.0 with controlled bug fixes).
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 implementation changed from Apache Crimson to Xerces 2 version 2.0.0 beta3. The XSLT processor implementation was updated to Xalan classic version 2.2.D14.
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.