JAXP 1.2 Release Notes

Java^TM API for XML Processing Release Notes

Specification Version: 1.2
Reference Implementation (RI) Version: 1.2.0-FCS

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.

Identifying the JAR Files
Deploying the JAR Files
- Finding the JAR Files
- Using the JAR Files
XML Parsing
- Known Schema Processing Limitations in JAXP 1.2
- Known Migration Issues from JAXP 1.1
XSLT Processing
JWSDP Security Considerations
Changes in JAXP RI Versions

Identifying the JAR Files

This release is contained in six JAR files:

jaxp-api.jar: The javax.xml.parsers and javax.xml.transform components of JAXP. These packages contain the APIs that give applications a consistent way to obtain instances of XML processing implementations.
sax.jar: The APIs and helper classes for the Simple API for XML (SAX), used for serial access to XML data.
dom.jar: The APIs and helper classes for the Document Object Model (DOM), used to create an in-memory tree structure from the XML data.
xercesImpl.jar: The implementation classes for the SAX and DOM parsers, as well as Xerces-specific implementations of the JAXP APIs..
xalan.jar: The "classic" Xalan XSLT processor.
xsltc.jar: The Xalan Compiling XSLT processor.

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.

Finding the JAR Files

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.

Apache Implementation JAR Files

Three of the JAR files contain Apache implementations of the parser and transformation classes:

xercesImpl.jar (Xerces 2 version 2.0.1, with controlled bug fixes)
xalan.jar (Xalan version 2.3.1, with controlled bug fixes)
xsltc.jar (version 2.3.1, with controlled bug fixes)

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

http://xml.apache.org/

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

JAR Files for the Parsing APIs

The JAR files that define the SAX and DOM API classes used by the parsers and transformation engines are:

sax.jar (SAX 2.0)
dom.jar (Dom Level 2)

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:

JAR file for the JAXP APIs

The remaining JAR file defines the JAXP factory classes and transform APIs:

jaxp-api.jar (JAXP 1.2)

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.

Using the 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:

Whether or not you are using the Web Services Pack
Whether or not you are using Tomcat
Whether you are using version 1.4 of the Java 2 platform, or an earlier version

Using JAXP 1.2 with the Web Services Pack

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/

Using JAXP 1.2 with Tomcat version 4.0.3 or 3.3

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:

For version 1.4 of the Java 2 SDK:: You need to know that JAXP 1.1 is built into that version of the platform. JAXP 1.1 has a smaller footprint, but JAXP 1.2 implements XML Schema, and it also includes transform compiler, XSLTC.

To use the JAXP 1.2 implementation instead of the JAXP 1.1 implementation, copy all of the JAR files except jaxp-api.jar to

<TOMCAT_HOME>/common/lib/

Then, when running Tomcat, set the java.endorsed.dirs system property to

<TOMCAT_HOME>/common/lib/
Note:
The jaxp-api.jar file should not be copied, because it contains high-level factory APIs that are not subject to change.
For version 1.3 of the Java 2 SDK:: Copy all 6 JAR files to

<TOMCAT_HOME>/common/lib/

and add that directory to your classpath.

Using JAXP 1.2 with version 1.4.0 of the Java 2 platform

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.

Using JAXP 1.2 with earlier versions of the Java 2 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 the ext/ 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.)

XML Parsing

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.

There are two factory classes for making parsers pluggable. If you limit your application to the JAXP API in the 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.
To be notified of validation errors in an XML document, these items must be true:
1. The document must be associated with a schema.
2. Validation must be turned on. See the setValidating methods of javax.xml.parsers.DocumentBuilderFactory or javax.xml.parsers.SAXParserFactory.
  
  To validate with a W3C XML Schema, you must also set a SAX property or DOM attribute. For details see, the Schema Examples section of samples.html.
3. An application-defined 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.

Known Schema Processing Limitations in JAXP 1.2

This section discusses known schema processing bugs, limitations, and implementation-dependent operations.

Limitations

These limitations specify known upper bounds on values.

Length, minLength, and maxLength facets are limited to the value 2147483647.
Items larger than this limit will not be validated correctly.
Year and seconds values in date/time datatypes are limited to the value 2147483647.
Items larger than this limit will not be validated correctly.

Problem Areas / Known Bugs

The following problems are known to exist:

Due to changes in the specification for Decimals in JDK1.3, not all decimals that should
be invalid according to the Schema specs may be found by the parser.
For larger values of maxOccurs, a StackOverflowError may occur.
The workaround for this problem, if your application permits it, is to change the
maxOccurs value to unbounded.

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.

Implementation-Dependent Operations

