## JavaTM API for XML Processing Release Notes

Specification Version: 1.3
Reference Implementation (RI) Version: 1.3.0

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.

#### Contents

- Component Versions
- Identifying the JAR Files
- XML Parsing
  - Known Schema Processing Limitations
  - Known Migration Issues
    - from JAXP 1.1
    - from JAXP 1.2
- The Compiling XSLT Processor (XSLTC)
  - Custom Class Loader Issue
- JWSDP Security Considerations
- Changes in JAXP RI Versions

## Component Versions

These versions of the relevant technologies have been incorporated into the reference implementation.

- Xerces version 2.6.2 + (Xerces version 2.6.2 with controlled bug fixes)
- XSLTC version 2.6.0 + (XSLTC version 2.6.0 , with controlled bug fixes, based on the Xalan 2.6.0 release)

## Identifying the JAR Files

This release is contained in six JAR files:

jaxp-api.jar
  The javax.xml.parsers, javax.xml.transform, `javax.xml.xpath`, `javax.xml.validation`, `javax.xml.datatype`, and `javax.xml.namespace` components of JAXP. These packages contain the APIs that give applications a consistent way to obtain instances of XML processing implementations. The `javax.xml.xpath` package supports the standard XPath API.
sax.jar
  The APIs and helper classes for the Simple API for XML (SAX), used for serial access to XML data. The APIs support SAX version 2.0.2.
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. The APIs support DOM Level 3.
xercesImpl.jar
  The implementation classes for the SAX and DOM parsers, as well as Xerces-specific implementations of the JAXP APIs..
xalan.jar
  Contains XSLTC the compiling XSLT processor from the Xalan project.

## XML Parsing

The information in this section pertains to the Xerces technology. The latest updates can be found at http://jaxp.dev.java.net. For information on known bugs and recent fixes in the latest Apache version, see http://xml.apache.org/xerces2-j/releases.html.

### Known Schema Processing Limitations

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.

#### Implementation-Dependent Operations

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

- 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

This section covers known issues that arise when migrating from earlier versions of JAXP.

#### Migrating from JAXP 1.2

JAXP 1.2 is built into JWSDP and J2EE 1.4. These sections of the Compatibility Guide cover the relevant migration issues:

- IOException added to SAX EntityResolver API
  This is a change to the SAX 2.0.1 API.
- Methods added to DOM interfaces
  This is a change in the DOM Level 3 API.
- Package Name Changes
  This change affects applications that access implementation-specific features.

#### Migrating from JAXP 1.1

JAXP 1.1 is built into J2EE 1.3 and J2SE 1.4. For differences in functionality from JAXP 1.1, see the JAXP Compatibility Guide.

## DOM Level 3 Implementation Notes

This section contains implementation notes for DOM Level 3 Core and DOM Level 3 Load and Save.

### DOM Level 3 Core

Not implemented:

- DOMConfiguration "infoset" parameter - value "true" is not supported.

Supported parameters:

- error-handler [ DOMErrorHandler ]
- resource-resolver [ DOMResourceResolver ]
- schema-type [ String ]
- schema-location [ String ]
- canonical-form [ false ]
- cdata-sections [ true/false ]
- comments [ true/false ]
- namespaces [ true/false ]
- entities [ true/false ]
- infoset [ false ]
- namespace-declarations [ true ]
- normalize-characters [ false ]
- split-cdata-sections [ true/false ]
- validate-if-schema [ true/false ]
- whitespace-in-element-content [ true ]
- datatype-normalization [ true/false ]
- validate [ true/false ] -- revalidation is supported only against XML Schemas. For more information, please refer to How to revalidate DOM in memory? .
- validate-if-schema [ true/false ]
- check-character-normalization [ false ]
- well-formed [ true/false ]
- psvi [ true/false ] -- (NON-DOM) setting the value of this parameter to true will include PSVI information in the DOM tree. To access the information, cast dom.Element to org.apache.xerces.xs.ElementPSVI and dom.Attr to org.apache.xerces.xs.AttributePSVI.

### DOM Level 3 Load and Save

Not supported:

- LSParser parserWithContext
- DOMImplementationLS MODE_ASYNCHRONOUS
- LSSerializer - the following parameters are not supported:

- ignore-unknown-character-denormalizations [ true ]
- normalize-characters [ true ]
- well-formed [ true ]

## The Compiling XSLT Processor (XSLTC)

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.

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

### Custom Class Loader Issue

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.

## JWSDP Security Considerations

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 `FactoryConfigurationError` is thrown that says:
> Provider org.apache.xerces.jaxp.SAXParserFactoryImpl not found

## Changes in JAXP RI Versions

### Changes in JAXP RI version 1.3

- Xerces version changed from 2.3.0 to 2.6.2 (+ controlled bug fixes).
- The two XSL transformation engines available in the standalone version of JAXP 1.3 are Xalan interpretive and XSLTC (based on Xalan 2.6.0 (+ controlled bugfixes)). The JAXP 1.3 version included in J2SE 5 includes only the XSLTC transformer (based on Xalan 2.6.0 (+ controlled bug fixes)).
- New features and functionality added, as described in the What's New section of the Compatibility Guide.
- A denial of service vulnerability was rectified by adding the system property elementAttributeLimit, which can be used to limit the number of attributes in a element. The default limit is 10,000 attributes for an element.

### Changes in JAXP RI version 1.2.4

- Fix for a J2SE 1.4.2 compilation bug in Xerces.

### Changes in JAXP RI version 1.2.3

- Xerces version changed from 2.2.1 to 2.3.0 (+ controlled bug fixes). This version Includes many bug fixes.
- All Decimal value that should be invalid according to the Schema specification are now found by the parser (removing a 1.2.2 limitation).
- Solved the problem of Xerces compilation under JDK 1.4.1.
- XML Schema loading performance improved dramatically (virtually cut in half).

### Changes in JAXP RI version 1.2.2

- New properties were implemented for increased security, as described in the Security Issue section.
- Parser implementation changed from Xerces 2.0.1_04 to Xerces 2.2.1 with controlled bug fixes.
- XSLT processor imlpementation changed from Xalan 2.3.1_01 to Xalan 2.4.1 with controlled bug fixes..
- XSLTC is included in this release.

### Changes in JAXP Ri version 1.2.1

Performance of Xerces parser improved significantly.

XSLTC was not included as part of this release, which was destined solely for the J2EE platform.

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