These implementation-dependent operations are not fully clarified by the W3C XML Schema specification (http://www.w3.org/2001/XMLSchema). As a result, differing implementations exist.

In the JAXP 1.2 reference implementation parser (Xerces 2.0.1), the length facet of QName is measured as units of XML characters in the value space (the number of chars in namespace URI + ":" + local part). Since the W3C schema specification does not define the unit of length for QName, other implementations may differ.
The JAXP 1.2 reference implementation parser (Xerces 2.0.1), <keyref> Identity Constraints refers to <key> or <unique> identity constraints within the scope of the elements to which the <keyref> is attached, as defined in the XML Schema Part 1: Structures. (The introductory section of XML Schema, on the other hand, (XML Schema Part 0: Primer) contains an example with a <keyref> declared on an element used inside the element of its corresponding <key>. The discrepancy is noted here in an effort to avoid confusion.)

Known Migration Issues from JAXP 1.1

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.

Use of Java Encoding Names

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

XSLT Processing

The JAXP RI contains 2 XSLT engines that are part of the Xalan implementation. This section of the Release Notes describes:

The Classic Xalan XSLT Processor
The Xalan Compiling Processor (XSLTC)
Localization Issues
Manually Specifying which XSLT Implementation to Use
Automatically Choosing with the Smart Transformer Switch

Note:
XSLT is supported in this release by the JAXP transform package. See javax.xml.transform for details on accessing basic XSLT functionality in an implementation-independent manner.

The Classic Xalan XSLT Processor

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 Compiling Processor (XSLTC)

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.

XSLT 1.0 Conformance and Extensions

XSLTC does not yet support the following features of the XSL Transformations (XSLT) Version 1.0:

The case-order option to the sort element is not supported, because XSLTC relies on the underlying Java sorting classes (bugzilla 1396).
XSLTC does not support Unicode (UTF-8, UTF-16, etc, encoding) in XPATH expressions.
Stylesheets with nonASCII characters in the element and attribute names referenced in XPATH expressions will fail to compile (bugzilla 6724). This has been fixed at Apache, but did not make it into this release.

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:

Calling external Java methods from a Translet.
At the time of writing, only static methods are supported. A call to a function whose namespace is either http://xml.apache.org/xslt/Java or http://xml.apache.org/xalan/xsltc/Java is resolved by loading the appropriate class and calling a static method that matches the signature of the function. The class can be specified as part of the namespace URI or as part of the function call as shown in the following example:
```
 <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>
```
Result Tree Fragments
Result Tree Fragments (RTFs) can be captured as the template content of a variable or parameter and then the variable can be passed to a for-each or an apply-templates as a node set.

nodeset() Function
XSLTC also supports the nodeset() function for transforming an RTF (result tree fragment)
into a node set. It can be used as an xsltc-extension function or as a standard XPATH
function as shown in the following example:

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

Output Redirection
Output can be redirected to one or more files, using code like the following:

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

Known Limitations in XSLTC

The known bugs and limitations are:

The strip space element does not work with copy-of. For example, with <xsl:strip-space elements="*"/>, if you do an identity transform by matching on the root node (/) and then do a copy-of select=".", the whitespace-only nodes are not stripped out. xsl:strip-space works when you do not do a copy-of.
In some cases, XSLTC can generate methods that are too long (> 64K length) to run, or contain jump offsets that are too large for the JVM to handle. You can minimize this by breaking up large templates into smaller templates. XSLTC has a new compile option to disable template inlining, compiling each template in a separate method.
From the command line, you would use "-n" to turn off inlining, or with TrAX set the "disable-inlining" attribute to the TransformationFactory. For example,
```
TransformationFactory tfac = new TransformationFactory(); 
tfac.setAttribute("disable-inlining", new Boolean(true))
```
If you need this option, it is available from the current version of XSLTC at Apache.
XSLTC tries to determine the order in which global variables are initialized by tracking the dependencies between them. In some cases, the value of a variable may depend on a template, e.g., if xsl:call-template is used to initialized a variable whose type is RTF. If this happens, a NPE may be thrown at runtime when the translet attempts to access a variable that has not been properly initialized. In most cases, this problem can be avoided by reordering the variable declarations.

Using TrAX, if you specify an XML document directly as your SAX source. an NPE results. This problem has been fixed in the current version of XSLTC at Apache. However, you can work-around the problem in this release by either constructing an instance of the SAXSource from an XMLReader:

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));

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(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:

Go to http://nagoya.apache.org/bugzilla.
Select Query Existing Bug Reports.
Choose:
Program: XalanJ2 Component: org.apache.xalan.xsltc (and) Xalan-Xsltc
Submit the query.

Localization Issues

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

Custom Class Loader Issue

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.

Manually Specifying which XSLT Implementation to Use

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

Automatically Choosing with the Smart Transformer Switch

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.

JWSDP Security Considerations

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

Changes in JAXP RI Versions

Changes in JAXP RI version 1.2.0-FCS

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.

Changes In JAXP RI version 1.2.0-EA2

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.

Changes in JAXP RI version 1.2.0-EA1

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.

JavaTM API for XML Processing Release Notes

Contents