JSR 206 Java API for XML Processing (JAXP) 1.3 - Oracle Software ...

JSR 206 Java API for XML Processing 

(JAXP) 1.3 

Jeff Suttor 

Norman Walsh 

Kohsuke Kawaguchi

Community Draft 


JSR 206 Java API for XML Processing (JAXP) 1.3 

by Jeff Suttor, Norman Walsh, and Kohsuke Kawaguchi 

Copyright ' 2003 Sun Microsystems, Inc. 

Public Draft for Public Review 

The JSR 206 Java API for XML Processing (JAXP) 1.3 Expert Group would like to thank participants in the Java 

Community that are reviewing this Java Specification Request. All comments, feedback and guidance from the Java 

Community is appreciated. 

A list of open issues follows in the next section. In addition, a dynamic list of open issues and electronic artifacts is 

being maintained at JSR206-Public.Dev.Java.Net [http://jsr206-public.dev.java.net/] under File sharing 

[https://jsr206-public.dev.java.net/servlets/ProjectDocumentList] in Project tools. 

Please submit comments to . 

Java API for XML Processing (JAXP) Specification ("Specification") Version: 1.3 Public 

Draft 1.0.0 Status: pre-FCS, Release: December 16, 2003 

Copyright 2003 Sun Microsystems, Inc. 

4150 Network Circle, Santa Clara, California 95054, U.S.A. 

All rights reserved. 

NOTICE 

The Specification is protected by copyright and the information described therein may be protected by one or more U.S. patents, foreign patents, 

or pending applications. Except as provided under the following license, no part of the Specification may be reproduced in any form by any means 

without the prior written authorization of Sun Microsystems, Inc. ("Sun") and its licensors, if any. Any use of the Specification and the information 

described therein will be governed by the terms and conditions of this Agreement. 

Subject to the terms and conditions of this license, Sun hereby grants you a fully-paid, non-exclusive, non-transferable, limited license (without the 

right to sublicense) under Sun’s intellectual property rights to review the Specification only for the purposes of evaluation. This license includes 

the right to discuss the Specification (including the right to provide limited excerpts of text to the extent relevant to the point[s] under discussion) 

with other licensees (under this or a substantially similar version of this Agreement) of the Specification. Other than this limited license, you acquire 

no right, title or interest in or to the Specification or any other Sun intellectual property, and the Specification may only be used in accordance with 

the license terms set forth herein. This license will expire on the earlier of: (i) two (2) years from the date of Release listed above; (ii) the date on 

which the final version of the Specification is publicly released; or (iii) the date on which the Java Specification Request (JSR) to which the Spe 

cification corresponds is withdrawn. In addition, this license will terminate immediately without notice from Sun if you fail to comply with any 

provision of this license. Upon termination, you must cease use of or destroy the Specification. 

TRADEMARKS 

No right, title, or interest in or to any trademarks, service marks, or trade names of Sun or Sun’s licensors is granted hereunder. Sun, Sun Microsystems, 

the Sun Microsystems logo, Java, and the Java Coffee Cup logo are trademarks or registered trademarks of the Sun Microsystems, Inc. in the U.S. 

and other countries. 

DISCLAIMER OF WARRANTIES 

THE SPECIFICATION IS PROVIDED "AS IS" AND IS EXPERIMENTAL AND MAY CONTAIN DEFECTS OR DEFICIENCIES WHICH 

CANNOT OR WILL NOT BE CORRECTED BY SUN. SUN MAKES NO REPRESENTATIONS OR WARRANTIES, EITHER EXPRESS OR 

IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 

OR NON-INFRINGEMENT THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE OR THAT ANY 

PRACTICE OR IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADE 

SECRETS OR OTHER RIGHTS. This document does not represent any commitment to release or implement any portion of the Specification in 

any product. 

THE SPECIFICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY 

ADDED TO THE INFORMATION THEREIN; THESE CHANGES WILL BE INCORPORATED INTO NEW VERSIONS OF THE SPECIFIC 

ATION, IF ANY. SUN MAY MAKE IMPROVEMENTS AND/OR CHANGES TO THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED



IN THE SPECIFICATION AT ANY TIME. Any use of such changes in the Specification will be governed by the then-current license for the ap 

plicable version of the Specification. 

LIMITATION OF LIABILITY 

TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY DAMAGES, IN 

CLUDING WITHOUT LIMITATION, LOST REVENUE, PROFITS OR DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCID 

ENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF OR 

RELATED TO ANY FURNISHING, PRACTICING, MODIFYING OR ANY USE OF THE SPECIFICATION, EVEN IF SUN AND/OR ITS 

LICENSORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 

You will hold Sun (and its licensors) harmless from any claims based on your use of the Specification for any purposes other than the limited right 

of evaluation as described above, and from any claims that later versions or releases of any Specification furnished to you are incompatible with 

the Specification provided to you under this license. 

RESTRICTED RIGHTS LEGEND 

If this Software is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime contractor or subcontractor (at any tier), 

then the Government’s rights in the Specification and accompanying documentation shall be only as set forth in this license; this is in accordance 

with 48 C.F.R. 227.7201 through 227.7202-4 (for Department of Defense (DoD) acquisitions) and with 48 C.F.R. 2.101 and 12.212 (for non-DoD 

acquisitions). 

REPORT 

You may wish to report any ambiguities, inconsistencies or inaccuracies you may find in connection with your evaluation of the Specification 

("Feedback"). To the extent that you provide Sun with any Feedback, you hereby: (i) agree that such Feedback is provided on a non-proprietary and 

non-confidential basis, and (ii) grant Sun a perpetual, non-exclusive, worldwide, fully paid-up, irrevocable license, with the right to sublicense 

through multiple levels of sublicensees, to incorporate, disclose, and use without limitation the Feedback for any purpose related to the Specification 

and future versions, implementations, and test suites thereof. 

GENERAL TERMS 

Any action related to this Agreement will be governed by California law and controlling U.S. federal law. The U.N. Convention for the International 

Sale of Goods and the choice of law rules of any jurisdiction will not apply. 

The Specification is subject to U.S. export control laws and may be subject to export or import regulations in other countries. Licensee agrees to 

comply strictly with all such laws and regulations and acknowledges that it has the responsibility to obtain such licenses to export, re-export or import 

as may be required after delivery to Licensee. 

Neither party may assign or otherwise transfer any of its rights or obligations under this Agreement, without the prior written consent of the other 

party, except that Sun may assign this Agreement to an affiliated company. 

This Agreement is the parties’ entire agreement relating to its subject matter. It supersedes all prior or contemporaneous oral or written communic 

ations, proposals, conditions, representations and warranties and prevails over any conflicting or additional terms of any quote, order, acknowledgment, 

or other communication between the parties relating to its subject matter during the term of this Agreement. No modification to this Agreement will 

be binding, unless in writing and signed by an authorized representative of each party.



Table of Contents 

1. Open Issues ..................................................................................................................................... 1 

2. Overview ........................................................................................................................................ 3 

What is XML? ............................................................................................................................ 3 

XML and the Java Platform ........................................................................................................... 3 

About This Specification ............................................................................................................... 3 

Who Should Read This Document .................................................................................................. 4 

Report and Contact ...................................................................................................................... 4 

Development of This Specification ................................................................................................. 4 

Acknowledgments ....................................................................................................................... 5 

3. Endorsed Specifications ..................................................................................................................... 6 

Extensible Markup Language (XML) .............................................................................................. 6 

Namespaces in XML .................................................................................................................... 6 

XML Schema ............................................................................................................................. 6 

XSL Transformations (XSLT) ........................................................................................................ 6 

XML Path Language (XPath) ......................................................................................................... 7 

XML Inclusions (XInclude) ........................................................................................................... 7 

Document Object Model (DOM) Level 3 ......................................................................................... 7 

Simple API for XML (SAX) .......................................................................................................... 7 

4. Plugability Layer .............................................................................................................................. 9 

SAX Plugability .......................................................................................................................... 9 

Examples ........................................................................................................................... 9 

DOM Plugability ....................................................................................................................... 10 

Reliance on SAX API ......................................................................................................... 11 

Examples ......................................................................................................................... 11 

XSLT Plugability ....................................................................................................................... 12 

Examples ......................................................................................................................... 12 

Thread Safety ............................................................................................................................ 17 

Properties For Enabling Schema Validation .................................................................................... 18 

Samples Using the Properties ............................................................................................... 20 

Recommended Implementation of Properties ................................................................................... 21 

5. Conformance Requirements .............................................................................................................. 22 

6. XML Inclusions (XInclude) .............................................................................................................. 23 

What is XML Inclusions (XInclude) .............................................................................................. 23 

Implementation Required by JSR 206 Java API for XML Processing (JAXP) 1.3 ................................... 23 

7. JSR 206 Java API for XML Processing (JAXP) 1.3 Specification and Implementation Version Information ..... 24 

JSR 206 Java API for XML Processing (JAXP) 1.3 Specification Version Information ............................ 24 

JSR 206 Java API for XML Processing (JAXP) 1.3 Implementation Version Information ........................ 24 

JSR 206 Java API for XML Processing (JAXP) 1.3 Full Specification and Implementation Version Inform 

ation ........................................................................................................................................ 24 

8. Package javax.xml.parsers ................................................................................................................ 26 

Class DocumentBuilder ............................................................................................................... 26 

Synopsis .......................................................................................................................... 26 

Members .......................................................................................................................... 27 

Class DocumentBuilderFactory .................................................................................................... 31 

Synopsis .......................................................................................................................... 31 

Members .......................................................................................................................... 32 

Class SAXParser ....................................................................................................................... 38 

Synopsis .......................................................................................................................... 39 

Members .......................................................................................................................... 40 

Class SAXParserFactory ............................................................................................................. 48 

Synopsis .......................................................................................................................... 48 

iv





Members .......................................................................................................................... 49 

Exception ParserConfigurationException ........................................................................................ 54 

Synopsis .......................................................................................................................... 54 

Members .......................................................................................................................... 54 

Error FactoryConfigurationError ................................................................................................... 55 

Synopsis .......................................................................................................................... 55 

Members .......................................................................................................................... 55 

9. Package javax.xml.transform ............................................................................................................ 57 

Creating Objects ........................................................................................................................ 57 

Specification of Inputs and Outputs ....................................................................................... 57 

Class OutputKeys ...................................................................................................................... 59 

Synopsis .......................................................................................................................... 59 

Members .......................................................................................................................... 59 

Class Transformer ...................................................................................................................... 62 

Synopsis .......................................................................................................................... 62 

Members .......................................................................................................................... 63 

Class TransformerFactory ............................................................................................................ 68 

Synopsis .......................................................................................................................... 68 

Members .......................................................................................................................... 69 

Interface ErrorListener ................................................................................................................ 73 

Synopsis .......................................................................................................................... 73 

Members .......................................................................................................................... 74 

Interface Result ......................................................................................................................... 75 

Synopsis .......................................................................................................................... 75 

Members .......................................................................................................................... 75 

Interface Source ......................................................................................................................... 76 

Synopsis .......................................................................................................................... 76 

Members .......................................................................................................................... 76 

Interface SourceLocator .............................................................................................................. 77 

Synopsis .......................................................................................................................... 77 

Members .......................................................................................................................... 77 

Interface Templates .................................................................................................................... 78 

Synopsis .......................................................................................................................... 78 

Members .......................................................................................................................... 79 

Interface URIResolver ................................................................................................................ 79 

Synopsis .......................................................................................................................... 79 

Members .......................................................................................................................... 80 

Exception TransformerConfigurationException ............................................................................... 80 

Synopsis .......................................................................................................................... 80 

Members .......................................................................................................................... 81 

Exception TransformerException .................................................................................................. 82 

Synopsis .......................................................................................................................... 82 

Members .......................................................................................................................... 83 

Error TransformerFactoryConfigurationError .................................................................................. 87 

Synopsis .......................................................................................................................... 87 

Members .......................................................................................................................... 87 

10. Package javax.xml.transform.dom .................................................................................................... 89 

Class DOMResult ...................................................................................................................... 89 

Synopsis .......................................................................................................................... 89 

Members .......................................................................................................................... 90 

Class DOMSource ..................................................................................................................... 94 

Synopsis .......................................................................................................................... 94 

Members .......................................................................................................................... 95 

Interface DOMLocator ................................................................................................................ 96 

v





Synopsis .......................................................................................................................... 96 

Members .......................................................................................................................... 96 

11. Package javax.xml.transform.sax ..................................................................................................... 97 

Class SAXResult ....................................................................................................................... 97 

Synopsis .......................................................................................................................... 98 

Members .......................................................................................................................... 98 

Class SAXSource ..................................................................................................................... 100 

Synopsis ......................................................................................................................... 100 

Members ........................................................................................................................ 100 

Class SAXTransformerFactory ................................................................................................... 102 

Synopsis ......................................................................................................................... 103 

Members ........................................................................................................................ 103 

Interface TemplatesHandler ........................................................................................................ 106 

Synopsis ......................................................................................................................... 106 

Members ........................................................................................................................ 106 

Interface TransformerHandler ..................................................................................................... 106 

Synopsis ......................................................................................................................... 107 

Members ........................................................................................................................ 107 

12. Package javax.xml.transform.stream ............................................................................................... 109 

Class StreamResult ................................................................................................................... 109 

Synopsis ......................................................................................................................... 109 

Members ........................................................................................................................ 110 

Class StreamSource .................................................................................................................. 112 

Synopsis ......................................................................................................................... 112 

Members ........................................................................................................................ 113 

13. Package javax.xml.namespace ....................................................................................................... 117 

Class QName .......................................................................................................................... 117 

Synopsis ......................................................................................................................... 117 

Members ........................................................................................................................ 118 

Interface NamespaceContext ...................................................................................................... 122 

Synopsis ......................................................................................................................... 122 

Members ........................................................................................................................ 123 

14. Package javax.xml.xpath .............................................................................................................. 126 

About XPath ........................................................................................................................... 126 

XPath Examples ............................................................................................................... 126 

Class XPathConstants ............................................................................................................... 128 

Synopsis ......................................................................................................................... 128 

Members ........................................................................................................................ 129 

Class XPathFactory .................................................................................................................. 130 

Synopsis ......................................................................................................................... 130 

Members ........................................................................................................................ 130 

Interface XPath ........................................................................................................................ 131 

Synopsis ......................................................................................................................... 132 

Members ........................................................................................................................ 133 

Interface XPathExpression ......................................................................................................... 139 

Synopsis ......................................................................................................................... 140 

Members ........................................................................................................................ 140 

Interface XPathFunction ............................................................................................................ 144 

Synopsis ......................................................................................................................... 144 

Members ........................................................................................................................ 144 

Interface XPathFunctionResolver ................................................................................................ 145 

Synopsis ......................................................................................................................... 145 

Members ........................................................................................................................ 145 

Interface XPathVariableResolver ................................................................................................ 146 

vi





Synopsis ......................................................................................................................... 146 

Members ........................................................................................................................ 146 

Exception XPathException ......................................................................................................... 147 

Synopsis ......................................................................................................................... 147 

Members ........................................................................................................................ 147 

Exception XPathExpressionException .......................................................................................... 148 

Synopsis ......................................................................................................................... 148 

Members ........................................................................................................................ 149 

Exception XPathFactoryConfigurationException ............................................................................ 150 

Synopsis ......................................................................................................................... 150 

Members ........................................................................................................................ 151 

Exception XPathFunctionException ............................................................................................. 152 

Synopsis ......................................................................................................................... 152 

Members ........................................................................................................................ 152 

15. Package javax.xml.validation ........................................................................................................ 154 

Class AbstractSchemaImpl ......................................................................................................... 154 

Synopsis ......................................................................................................................... 154 

Members ........................................................................................................................ 154 

Class Schema .......................................................................................................................... 155 

Synopsis ......................................................................................................................... 155 

Members ........................................................................................................................ 156 

Class SchemaFactory ................................................................................................................ 156 

Schema Language ............................................................................................................ 156 

Synopsis ......................................................................................................................... 157 

Members ........................................................................................................................ 158 

Class SchemaFactoryFinder ....................................................................................................... 167 

Resolution Process ........................................................................................................... 167 

Synopsis ......................................................................................................................... 168 

Members ........................................................................................................................ 169 

Class SchemaFactoryLoader ....................................................................................................... 169 

Synopsis ......................................................................................................................... 170 

Members ........................................................................................................................ 170 

Class TypeInfoProvider ............................................................................................................. 171 

Synopsis ......................................................................................................................... 171 

Members ........................................................................................................................ 171 

Class Validator ........................................................................................................................ 174 

Synopsis ......................................................................................................................... 174 

Members ........................................................................................................................ 175 

Class ValidatorHandler ............................................................................................................. 181 

Recognized Properties and Features ..................................................................................... 182 

Synopsis ......................................................................................................................... 182 

Members ........................................................................................................................ 183 

16. Package javax.xml.datatype ........................................................................................................... 190 

Class Duration ......................................................................................................................... 190 

Order relationship ............................................................................................................ 190 

Synopsis ......................................................................................................................... 191 

Members ........................................................................................................................ 192 

Class Duration.Field ................................................................................................................. 206 

Synopsis ......................................................................................................................... 206 

Members ........................................................................................................................ 206 

Class XMLGregorianCalendar .................................................................................................... 206 

Synopsis ......................................................................................................................... 209 

Members ........................................................................................................................ 212 

17. Package javax.xml ....................................................................................................................... 233 

vii





Class AbstractVersion ............................................................................................................... 233 

Synopsis ......................................................................................................................... 233 

Members ........................................................................................................................ 234 

Class SecureProcessing ............................................................................................................. 234 

Synopsis ......................................................................................................................... 234 

Members ........................................................................................................................ 235 

Class Version .......................................................................................................................... 236 

Synopsis ......................................................................................................................... 237 

Members ........................................................................................................................ 237 

Class VersionImpl .................................................................................................................... 239 

Synopsis ......................................................................................................................... 239 

Members ........................................................................................................................ 240 

Class XMLConstants ................................................................................................................ 241 

Synopsis ......................................................................................................................... 241 

Members ........................................................................................................................ 241 

Class XMLUtils ....................................................................................................................... 243 

Synopsis ......................................................................................................................... 243 

Members ........................................................................................................................ 244 

18. Change History ........................................................................................................................... 246 

From 1.1 final release to 1.2 final release ...................................................................................... 246 

From 1.1 Proposed Final Draft to 1.1 Final Release ......................................................................... 246 

From 1.1 Public Review 2 to Proposed Final Draft .......................................................................... 246 

From 1.1 Public Review 1 to 1.1 Public Review 2 .......................................................................... 246 

From 1.0 Final Release to 1.1 Public Review ................................................................................. 246 

From 1.0 Public Release to 1.0 Final Release ................................................................................. 247 

From 1.0 Public Review to 1.0 Public Release ............................................................................... 247 

A. Change Log ................................................................................................................................ 248 

19. Colophon ................................................................................................................................... 249 

Talk the Talk, Walk the Walk ..................................................................................................... 249 

viii



List of Tables 

19.1. XML Usage Conventions ........................................................................................................... 249 

ix



Chapter 1. Open Issues 

Introduction 

The JSR 206 Java API for XML Processing (JAXP) 1.3 Expert Group would like to thank participants in the Java 

Community that are reviewing this Java Specification Request. All comments, feedback and guidance from the Java 

Community is appreciated. 

Please submit comments to . 

A dynamic version of the open issues and electronic artifacts is being maintained at JSR206-Public.Dev.Java.Net 

[http://jsr206-public.dev.java.net/] under File sharing [https://jsr206-public.dev.java.net/servlets/ProjectDocumentList] 

in Project tools. Please see this on-line version for the most current open issues and electronic artifacts. 

If you are viewing this on-line and wish to have the links resolve to a downloaded copy of the 

Public Draft, take the following steps: 

1. Download the Public Draft in XHTML or HTML format from JSR206-Public.Dev.Java.Net 

[http://jsr206-public.dev.java.net/] under File sharing 

[https://jsr206-public.dev.java.net/servlets/ProjectDocumentList] in Project tools. 

2. Unzip the downloaded file into a local directory. 

3. Save this file into the downloaded directory. If you downloaded the XHTML version of the Public Draft, download 

the XHTML version of this document. If you downloaded the HTML version of the Public Draft, download the 

HTML version of this document. 

4. All links in this document are relative links so they will now be resolved to the local copy of the specification. 

The Expert Group would like to call specific attention to and solicit explicit feedback and guidance on the following 

parts of the API. 

XML 1.1 and SAX 

In order to process XML 1.1, one must use SAX extensions [http://www.saxproject.org/?selected=ext]. The SAX ex 

tensions are are labeled "beta1". Although labeled "beta1", they have been stable and in wide use for a long period of 

time. 

Input [mailto:JSR-206-comments@JCP.org] is requested as to if it is acceptable to use the SAX extensions as they 

exist today or an effort in the SAX community should be made to: 

1. move the SAX extensions to a "final" designation 

2. move the SAX extensions necessary for XML 1.1 to SAX core 

Validation 

Validation has now been decoupled from parsing. It is now possible to parse/process/cache/etc grammars with the 

javax.xml.validation package. Input [mailto:JSR-206-comments@JCP.org] is requested for reasonable use cases for 

for both J2SE and J2EE applications to insure that the full spectrum of expectations and needs are met. 

Secure Processing 

There are several known Denial of Service exploits when processing XML. Some security exposures are inherit in the 

XML processing model and some are implementation dependent. 

1


Open Issues 


A preliminary Secure Processing model, javax.xml.SecureProcessing, has been included in this Public Draft. It is ex 

pected that this security model will change based on Public Review. 

Input [mailto:JSR-206-comments@JCP.org] is requested as to the desired security model that insures interoperability 

yet allows for implementation dependent secure processing as required by the application. Examples would include: 

boolean set/get method 

property/feature 

XInclude Processing 

The ability to enable/disable/query the state of XInclude processing is available for javax.xml.parsers.DocumentBuild 

erFactory and javax.xml.parsers.SAXParserFactory . The Expert Group has not been provided nor able to determine 

any reasonable use cases to provide the ability to modify the state of XInclude processing for javax.xml.parsers.Doc 

umentBuilder and javax.xml.parsers.SAXParser . Input [mailto:JSR-206-comments@JCP.org] is requested for reas 

onable use cases that require such functionality. 

2



Chapter 2. Overview 

What is XML? 

XML is the meta language defined by the World Wide Web Consortium (W3C) that can be used to describe a broad 

range of hierarchical mark up languages. It is a set of rules, guidelines, and conventions for describing structured data 

in a plain text, editable file. Using a text format instead of a binary format allows the programmer or even an end user 

to look at or utilize the data without relying on the program that produced it. However the primary producer and consumer 

of XML data is the computer program and not the end-user. 

Like HTML, XML makes use of tags and attributes. Tags are words bracketed by the "<" and ">" characters 

and attributes are strings of the form ’name="value"’ that are inside of tags. While HTML specifies what each tag 

and attribute means, as well as their presentation attributes in a browser, XML uses tags only to delimit pieces of data 

and leaves the interpretation of the data to the application that uses it. In other words, XML defines only the structure 

of the document and does not define any of the presentation semantics of that document. 

Development of XML started in 1996 leading to a W3C Recommendation in February of 1998. However, the technology 

is not entirely new. It is based on SGML (Standard Generalized Markup Language) which was developed in the early 

1980’s and became an ISO standard in 1986. SGML has been widely used for large documentation projects and there 

is a large community that has experience working with SGML. The designers of XML took the best parts of SGML, 

used their experience as a guide and produced a technology that is just as powerful as SGML, but much simpler and 

easier to use. 

XML-based documents can be used in a wide variety of applications including vertical markets, e-commerce, businessto-business 

communication, and enterprise application messaging. 

XML and the Java Platform 

In many ways, XML and the Java Platform are a partnership made in heaven. XML defines a cross platform data format 

and Java provides a standard cross platform programming platform. Together, XML and Java technologies allow pro 

grammers to apply Write Once, Run Anywhere fundamentals to the processing of data and documents generated by 

both Java based programs and non-Java based programs. 

About This Specification 

This document describes the Java API for XML Processing, Version 1.3. This version of the specification introduces 

basic support for parsing and manipulating XML documents through a standardized set of Java Platform APIs. 

When this specification is final there will be a Reference Implementation which will demonstrate the capabilities of 

this API and will provide an operational definition of the specification. A Technology Compatibility Kit (TCK) will 

also be available that will verify whether an implementation of this specification is compliant. These are required as 

per the Java Community Process 2.5 (JCP 2.5). 

Note 

API references are accompanied by a small-font subscript that gives the page on which the API is defined. 

For example: 

newDocumentBuilder 

3


Overview 


Who Should Read This Document 

This specification is intended for use by: 

• Parser Developers wishing to implement this version of the specification in their parser. 

• Application Developers who use the APIs described in this specification and wish to have a more complete under 

standing of the API. 

Note 

We are looking for feedback on the XPath API in the javax.xml.xpath package. This is new functionality that 

we are adding in JSR 206 along with Grammar Caching. We want this API to be extensible so that it is easy 

to build XPath 2.0 functionality on top of this API. Please keep this goal in mind while reviewing the XPath 

API. 

This specification is not a tutorial or a user’s guide to XML, DOM, SAX or XSLT. Familiarity with these technologies 

and specifications on the part of the reader is assumed. 

Report and Contact 

Your comments on this specification are welcome and appreciated. Without your comments, the specifications developed 

under the auspices of the Java Community Process would not serve your needs as well. To comment on this specification, 

please send email to . 

You can stay current with Sun’s Java Platform related activities, as well as information on our 

and mailing lists, at our website [http://java.sun.com/xml/jaxp]. 

Development of This Specification 

This specification was developed in accordance with the Java Community Process [http://www.jcp.org] 2.5. It was 

developed under the authorization of Java Specification Request 206 [http://jcp.org/en/jsr/detail?id=206]. 

The expert group who contributed to this specification is composed of individuals from a number of companies. These 

individuals are: 

• Jeff Suttor (Specification Lead), Sun Microsystems, Inc. 

• Norm Walsh (Specification Lead), Sun Microsystems, Inc. 

• Kohsuke Kawaguchi (Markup Geek), Sun Microsystems, Inc. 

• Ben Galbraith 

• Neil Graham, IBM 

• Phil Hanna, SAS Institute Inc. 

• Todd Karakashian, bea 

• K. Karun, Oracle 

• Dongeun Kim, Tmax Soft, Inc. 

4


Overview 


• Harish Krishnaswamy, Novell, Inc. 

• Miles Sabin 

• Vladimir Savchenko, SAP AG 

• Ilene Seelemann, IBM 

• Henry Zongaro, IBM 

We would like to acknowledge that a lot of the grammar caching work introduced in this version of the specification 

was derived from the work being done under the Xerces project at Apache. 

Acknowledgments 

Many individuals and companies have given their time and talents to make this specification, or the specifications that 

this specification relies upon, a reality. The authors of this specification would like to thank (in no particular order): 

• David Brownell, David Megginson and the XML-DEV community who developed the SAX API 

• The W3C DOM Working Group chaired by Philippe Le Hégaret 

• The Apache Software Foundation [http://apache.org/], for Xerces and Xalan 

• Michael Kay, Software AG 

• Elliotte Rusty Harold, Cafe con Leche XML News and Resources [http://www.cafeconleche.org/], Cafe au Lait 

Java News and Resources [http://www.cafeaulait.org/] 

• Han Ming Ong, Apple 

• Eduardo Pelegri-Lopart, Tom Kincaid, Connie Weiss, Gopal Sharma, Neeraj Bajaj, K. Venugopal, Arun Yadav, 

Ramesh Mandava, Bhakti Mehta, Prasad Subramanian, Todd Miller, Joesph Fialli, and Rajiv Mordani all of whom 

work at Sun Microsystems, Inc. and whose talents have all reflected upon the development of this API. 

• Margaret, Mark, Magita and the unmet transformative change agents who remind us that with trust and commitment, 

"it’s all true." 

5



Chapter 3. Endorsed Specifications 

This specification endorses and builds upon several external specifications. Each specification endorsed by this document 

is called out together with the exact version of the specification and its publicly accessible location. All of these 

standards have conformance tests provided in the Technology Compatibility Kit available for this specification. 

Extensible Markup Language (XML) 

This specification supports Extensible Markup Language (XML) 1.1 [http://www.w3.org/TR/xml11], Extensible 

Markup Language (XML) 1.0 (Second Edition) [http://www.w3.org/TR/REC-xml] and Extensible Markup Language 

(XML) 1.0 (Second Edition) Errata [http://www.w3.org/XML/xml-V10-2e-errata] 

XML is a product of the W3C XML Activity [http://www.w3.org/XML/]. 

This specification includes by reference Extensible Markup Language (XML) 1.1, Extensible Markup Language (XML) 

1.0 (Second Edition) and Extensible Markup Language (XML) 1.0 (Second Edition) Errata in their entirety for the 

purposes of defining XML in the APIs defined herein. 

Namespaces in XML 

This specification supports Namespaces in XML 1.1. [http://www.w3.org/TR/xml-names11/], Namespaces in XML 

1.0 [http://www.w3.org/TR/REC-xml-names] and Namespaces in XML 1.0 Errata 

[http://www.w3.org/XML/xml-names-19990114-errata]. 

Namespaces in XML is a product of the W3C XML Activity [http://www.w3.org/XML/]. 

This specification includes by reference Namespaces in XML 1.1, Namespaces in XML 1.0 and Namespaces in XML 

1.0 Errata, in their entirety for the purposes of defining Namespaces in XML in the APIs defined herein. 

XML Schema 

This specification supports XML Schema Part 1: Structures [http://www.w3.org/TR/xmlschema-1/], XML Schema 

Part 1: Structures Errata [http://www.w3.org/2001/05/xmlschema-errata#Errata1], XML Schema Part 2: Datatypes 

[http://www.w3.org/TR/xmlschema-2/] and XML Schema Part 2: Datatypes Errata 

[http://www.w3.org/2001/05/xmlschema-errata#Errata2]. 

XML Schema is a product of the XML Schema Working Group [http://www.w3.org/XML/Schema]. 

This specification includes by reference XML Schema Part 1: Structures, XML Schema Part 1: Structures Errata, XML 

Schema Part 2: Datatypes and XML Schema Part 2: Datatypes Errata in their entirety for the purposes of defining 

XML Schema in the APIs defined herein. 

XSL Transformations (XSLT) 

This specification supports XSL Transformations (XSLT) Version 1.0 [http://www.w3.org/TR/xslt]. 

XSLT is a product of the W3C Style Activity [http://www.w3.org/Style/Activity]. 

This specification includes by reference XSL Transformations (XSLT) Version 1.0 in its entirety for the purposes of 

defining XSLT in the APIs defined herein. 

6


Endorsed Specifications 


XML Path Language (XPath) 

This specification supports XML Path Language (XPath) Version 1.0 [http://www.w3.org/TR/xpath] and XML Path 

Language (XPath) Version 1.0 Errata [http://www.w3.org/1999/11/REC-xpath-19991116-errata]. 

XPath is a product of the W3C XML Activity [http://www.w3.org/XML/Activity] and W3C Style Activity 

[http://www.w3.org/Style/Activity]. 

This specification includes by reference XML Path Language (XPath) Version 1.0 and XML Path Language (XPath) 

Version 1.0 Errata in their entirety for the purposes of defining SAX in the APIs defined herein. 

XML Inclusions (XInclude) 

This specification supports XML Inclusions (XInclude) Version 1.0 [http://www.w3.org/TR/xinclude/]. 

XInclude is a product of the W3C XML Core Working Group [http://www.w3.org/XML/Core/] as part of the W3C 

XML Activity [http://www.w3.org/XML/Activity]. 

This specification includes by reference XML Inclusions (XInclude) Version 1.0. in its entirety for the purposes of 

defining XInclude in the APIs defined herein. 

Document Object Model (DOM) Level 3 

This specification supports Document Object Model (DOM) Level 3 Core [http://www.w3.org/TR/DOM-Level-3-Core] 

and Document Object Model (DOM) Level 3 Load and Save [http://www.w3.org/TR/DOM-Level-3-LS]. 

DOM Level 3 is a product of the W3C DOM Activity [http://www.w3.org/DOM/]. 

This specification includes by reference Document Object Model (DOM) Level 3 Core and Document Object Model 

(DOM) Level 3 Load and Save in their entirety for the purposes of defining SAX in the APIs defined herein. 

The API packages included by reference are: 

• org.w3c.dom 

• org.w3c.dom.bootstrap 

• org.w3c.dom.ls 

• org.w3c.dom.ranges 

• org.w3c.dom.traversal 

Simple API for XML (SAX) 

This specification supports Simple API for XML (SAX) 2.0.1 (sax2 r2) [http://www.saxproject.org/] and Simple API 

for XML (SAX) 2.0.1 (sax2 r2) Extensions [http://www.saxproject.org/?selected=ext]. 

SAX is a product of the SAX Community [http://www.saxproject.org/]. 

This specification includes by reference Simple API for XML (SAX) 2.0.1 (sax2 r2) and Simple API for XML (SAX) 

2.0.1 (sax2 r2) Extensions in their entirety for the purposes of defining SAX in the APIs defined herein. 

7


Endorsed Specifications 


The API packages included by reference are: 

• org.xml.sax 

• org.xml.sax.ext 

• org.xml.sax.helpers 

8



Chapter 4. Plugability Layer 

The endorsed APIs provide broad and useful functionality. However, the use of a SAX or a DOM parser typically requires 

knowledge of the specific implementation of the parser. Providing the functionality of the endorsed APIs in the Java 

Platform, while allowing choice of the implementation of the parser, requires a Plugability layer. 

This section of the specification defines a Plugability mechanism to allow a compliant SAX or DOM parser to be used 

through the abstract javax.xml.parsers and javax.xml.transform API. 

SAX Plugability 

Examples 

The SAX Plugability classes allow an application programmer to provide an implementation of the 

org.xml.sax.DefaultHandler API to a SAXParser implementation and parse XML documents. As the 

parser processes the XML document, it will call methods on the provided DefaultHandler. 

In order to obtain a SAXParser instance, an application programmer first obtains an instance of a SAXParserFact 

ory. The SAXParserFactory instance is obtained via the static newInstance method of the SAXParserFact 

ory class. 

This method uses the following ordered lookup procedure to determine the SAXParserFactory implementation class 

to load: 

• Use the javax.xml.parsers.SAXParserFactory system property. 

• Use the properties file "lib/jaxp.properties" in the JRE directory. This configuration file is in standard 

java.util.Properties format and contains the fully qualified name of the implementation class with the key being 

the system property defined above. The jaxp.properties file is read only once by the JSR 206 Java API for XML 

Processing (JAXP) 1.3 implementation and it’s values are then cached for future use. If the file does not exist when 

the first attempt is made to read from it, no further attempts are made to check for its existence. It is not possible 

to change the value of any property in jaxp.properties after it has been read for the first time. 

• Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services 

API will look for the classname in the file META-INF/services/javax.xml.parsers.SAXParserFactory in jars 

available to the runtime. 

• Platform default SAXParserFactory instance. 

If the SAXParserFactory implementation class cannot be loaded or instantiated at runtime, a FactoryConfig 

urationError is thrown. This error message should contain a descriptive explanation of the problem and how the 

user can resolve it. 

The instance of SAXParserFactory can optionally be configured by the application programmer to provide parsers 

that are namespace aware, or validating, or both. These settings are made using the setNamespaceAware and 

setValidating methods of the factory. The application programmer can then obtain a SAXParser implementation 

instance from the factory. If the factory cannot provide a parser configured as set by the application programmer, then 

a ParserConfigurationException is thrown. 

The following is a simple example of how to parse XML content from a URL: 

SAXParser parser; 

9


Plugability Layer 


DefaultHandler handler = new MyApplicationParseHandler(); 

SAXParserFactory factory = SAXParserFactory.newInstance(); 

try { 

parser = factory.newSAXParser(); 

parser.parse("http://myserver/mycontent.xml", handler); 

} catch (SAXException se) { 

// handle error 

} catch (IOException ioe) { 


} catch (ParserConfigurationException pce) { 


} 

The following is an example of how to configure a SAX parser to be namespace aware and validating: 

SAXParser parser; 

DefaultHandler handler = new MyApplicationParseHandler(); 

SAXParserFactory factory = SAXParserFactory.newInstance(); 

factory.setNamespaceAware(true); 

factory.setValidating(true); 

try { 

parser = factory.newSAXParser(); 

parser.parse("http://myserver/mycontent.xml", handler); 







} 

An example of how one could pass the System property as a command line option is: 

java -Djavax.xml.parsers.SAXParserFactory=org.apache.xerces.jaxp.SAXParserFactoryImpl user.parserApp 

DOM Plugability 

The DOM plugability classes allow a programmer to parse an XML document and obtain an org.w3c.dom.Docu 

ment object from a DocumentBuilder implementation which wraps an underlying DOM implementation. 

In order to obtain a DocumentBuilder instance, an application programmer first obtains an instance of a Docu 

mentBuilderFactory. The DocumentBuilderFactory instance is obtained via the static newInstance 

method of the DocumentBuilderFactory class. 

This method uses the following ordered lookup procedure to determine the DocumentBuilderFactory implementation 

class to load: 

• Use the javax.xml.parsers.DocumentBuilderFactory system property 



10









API will look for the classname in the file META-INF/services/javax.xml.parsers.DocumentBuilderFactory in jars 


• Platform default DocumentBuilderFactory instance. 

If the DocumentBuilderFactory implementation class cannot be loaded or instantiated at runtime, a Factory 

ConfigurationError is thrown. This error message should contain a descriptive explanation of the problem and 

how the user can resolve it. 

The instance of DocumentBuilderFactory can optionally be configured by the application programmer to provide 

parsers that are namespace aware or validating, or both. These settings are made using the setNamespaceAware 

and setValidating methods of the factory. The application programmer can then obtain a DocumentBuilder 

implementation instance from the factory. If the factory cannot provide a parser configured as set by the application 

programmer, then a ParserConfigurationException is thrown. 

Reliance on SAX API 

Examples 

The DocumentBuilder reuses several classes from the SAX API. This does not mean that the implementor of the un 

derlying DOM implementation must use a SAX parser to parse the XML content, only that the implementation com 

municate with the application using these existing and defined APIs. 

The following is a simple example of how to parse XML content from a URL: 

DocumentBuilder builder; 

DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance(); 

String location = "http://myserver/mycontent.xml"; 

try { 

builder = factory.newDocumentBuilder(); 

Document document = builder.parse(location); 







} 

The following is an example of how to configure a factory to produce parsers to be namespace aware and validating: 

DocumentBuilder builder; 

DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance(); 

factory.setNamespaceAware(true); 

factory.setValidating(true); 

11




String location = "http://myserver/mycontent.xml"; 

try { 

builder = factory.newDocumentBuilder(); 

Document document = builder.parse(location); 







} 


java -Djavax.xml.parsers.DocumentBuilderFactory=org.apache.xerces.jaxp.DocumentBuilderFactoryImpl 

user.parserApp 

XSLT Plugability 

Examples 

The XSLT Plugability classes allow an application programmer to obtain a Transformer object that is based on a spe 

cific XSLT stylesheet from a TransformerFactory implementation. In order to obtain a Transformer object, a programmer 

first obtains an instance of the TransformerFactory. The TransformerFactory instance is obtained via the static newIn 

stance method of the TransformerFactory class. 

This method uses the following ordered lookup procedure to determine the TransformerFactory implementation class 

to load: 

• Use the javax.xml.transform.TransformerFactory system property 








API will look for the classname in the file META-INF/services/javax.xml.transform.TransformerFactory in jars 


• Platform default TransformFactory instance. 

If the TransformerFactory implementation class cannot be loaded or instantiated at runtime, a Transformer 

FactoryConfigurationError is thrown. This error message should contain a descriptive explanation of the 

problem and how the user can resolve it. 

The following is a simple example of how to transform XML content: 

Transformer transformer; 

TransformerFactory factory = TransformerFactory.newInstance(); 

12




String stylesheet = "file:///home/user/mystylesheet.xsl"; 

String sourceId = "file:///home/user/sourcefile.xml"; 

try { 

transformer = factory.newTransformer(new StreamSource(stylesheet)); 

transformer.transform(new StreamSource(sourceId), new StreamResult(System.out)); 

} catch (Exception e) { 


} 

The following example illustrates the serialization of a DOM node to an XML stream: 

TransformerFactory tfactory = TransformerFactory.newInstance(); 

Transformer serializer = tfactory.newTransformer(); 

Properties oprops = new Properties(); 

oprops.put("method", "html"); 

oprops.put("indent-amount", "2"); 

serializer.setOutputProperties(oprops); 

serializer.transform(new DOMSource(doc), new StreamResult(System.out)); 

Exceptions and Error Reporting 

The following example illustrates the use of the URIResolver to resolve URIs to DOM nodes, in a transformation 

whose input is totally DOM based: 


if (tfactory.getFeature(DOMSource.FEATURE) && tfactory.getFeature(StreamResult.FEATURE)) 

DocumentBuilderFactory dfactory = DocumentBuilderFactory.newInstance(); 

dfactory.setNamespaceAware(true); // Always, required for XSLT 

DocumentBuilder docBuilder = dfactory.newDocumentBuilder(); 

// Set up to resolve URLs that correspond to our inc1.xsl, 

// to a DOM node. Use an anonymous class for the URI resolver. 

final Node xslInc1 = docBuilder.parse("xsl/inc1/inc1.xsl"); 

final Node xslInc2 = docBuilder.parse("xsl/inc2/inc2.xsl"); 

tfactory.setURIResolver(new URIResolver() { 

public Source resolve(String href, String base) 

throws TransformerException { 

// ignore base. 

return (href.equals("inc1/inc1.xsl")) ? new DOMSource(xslInc1) : (href.equals("inc2/ 

} 

} 

); 

// The TransformerFactory will call the anonymous URI 

// resolver set above when it encounters 

// <xsl:include href="inc1/inc1.xsl"/> 

Templates templates = tfactory.newTemplates(new DOMSource(docBuilder.parse(xslID), xslID 

// Get a transformer from the templates. 

13




Transformer transformer = templates.newTransformer(); 

// Set up to resolve URLs that correspond to our foo2.xml, to 

// a DOM node. Use an anonymous class for the URI resolver. 

// Be sure to return the same DOM tree every time for the given URI. 

final Node xmlSubdir1Foo2Node = docBuilder.parse("xml/subdir1/foo2.xml"); 

transformer.setURIResolver(new URIResolver() { 

public Source resolve(String href, String base) 

throws TransformerException { 

// ignore base because we’re lazy, or we don’t care. 

return (href.equals("subdir1/foo2.xml")) ? new DOMSource(xmlSubdir1Foo2Node) : null; 

} 

} 

); 

// Now the transformer will call our anonymous URI resolver 

// when it encounters the document("subdir1/foo2.xml") invocation. 

transformer.transform(new DOMSource(docBuilder.parse(sourceID), sourceID), new StreamRe 

} 

The following example performs a transformation using DOM nodes as input for the TransformerFactory, as input for 

the Transformer, and as the output of the transformation: 


// Make sure the TransformerFactory supports the DOM feature. 

if (tfactory.getFeature(DOMSource.FEATURE) && tfactory.getFeature(DOMResult.FEATURE)) { 

// Use javax.xml.parsers to create our DOMs. 

DocumentBuilderFactory dfactory = DocumentBuilderFactory.newInstance(); 

dfactory.setNamespaceAware(true); // do this always for XSLT 

DocumentBuilder docBuilder = dfactory.newDocumentBuilder(); 

// Create the Templates from a DOM. 

Node xslDOM = docBuilder.parse(xslID); 

DOMSource dsource = new DOMSource(xslDOM, xslID); 

Templates templates = tfactory.newTemplates(dsource); 

// Create the source tree in the form of a DOM. 

Node sourceNode = docBuilder.parse(sourceID); 

// Create a DOMResult that the transformation will fill in. 

DOMResult dresult = new DOMResult(); 

// And transform from the source DOM tree to a result DOM tree. 


transformer.transform(new DOMSource(sourceNode, sourceID), dresult); 

// The root of the result tree may now be obtained from 

// the DOMResult object. 

Node out = dresult.getNode(); 

// Serialize it to System.out for diagnostics. 

Transformer serializer = tfactory.newTransformer(); 

14




serializer.transform(new DOMSource(out), new StreamResult(System.out)); 

} 

The following code fragment illustrates the use of the SAXSource and SAXResult objects: 


// Does this factory support SAX features? 

if (tfactory.getFeature(SAXSource.FEATURE) && tfactory.getFeature(SAXResult.FEATURE)) { 

// Get a transformer. 

Transformer transformer = tfactory.newTransformer(new StreamSource(xslID)); 

// Create a reader for reading. 

XMLReader reader = XMLReaderFactory.createXMLReader(); 

transformer.transform(new SAXSource(reader, new InputSource(sourceID)), new SAXResult(n 

} 

The following illustrates the feeding of SAX events from an org.xml.sax.XMLReader to a Transformer: 



if (tfactory.getFeature(SAXTransformerFactory.FEATURE)) { 

// If so, we can safely cast. 

SAXTransformerFactory stfactory = ((SAXTransformerFactory) tfactory); 

// A TransformerHandler is a ContentHandler that will listen for 

// SAX events, and transform them to the result. 

TransformerHandler handler = stfactory.newTransformerHandler(new StreamSource(xslID)); 

// Set the result handling to be a serialization to System.out. 

handler.setResult(new StreamResult(System.out)); 

handler.getTransformer().setParameter("a-param", "hello to you!"); 

// Create a reader, and set it’s content handler to be the TransformerHandler. 


reader.setContentHandler(handler); 

// It’s a good idea for the parser to send lexical events. 

// The TransformerHandler is also a LexicalHandler. 

reader.setProperty("http://xml.org/sax/properties/lexical-handler", handler); 

// Parse the source XML, and send the parse events to the TransformerHandler. 

reader.parse(sourceID); 

} 

The following code fragment illustrates the creation of a Templates object from SAX2 events sent from an XMLReader: 




// If so, we can safely cast. 

SAXTransformerFactory stfactory = ((SAXTransformerFactory) tfactory); 

15




// Have the factory create a special ContentHandler that will 

// create a Templates object. 

TemplatesHandler handler = stfactory.newTemplatesHandler(); 

// If you don’t do this, the TemplatesHandler won’t know how to 

// resolve relative URLs. 

handler.setSystemId(xslID); 

// Create a reader, and set it’s content handler to be the TemplatesHandler. 


reader.setContentHandler(handler); 

// Parse the source XML, and send the parse events to the TemplatesHandler. 

reader.parse(xslID); 

// Get the Templates reference from the handler. 

Templates templates = handler.getTemplates(); 

// Ready to transform. 


transformer.transform(new StreamSource(sourceID), new StreamResult(System.out)); 

} 

The following illustrates several transformations chained together. Each filter points to a parent 

org.xml.sax.XMLReader ,and the final transformation is caused by invoking org.xml.sax.XMLRead 

er#parse on the final reader in the chain: 




Templates stylesheet1 = tfactory.newTemplates(new StreamSource(xslID_1)); 

Transformer transformer1 = stylesheet1.newTransformer(); 

SAXTransformerFactory stf = (SAXTransformerFactory)tfactory; 


XMLFilter filter1 = stf.newXMLFilter(new StreamSource(xslID_1)); 



// transformer1 will use a SAX parser as it’s reader. 

filter1.setParent(reader); 

// transformer2 will use transformer1 as it’s reader. 

filter2.setParent(filter1); 

// transform3 will use transform2 as it’s reader. 

filter3.setParent(filter2); 

filter3.setContentHandler(new ExampleContentHandler()); 

// filter3.setContentHandler(new org.xml.sax.helpers.DefaultHandler()); 

// Now, when you call transformer3 to parse, it will set 

// itself as the ContentHandler for transform2, and 

// call transform2.parse, which will set itself as the 

// content handler for transform1, and call transform1.parse, 

16




// which will set itself as the content listener for the 

// SAX parser, and call parser.parse(new InputSource("xml/foo.xml")). 

filter3.parse(new InputSource(sourceID)); 

} 

The following code fragment illustrates the use of the stream Source and Result objects: 

// Create a TransformerFactory instance. 


InputStream xslIS = new BufferedInputStream(new FileInputStream(xslID)); 

StreamSource xslSource = new StreamSource(xslIS); 

// Note that if we don’t do this, relative URLs cannot be resolved correctly! 

xslSource.setSystemId(xslID); 

// Create a transformer for the stylesheet. 

Transformer transformer = tfactory.newTransformer(xslSource); 

InputStream xmlIS = new BufferedInputStream(new FileInputStream(sourceID)); 

StreamSource xmlSource = new StreamSource(xmlIS); 

// Note that if we don’t do this, relative URLs cannot be resolved correctly! 

xmlSource.setSystemId(sourceID); 

// Transform the source XML to System.out. 

transformer.transform( xmlSource, new StreamResult(System.out)); 


java -Djavax.xml.transform.TransformerFactory=org.apache.xalan.processor.TransformerFactoryImpl 

user.parserApp 

Thread Safety 

Implementations of the SAXParser, DocumentBuilder, Transformer and GrammarCache abstract classes 

and implementation instances of GrammarLoader are not expected to be thread safe by this specification. This means 

that application programmers should not expect to be able to use the same instance of a SAXParser, Document 

Builder, Transformer GrammarCache or GrammarLoader in more than one thread at a time without side 

effects. If a programmer is creating a multi-threaded application, they should make sure that only one thread has access 

to any given SAXParser, DocumentBuilder, Transformer, GrammarCache or GrammarLoader instance. 

Configuration of a SAXParserFactory, DocumentBuilderFactory TransformerFactory or Grammar 

LoaderFactory is also not expected to be thread safe. This means that an application programmer should not allow 

a SAXParserFactory, DocumentBuilderFactory, TransformerFactory or GrammarLoaderFactory 

instance to have its setter methods accessed from more than one thread. 

It is expected that the newSAXParser and newGrammarLoader method of a SAXParserFactory implement 

ation, the newDocumentBuilder and newGrammarLoader method of a DocumentBuilderFactory and 

the newTransformer method of a TransformerFactory will be thread safe without side effects. This means 

that an application programmer should expect to be able to create parser instances in multiple threads at once from a 

shared factory without side effects or problems. 

17




Properties For Enabling Schema Validation 

javax.xml.parsers.SAXParserFactory 

The validating property must have the value true for any of the property strings defined below to take effect. Otherwise, 

the values of the properties defined below will be ignored. This value can be set by invoking 

setValidating(true) 

javax.xml.parsers.SAXParser 

The setProperty method in SAXParser must support the property strings defined below to indicate the schema language 

and the source of the schema file(s) to the parser: 

http://java.sun.com/xml/jaxp/properties/schemaLanguage 

This property defines the schema language to be used for validation. The value of this property must be the URI of the 

schema language specification. To be compliant with this version of the specification, the implementation must support 

the W3C XML Schema [http://www.w3.org/2001/XMLSchema] specification. 

When setValidating is set to true and a schema language is set, then the parser must validate against that schema language 

only. For example if an application sets the schemaLanguage property to XML Schemas then the parser must try to 

validate against the XML schema only, even if the document has a DOCTYPE declaration that refers to a DTD. 

http://java.sun.com/xml/jaxp/properties/schemaSource 

The XML Schema Recommendation explicitly states that the inclusion of schemaLocation / noNamespaceSchema 

Location attributes in an instance document is only a hint; it does not mandate that these attributes must be used to 

locate schemas. 

The schemaSource property lets the user set the schema(s) to validate against. If the target namespace of a schema 

specified using this property matches the target namespace of a schema occurring in schemaLocation attribute, the 

schema specified by the user using this property will be used and the instance document’s schemaLocation attribute 

will be effectively ignored. However if the target namespace of any schema specified using this property doesn’t match 

the target namespace of a schema occurring in the instance document, then the hint specified in the instance document 

will be used for validation. The acceptable value for this property must be one of the following: 

• String that points to the URI of the schema 

• InputStream with the contents of the schema 

• SAX InputSource 

• File 

• an array of Objects with the contents being one of the types defined above. An array of Objects can be used only 

when the schema language has the ability to assemble a schema at runtime. When an array of Objects is passed it 

is illegal to have two schemas that share the same namespace. 

If no target namespace is defined, then only one schema can be referenced by the property and it must work exactly 

the way xsi:noNamespaceSchemaLocation does. 

It is illegal to set the schemaSource property if the schemaLanguage property has not been set. In that case, the imple 

mentation must throw a SAXNotSupportedException with a detailed message. 

18




If the schemaSource property is set using a String, the parser must pass the value of the property to the 

org.xml.sax.EntityResolver with the publicId set to null. 

javax.xml.parsers.DocumentBuilderFactory 

The same property strings as described above for the SAXParser must be supported by DocumentBuilderFact 

ory.setAttribute method. 

When setValidating is set to true and a schema language is set then the parser must validate against that schema language 

only. For example if an application sets the schema language property to XML Schemas the parser must try to validate 

against the XML schema only, even if the document has a DOCTYPE declaration that refers to a DTD. 

It is illegal to set the schemaSource property if the schemaLanguage property has not been set. In that case, the imple 

mentation must throw an IllegalArgumentException with a detailed message. 

Note: None of the properties will take effect till the setValidating(true) has been called on the SAXParserFactory or 

the DocumentBuilderFactory that was used to create the SAXParser or the DocumentBuilder. 

The table below shows the results of various configuration scenarios. In all cases, we assume that setValidating(true) 

has been called. 

Document 

DOCTYPE? 

no 

no 

no 

yes / no 

yes / no 

yes / no 

has 

schema language 

property set to 

XML Schemas? 

no 

no 

no 

yes 

yes 

yes 

schema source 

property set? 

no 

no 

yes 

no 

yes 

yes 

schema location 

attribute present 

in document? 

no 

yes 

yes / no 

yes 

no 

yes 

Document Valid 

ated against 

error as per JAXP N/A 

1.1 spec. Must 

have a DOCTYPE 

declaration when 

validation is 

turned on. 

Error. Schema lan 

guage must be set. 

Error schema lan 

guage must be set. 

xml schemas 

xml schemas 

xml schemas 

Schema file used 

N/A 

N/A 

schema files re 

ferred to using the 


attributes present 

in the instance 

document 

schema file re 

ferred to in the 

schemasource 

property 



schema source 

property, if the tar 

get namespace 

matches. The 



19




Document 

DOCTYPE? 

yes 

yes 

has 

schema language 

property set to 

XML Schemas? 

no 

no 

schema source 

property set? 

no 

yes 


attribute present 

in document? 

yes / no 

yes / no 

Document Valid 

ated against 

DTD 

Error. Schema 

source cannot be 

set without setting 

the schema lan 

guage. 


attribute is ignored 

only if the target 

namespace 

matches 

Schema file used 

DTD referred to in 

the DOCTYPE 

N/A 

Samples Using the Properties 

Sax parser sample: 

try { 

SAXParserFactory spf = SAXParserFactory.newInstance(); 

spf.setNamespaceAware(true); 

spf.setValidating(true); 

SAXParser sp = spf.newSAXParser(); 

sp.setProperty("http://java.sun.com/xml/jaxp/properties/schemaLanguage", 

"http://www.w3.org/2001/XMLSchema"); 

sp.setProperty("http://java.sun.com/xml/jaxp/properties/schemaSource", 

"http://www.example.com/Report.xsd"); 

DefaultHandler dh = new DefaultHandler(); 

sp.parse("http://www.wombats.com/foo.xml", dh); 

} catch(SAXException se) { 

se.printStackTrace(); 

} 

DOM parser sample: 

try { 

DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance(); 

dbf.setNamespaceAware(true); 

dbf.setValidating(true); 

dbf.setAttribute("http://java.sun.com/xml/jaxp/properties/schemaLanguage", 

"http://www.w3.org/2001/XMLSchema"); 

dbf.setAttribute("http://java.sun.com/xml/jaxp/properties/schemaSource", 

"http://www.example.com/Report.xsd"); 

DocumentBuilder db = dbf.newDocumentBuilder(); 

Document doc = db.parse("http://www.wombats.com/foo.xml"); 

} catch(DOMException de) { 

20




} 

de.printStackTrace(); 

Recommended Implementation of Properties 

It is recommended that parser implementations recognize properties defined in the form of a URI, as above. Such im 

plementations avoid conflicts in the use of the feature and property strings among parser implementations. That is also 

the way in which SAX 2.0 defines feature and property strings. 

21



Chapter 5. Conformance Requirements 

This section describes the conformance requirements for parser implementations of this specification. Parser imple 

mentations that are accessed via the APIs defined here must implement these constraints, without exception, to provide 

a predictable environment for application development and deployment. 

Note that applications may provide non-conformant implementations that are able to support the plugability mechanism 

defined in the specification, however the system default processor must meet the conformance requirements defined 

below. 

All Implementations of JSR 206 Java API for XML Processing (JAXP) 1.3 Must Support 

the Following Specifications: 

• Extensible Markup Language (XML) 1.1 [http://www.w3.org/TR/xml11], Extensible Markup Language (XML) 

1.0 (Second Edition) [http://www.w3.org/TR/REC-xml], Extensible Markup Language (XML) 1.0 (Second Edition) 

Errata [http://www.w3.org/XML/xml-V10-2e-errata] 

• Namespaces in XML 1.1 [http://www.w3.org/TR/xml-names11/], Namespaces in XML 1.0 

[spec.namespaces-1.0.link;], Namespaces in XML 1.0 Errata [spec.namespaces-1.0-errata.link;] 

• XML Schema Part 1: Structures [http://www.w3.org/TR/xmlschema-1/], XML Schema Part 1: Structures Errata 

[http://www.w3.org/2001/05/xmlschema-errata#Errata1], XML Schema Part 2: Datatypes 

[http://www.w3.org/TR/xmlschema-2/], XML Schema Part 2: Datatypes Errata 

[http://www.w3.org/2001/05/xmlschema-errata#Errata2] 

• XSL Transformations (XSLT) Version 1.0 [http://www.w3.org/TR/xslt], XSL Transformations (XSLT) Version 

1.0 Errata [http://www.w3.org/1999/11/REC-xslt-19991116-errata] 

• XML Path Language (XPath) Version 1.0 [http://www.w3.org/TR/xpath], XML Path Language (XPath) Version 

1.0 Errata [http://www.w3.org/1999/11/REC-xpath-19991116-errata] 

• XML Inclusions (XInclude) Version 1.0 [http://www.w3.org/TR/xinclude/] 

• Document Object Model (DOM) Level 3 Core [http://www.w3.org/TR/DOM-Level-3-Core], Document Object 

Model (DOM) Level 3 Load and Save 

• Simple API for XML (SAX) 2.0.1 (sax2 r2) [http://www.saxproject.org/], http://www.saxproject.org/?selected=ext 

22



Chapter 6. XML Inclusions (XInclude) 

What is XML Inclusions (XInclude) 

JSR 206 Java API for XML Processing (JAXP) 1.3 supports XInclude as defined in XML Inclusions (XInclude) 

Version 1.0 [http://www.w3.org/TR/xinclude/]. 

XInclude specifies a processing model and syntax for general purpose inclusion. Inclusion is accom 

plished by merging a number of XML information sets into a single composite Infoset. Specification 

of the XML documents (infosets) to be merged and control over the merging process is expressed 

in XML-friendly syntax (elements, attributes, URI references). 

— XML Inclusions (XInclude) Version 1.0, Abstract [http://www.w3.org/TR/xinclude/#abstract] 

Implementation Required by JSR 206 Java API for 

XML Processing (JAXP) 1.3 

JSR 206 Java API for XML Processing (JAXP) 1.3 implements XML Inclusions (XInclude) 

Version 1.0 with the following limitations 

• at the time this specification was developed, there was no standard fragment identifier syntax for “application/xml” 

resources 

• supports XPointers using the XPointer Framework and XPointer element() scheme 

• no other XPointer schemes or addressing mechanisms are supported and it is an error to use an other XPointer 

scheme or addressing mechanism, the error is signaled by throwing a java.lang.Exception for DOM processing 

and an org.xml.sax.SAXParseException for SAX processing 

XInclude processing defaults to false. See Javadoc for javax.xml.parsers.DocumentBuilderFactory and 

javax.xml.parsers.SAXParserFactory for methods to enable/disable/query the state of XInclude processing. 

23



Chapter 7. JSR 206 Java API for XML 

Processing (JAXP) 1.3 Specification and 

Implementation Version Information 


Specification Version Information 

JSR 206 Java API for XML Processing (JAXP) 1.3 specification version information is 

made available via javax.xml.Version public static final methods 

• public static final String javax.xml.Version.getSpecificationTitle() 

• public static final String javax.xml.Version.getSpecificationVersion() 

• public static final String javax.xml.Version.getSpecificationVendor() 

• public static final String javax.xml.Version.getExtensionName() 


Implementation Version Information 

JSR 206 Java API for XML Processing (JAXP) 1.3 implementation version information is 

made available via javax.xml.Version public final methods 

• public final String javax.xml.Version.getImplementationTitle() 

• public final String javax.xml.Version.getImplementationVersion() 

• public final String javax.xml.Version.getImplementationVendor() 

• public final String javax.xml.Version.getImplementationVendorID() 

• public final String javax.xml.Version.getImplementationURL() 

Implementations must specify a version service provider class in META-INF/services/javax.xml.Ab 

stractVersion. The service provider must extend javax.xml.AbstractVersion. 


Full Specification and Implementation Version Inform 

ation 

A toString() method is available in javax.xml.Version that returns the complete JSR 206 Java API for XML 

Processing (JAXP) 1.3 specification and implementation version information as a String. 

24



(JAXP) 1.3 Specification and Implementa 


Implementors must provide a mechanism to easily expose the complete JSR 206 Java API for XML Processing 

(JAXP) 1.3 specification and implementation version information to the developer and user. The developer and user 

should not have to write any programs or applications to access such information. An example would be a command 

that would print the information to System.out for implementations that have a command line interface. 

25



Chapter 8. Package javax.xml.parsers 

Provides classes allowing the processing of XML documents. Two types of plugable parsers are supported: 

• SAX (Simple API for XML) 

• DOM (Document Object Model) 

Class DocumentBuilder 

Synopsis 

Defines the API to obtain DOM Document instances from an XML document. Using this class, an application program 

mer can obtain a org.w3c.dom.Document from XML. 

An instance of this class can be obtained from the DocumentBuilderFactory.newDocumentBuilder [ Method newDoc 

umentBuilder()] method. Once an instance of this class is obtained, XML can be parsed from a variety of input sources. 

These input sources are InputStreams, Files, URLs, and SAX InputSources. 

Note that this class reuses several classes from the SAX API. This does not require that the implementor of the under 

lying DOM implementation use a SAX parser to parse XML document into a Document. It merely requires that the 

implementation communicate with the application using these existing APIs. 

public DocumentBuilder { 

protected DocumentBuilder(); 

public Document parse(java.io.InputStream is) 

throws org.xml.sax.SAXException, java.io.IOException; 

public Document parse(java.io.InputStream is, 

java.lang.String systemId) 


public Document parse(java.lang.String uri) 


public Document parse(java.io.File f) 


public Document abstract parse(org.xml.sax.InputSource is) 


public boolean abstract isNamespaceAware(); 

public boolean abstract isValidating(); 

public void abstract setEntityResolver(org.xml.sax.EntityResolver er); 

public void abstract setErrorHandler(org.xml.sax.ErrorHandler eh); 

public Document abstract newDocument(); 

public DOMImplementation abstract getDOMImplementation(); 

26


Package javax.xml.parsers 


public Schema getSchema(); 

public SecureProcessing getSecureProcessing(); 

public boolean isXIncludeAware(); 

} 

Author 

Jeff Suttor [mailto:Jeff.Suttor@Sun.com] 

Version $Revision: 1.23 $, $Date: 2003/12/06 00:21:42 $ 

Inheritance Path 

java.lang.Object 

| 

javax.xml.parsers.DocumentBuilder 

Members 

Constructor DocumentBuilder() 

protected DocumentBuilder(); 

Protected constructor 

Method getDOMImplementation() 

public DOMImplementation abstract getDOMImplementation(); 

Obtain an instance of a org.w3c.dom.DOMImplementation object. 

Method getSchema() 


Exceptions 

UnsupportedOperationEx 

ception 

For backward compatibility, when implementations for earlier versions of JAXP is used, 

this exception will be thrown. 

Since 1.5 

Get a reference to the the javax.xml.validation.Schema being used by the XML processor. 

If no schema is being used, null is returned. 

Method getSecureProcessing() 


27




Exceptions 


ception 



Since 1.5 

See Also javax.xml.parsers.DocumentBuilderFactory.setSecureProcessing [Method setSecurePro 

cessing(javax.xml.SecureProcessing)] 

Get the javax.xml.SecureProcessing configuration associated with this parser 

. 

Method isNamespaceAware() 


Indicates whether or not this parser is configured to understand namespaces. 

Method isValidating() 


Indicates whether or not this parser is configured to validate XML documents. 

Method isXIncludeAware() 


Exceptions 


ception 



Since 1.5 

See Also javax.xml.parsers.DocumentBuilderFactory.setXIncludeAware [Method setXInclude 

Aware(boolean)] 

Get the XInclude processing mode for this parser. 

Method newDocument() 

public Document abstract newDocument(); 

Obtain a new instance of a DOM org.w3c.dom.Document object to build a DOM tree with. 

Method parse(File) 

public Document parse(java.io.File f) 


28




Parameters 

f 

returns 

Exceptions 

IOException 

SAXException 

See Also 

The file containing the XML to parse. 

A new DOM Document object. 

If any IO errors occur. 

If any parse errors occur. 

org.xml.sax.DocumentHandler 

Parse the content of the given file as an XML document and return a new DOM org.w3c.dom.Document object. An 

IllegalArgumentException is thrown if the File is null null. 

Method parse(InputSource) 

public Document abstract parse(org.xml.sax.InputSource is) 


Parameters 

is 

returns 

InputSource containing the content to be parsed. 


Exceptions 

IOException 

SAXException 

See Also 




Parse the content of the given input source as an XML document and return a new DOM org.w3c.dom.Document object. 

An IllegalArgumentException is thrown if the InputSource is null null. 

Method parse(InputStream) 

public Document parse(java.io.InputStream is) 


Parameters 

is 

returns 

InputStream containing the content to be parsed. 

Document result of parsing the InputStream 

Exceptions 

IOException 

SAXException 



29




See Also 


Parse the content of the given InputStream as an XML document and return a new DOM org.w3c.dom.Document 

object. An IllegalArgumentException is thrown if the InputStream is null. 

Method parse(InputStream, String) 

public Document parse(java.io.InputStream is, 



Parameters 

is 

systemId 

returns 


Provide a base for resolving relative URIs. 


Exceptions 

IOException 

SAXException 

See Also 




Parse the content of the given InputStream as an XML document and return a new DOM org.w3c.dom.Document 

object. An IllegalArgumentException is thrown if the InputStream is null. 

Method parse(String) 

public Document parse(java.lang.String uri) 


Parameters 

uri 

returns 

The location of the content to be parsed. 


Exceptions 

IOException 

SAXException 

See Also 




Parse the content of the given URI as an XML document and return a new DOM org.w3c.dom.Document object. An 

IllegalArgumentException is thrown if the URI is null null. 

Method setEntityResolver(EntityResolver) 

public void abstract setEntityResolver(org.xml.sax.EntityResolver er); 

30




Parameters 

er 

The EntityResolver to be used to resolve entities present in the XML document to be parsed. 

Specify the org.xml.sax.EntityResolver to be used to resolve entities present in the XML document to be parsed. Setting 

this to null will result in the underlying implementation using it's own default implementation and behavior. 

Method setErrorHandler(ErrorHandler) 

public void abstract setErrorHandler(org.xml.sax.ErrorHandler eh); 

Parameters 

eh 

The ErrorHandler to be used to resolve entities present in the XML document to be parsed. 

Specify the org.xml.sax.ErrorHandler to be used to resolve entities present in the XML document to be parsed. Setting 

this to null will result in the underlying implementation using it's own default implementation and behavior. 

Class DocumentBuilderFactory 

Synopsis 

Defines a factory API that enables applications to obtain a parser that produces DOM object trees from XML documents. 

public DocumentBuilderFactory { 

protected DocumentBuilderFactory(); 

static DocumentBuilderFactory newInstance(); 

public DocumentBuilder abstract newDocumentBuilder() 

throws ParserConfigurationException; 

public void setNamespaceAware(boolean awareness); 

public void setValidating(boolean validating); 

public void setIgnoringElementContentWhitespace(boolean whitespace); 

public void setExpandEntityReferences(boolean expandEntityRef); 

public void setIgnoringComments(boolean ignoreComments); 

public void setCoalescing(boolean coalescing); 

public boolean isNamespaceAware(); 

public boolean isValidating(); 

public boolean isIgnoringElementContentWhitespace(); 

public boolean isExpandEntityReferences(); 

public boolean isIgnoringComments(); 

31




public boolean isCoalescing(); 

public void abstract setAttribute(java.lang.String name, 

java.lang.Object value) 

throws java.lang.IllegalArgumentException; 

public Object abstract getAttribute(java.lang.String name) 



public void setSchema(javax.xml.validation.Schema schema); 

public void setSecureProcessing(javax.xml.SecureProcessing secureProcessing); 


public void setXIncludeAware(boolean state); 


} 

Author 

Jeff Suttor [Jeff.Suttor@Sun.com] 

Version $Revision: 1.34 $, $Date: 2003/12/11 18:40:25 $ 



| 

javax.xml.parsers.DocumentBuilderFactory 

Members 

Method getAttribute(String) 

public Object abstract getAttribute(java.lang.String name) 


Parameters 

name 

returns 

The name of the attribute. 

value The value of the attribute. 

Exceptions 

IllegalArgumentException 

thrown if the underlying implementation doesn't recognize the attribute. 

Allows the user to retrieve specific attributes on the underlying implementation. 



32




Exceptions 


ception 



Since 1.5 

Gets the javax.xml.validation.Schema object specified through the javax.xml.parsers.DocumentBuilderFactory.setSchema 

[ Method setSchema(javax.xml.validation.Schema)] method. 



Exceptions 


ception 



Since 1.5 

Get the javax.xml.SecureProcessing object specified through the javax.xml.parsers.DocumentBuilderFactory.setSe 

cureProcessing [ Method setSecureProcessing(javax.xml.SecureProcessing)] method. 

Method isCoalescing() 

public boolean isCoalescing(); 

Indicates whether or not the factory is configured to produce parsers which converts CDATA nodes to Text nodes and 

appends it to the adjacent (if any) Text node. 

Method isExpandEntityReferences() 

public boolean isExpandEntityReferences(); 

Indicates whether or not the factory is configured to produce parsers which expand entity reference nodes. 

Method isIgnoringComments() 

public boolean isIgnoringComments(); 

Indicates whether or not the factory is configured to produce parsers which ignores comments. 

Method isIgnoringElementContentWhitespace() 

public boolean isIgnoringElementContentWhitespace(); 

Indicates whether or not the factory is configured to produce parsers which ignore ignorable whitespace in element 

content. 



33




Indicates whether or not the factory is configured to produce parsers which are namespace aware. 



Indicates whether or not the factory is configured to produce parsers which validate the XML content during parse. 



Exceptions 


ception 



Since 1.5 

Get state of XInclude processing. 

Method newDocumentBuilder() 

public DocumentBuilder abstract newDocumentBuilder() 

throws ParserConfigurationException; 

Exceptions 

ParserConfigurationExcep 

tion 

if a DocumentBuilder cannot be created which satisfies the configuration requested. 

Creates a new instance of a javax.xml.parsers.DocumentBuilder [ Class DocumentBuilder] using the currently configured 

parameters. 

Method newInstance() 

static DocumentBuilderFactory newInstance(); 

Exceptions 

FactoryConfigurationErr 

or 

if the implementation is not available or cannot be instantiated. 

Obtain a new instance of a DocumentBuilderFactory. This static method creates a new factory instance. This 

method uses the following ordered lookup procedure to determine the DocumentBuilderFactory implementation 

class to load: 

• Use the javax.xml.parsers.DocumentBuilderFactory system property. 


java.util.Properties format and contains the fully qualified name of the implementation class with the 

key being the system property defined above. The jaxp.properties file is read only once by the JAXP implementation 

and it's values are then cached for future use. If the file does not exist when the first attempt is made to read from 

34




it, no further attempts are made to check for its existence. It is not possible to change the value of any property in 

jaxp.properties after it has been read for the first time. 


API will look for a classname in the file META-INF/services/javax.xml.parsers.DocumentBuild 

erFactory in jars available to the runtime. 

• Platform default DocumentBuilderFactory instance. 

Once an application has obtained a reference to a DocumentBuilderFactory it can use the factory to configure 

and obtain parser instances. 

Method setAttribute(String, Object) 




Parameters 

name 

value 


The value of the attribute. 

Exceptions 


thrown if the underlying implementation doesn't recognize the attribute. 

Allows the user to set specific attributes on the underlying implementation. 

Method setCoalescing(boolean) 

public void setCoalescing(boolean coalescing); 

Parameters 

coalescing 

true if the parser produced will convert CDATA nodes to Text nodes and append it to the 

adjacent (if any) text node; false otherwise. 

Specifies that the parser produced by this code will convert CDATA nodes to Text nodes and append it to the adjacent 

(if any) text node. By default the value of this is set to false 

Method setExpandEntityReferences(boolean) 

public void setExpandEntityReferences(boolean expandEntityRef); 

Parameters 

expandEntityRef 

true if the parser produced will expand entity reference nodes; false otherwise. 

Specifies that the parser produced by this code will expand entity reference nodes. By default the value of this is set 

to true 

35




Method setIgnoringComments(boolean) 

public void setIgnoringComments(boolean ignoreComments); 

Parameters 

ignoreComments 

boolean value to ignore comments during processing 

Specifies that the parser produced by this code will ignore comments. By default the value of this is set to false . 

Method setIgnoringElementContentWhitespace(boolean) 

public void setIgnoringElementContentWhitespace(boolean whitespace); 

Parameters 

whitespace 

true if the parser created must eliminate whitespace in the element content when parsing XML 

documents; false otherwise. 

Specifies that the parsers created by this factory must eliminate whitespace in element content (sometimes known 

loosely as 'ignorable whitespace') when parsing XML documents (see XML Rec 2.10). Note that only whitespace 

which is directly contained within element content that has an element only content model (see XML Rec 3.2.1) will 

be eliminated. Due to reliance on the content model this setting requires the parser to be in validating mode. By default 

the value of this is set to false. 

Method setNamespaceAware(boolean) 


Parameters 

awareness 

true if the parser produced will provide support for XML namespaces; false otherwise. 

Specifies that the parser produced by this code will provide support for XML namespaces. By default the value of this 

is set to false 

Method setSchema(Schema) 


Parameters 

schema 

Schema to use or null to remove a schema. 

Exceptions 


ception 



Since 1.5 

Set the javax.xml.validation.Schema to be used by parsers created from this factory. 

36




When a javax.xml.validation.Schema is non-null, a parser will use a validator created from it to validate documents 

before it passes information down to the application. 

When errors are found by the validator, the parser is responsible to report them to the user-specified 

org.w3c.dom.DOMErrorHandler, just like any other errors found by the parser itself. 

A validator may modify the outcome of a parse (for example by adding default values that were missing in documents), 

and a parser is responsible to make sure that the application will receive modified DOM trees. 

Initialy, null is set as the javax.xml.validation.Schema. 

This processing will take effect even if the javax.xml.parsers.DocumentBuilderFactory.isValidating [ Method isValid 

ating()] method returns 

false 

. 

It is an error to use the http://java.sun.com/xml/jaxp/properties/schemaSource property and/or 

the http://java.sun.com/xml/jaxp/properties/schemaLanguage property in conjunction with a 

javax.xml.validation.Schema object. Such configuration will cause a javax.xml.parsers.ParserConfigurationException 

[ Exception ParserConfigurationException] exception when the javax.xml.parsers.DocumentBuilderFactory.newDoc 

umentBuilder [ Method newDocumentBuilder()] is invoked. 

Note for implmentors 

A parser must be able to work with any javax.xml.validation.Schema implementation. 

Method setSecureProcessing(SecureProcessing) 


Parameters 

secureProcessing 

If a non-null object is specified, the parser will observe the settings of the specified 

javax.xml.SecureProcessing. Set null to remove the previously set javax.xml.SecurePro 

cessing object from this javax.xml.parsers.DocumentBuilderFactory [ Class Document 

BuilderFactory]. 

Exceptions 


ception 



Since 1.5 

Associate the javax.xml.SecureProcessing configuration for this javax.xml.parsers.DocumentBuilderFactory [ Class 

DocumentBuilderFactory]. 

The field is initially set to 

37




null 

, meaning the parsers created by this factory will work in a way specified by the relevant specs. 

Method setValidating(boolean) 


Parameters 

validating 

true if the parser produced will validate documents as they are parsed; false otherwise. 

Specifies that the parser produced by this code will validate documents as they are parsed. By default the value of this 

is set to false. 

Method setXIncludeAware(boolean) 


Parameters 

state 

Set XInclude processing to true or false 

Exceptions 


ception 



Since 1.5 

Set state of XInclude processing. 

If XInclude markup is found in the document instance, should it be processed as specified in XML Inclusions (XInclude) 


XInclude processing defaults to false. 

Class SAXParser 

Defines the API that wraps an org.xml.sax.XMLReader implementation class. In JAXP 1.0, this class wrapped the 

org.xml.sax.Parser interface, however this interface was replaced by the org.xml.sax.XMLReader. For ease of transition, 

this class continues to support the same name and interface as well as supporting new methods. An instance of this 

class can be obtained from the javax.xml.parsers.SAXParserFactory.newSAXParser [ Method newSAXParser()] 

method. Once an instance of this class is obtained, XML can be parsed from a variety of input sources. These input 

sources are InputStreams, Files, URLs, and SAX InputSources. 

This static method creates a new factory instance based on a system property setting or uses the platform default if no 

property has been defined. 

The system property that controls which Factory implementation to create is named "javax.xml.parsers.SAX 

ParserFactory". This property names a class that is a concrete subclass of this abstract class. If no property is 

defined, a platform default will be used. 

38




Synopsis 

As the content is parsed by the underlying parser, methods of the given org.xml.sax.HandlerBase or the 

org.xml.sax.helpers.DefaultHandler are called. 

Implementors of this class which wrap an underlaying implementation can consider using the org.xml.sax.help 

ers.ParserAdapter class to initially adapt their SAX1 impelemntation to work under this revised class. 

public SAXParser { 

protected SAXParser(); 

public void parse(java.io.InputStream is, 

org.xml.sax.HandlerBase hb) 



org.xml.sax.HandlerBase hb, 




org.xml.sax.helpers.DefaultHandler dh) 



org.xml.sax.helpers.DefaultHandler dh, 



public void parse(java.lang.String uri, 






public void parse(java.io.File f, 






public void parse(org.xml.sax.InputSource is, 






39




public Parser abstract getParser() 

throws org.xml.sax.SAXException; 

public XMLReader abstract getXMLReader() 




public void abstract setProperty(java.lang.String name, 


throws org.xml.sax.SAXNotRecognizedException, org.xml.sax.SAXNotSupportedException; 

public Object abstract getProperty(java.lang.String name) 





} 

Author 





| 

javax.xml.parsers.SAXParser 

Members 

Constructor SAXParser() 

protected SAXParser(); 

Protected constructor to prevent instaniation. Use javax.xml.parsers.SAXParserFactory.newSAXParser [ Method 

newSAXParser()]. 

Method getParser() 

public Parser abstract getParser() 


Exceptions 

SAXException 

If any SAX errors occur during processing. 

Returns the SAX parser that is encapsultated by the implementation of this class. 

40




Method getProperty(String) 

public Object abstract getProperty(java.lang.String name) 


Parameters 

name 

returns 

The name of the property to be retrieved. 

Value of the requested property. 

Exceptions 

SAXNotRecognizedEx 

ception 

SAXNotSupportedExcep 

tion 

When the underlying XMLReader does not recognize the property name. 

When the underlying XMLReader recognizes the property name but doesn't support the 

property. 

See Also 

org.xml.sax.XMLReader.getProperty 

Returns the particular property requested for in the underlying implementation of org.xml.sax.XMLReader. 



Exceptions 


ception 



Since 1.5 

Get a reference to the the javax.xml.validation.Schema being used by the XML processor. 

If no schema is being used, null is returned. 



Exceptions 


ception 



Since 1.5 

See Also javax.xml.parsers.SAXParserFactory.setSecureProcessing [Method setSecurePro 

cessing(javax.xml.SecureProcessing)] 

Get the javax.xml.SecureProcessing configuration associated with this parser 

. 

41




Method getXMLReader() 

public XMLReader abstract getXMLReader() 


Exceptions 

SAXException 


Returns the org.xml.sax.XMLReader that is encapsulated by the implementation of this class. 



Indicates whether or not this parser is configured to understand namespaces. 



Indicates whether or not this parser is configured to validate XML documents. 



Exceptions 


ception 



Since 1.5 

See Also 

javax.xml.parsers.SAXParserFactory.setXIncludeAware [Method setXIncludeAware(boolean)] 

Get the XInclude processing mode for this parser. 

Method parse(File, DefaultHandler) 




Parameters 

f 

dh 

The file containing the XML to parse 

The SAX DefaultHandler to use. 

Exceptions 


If the File object is null. 

42




IOException 

SAXException 

See Also 




Parse the content of the file specified as XML using the specified org.xml.sax.helpers.DefaultHandler. 

Method parse(File, HandlerBase) 




Parameters 

f 

hb 

The file containing the XML to parse 

The SAX HandlerBase to use. 

Exceptions 


IOException 

SAXException 

If the File object is null. 



See Also 


Parse the content of the file specified as XML using the specified org.xml.sax.HandlerBase. Use of the DefaultHandler 

version of this method is recommended as the HandlerBase class has been deprecated in SAX 2.0 

Method parse(InputSource, DefaultHandler) 




Parameters 

is 

dh 

The InputSource containing the content to be parsed. 


Exceptions 


IOException 

SAXException 

If the InputSource object is null. 



See Also 


43




Parse the content given org.xml.sax.InputSource as XML using the specified org.xml.sax.helpers.DefaultHandler. 

Method parse(InputSource, HandlerBase) 




Parameters 

is 

hb 

The InputSource containing the content to be parsed. 


Exceptions 


IOException 

SAXException 

If the InputSource object is null. 



See Also 


Parse the content given org.xml.sax.InputSource as XML using the specified org.xml.sax.HandlerBase. Use of the 

DefaultHandler version of this method is recommended as the HandlerBase class has been deprecated in SAX 2.0 

Method parse(InputStream, DefaultHandler) 




Parameters 

is 

dh 



Exceptions 


IOException 

SAXException 

If the given InputStream is null. 



See Also 


Parse the content of the given java.io.InputStream instance as XML using the specified org.xml.sax.helpers.DefaultHand 

ler. 

44




Method parse(InputStream, DefaultHandler, String) 


org.xml.sax.helpers.DefaultHandler dh, 



Parameters 

is 

dh 

systemId 



The systemId which is needed for resolving relative URIs. 

Exceptions 


IOException 

SAXException 




See Also 

version of this method instead. 

Parse the content of the given java.io.InputStream instance as XML using the specified org.xml.sax.helpers.DefaultHand 

ler. 

Method parse(InputStream, HandlerBase) 




Parameters 

is 

hb 



Exceptions 


SAXException 

IOException 


If parse produces a SAX error. 

If an IO error occurs interacting with the InputStream. 

See Also 


Parse the content of the given java.io.InputStream instance as XML using the specified org.xml.sax.HandlerBase. 

Use of the DefaultHandler version of this method is recommended as the HandlerBase class has been deprecated in 

SAX 2.0. 

45




Method parse(InputStream, HandlerBase, String) 


org.xml.sax.HandlerBase hb, 



Parameters 

is 

hb 

systemId 



The systemId which is needed for resolving relative URIs. 

Exceptions 


IOException 

SAXException 


If any IO error occurs interacting with the InputStream. 


See Also 

version of this method instead. 

Parse the content of the given java.io.InputStream instance as XML using the specified org.xml.sax.HandlerBase. 

Use of the DefaultHandler version of this method is recommended as the HandlerBase class has been deprecated in 

SAX 2.0. 

Method parse(String, DefaultHandler) 




Parameters 

uri 

dh 



Exceptions 


IOException 

SAXException 

If the uri is null. 



See Also 


Parse the content described by the giving Uniform Resource Identifier (URI) as XML using the specified 

org.xml.sax.helpers.DefaultHandler. 

46




Method parse(String, HandlerBase) 




Parameters 

uri 

hb 



Exceptions 


IOException 

SAXException 

If the uri is null. 



See Also 


Parse the content described by the giving Uniform Resource Identifier (URI) as XML using the specified 

org.xml.sax.HandlerBase. Use of the DefaultHandler version of this method is recommended as the HandlerBase 

class has been deprecated in SAX 2.0 

Method setProperty(String, Object) 

public void abstract setProperty(java.lang.String name, 



Parameters 

name 

value 

The name of the property to be set. 

The value of the property to be set. 

Exceptions 


ception 


tion 



property. 

See Also 

org.xml.sax.XMLReader.setProperty 

Sets the particular property in the underlying implementation of org.xml.sax.XMLReader. A list of the core features 

and properties can be found at http://www.megginson.com/SAX/Java/features.html 

[http://www.megginson.com/SAX/Java/features.html]. 

47




Class SAXParserFactory 

Synopsis 

Defines a factory API that enables applications to configure and obtain a SAX based parser to parse XML documents. 

} 

public SAXParserFactory { 

protected SAXParserFactory(); 

static SAXParserFactory newInstance(); 

public SAXParser abstract newSAXParser() 

throws ParserConfigurationException, org.xml.sax.SAXException; 





public void abstract setFeature(java.lang.String name, 

boolean value) 

throws ParserConfigurationException, org.xml.sax.SAXNotRecognizedException, org.xml.sax 

public boolean abstract getFeature(java.lang.String name) 








Author 





| 

javax.xml.parsers.SAXParserFactory 

48




Members 

Constructor SAXParserFactory() 

protected SAXParserFactory(); 

Protected constructor to force use of javax.xml.parsers.SAXParserFactory.newInstance [ Method newInstance()]. 

Method getFeature(String) 

public boolean abstract getFeature(java.lang.String name) 


Parameters 

name 

returns 

The name of the property to be retrieved. 

Value of the requested property. 

Exceptions 


tion 


ception 


tion 

if a parser cannot be created which satisfies the requested configuration. 



property. 

See Also 

org.xml.sax.XMLReader.getProperty 

Returns the particular property requested for in the underlying implementation of org.xml.sax.XMLReader. 



Exceptions 


ception 



Since 1.5 

Gets the javax.xml.validation.Schema object specified through the javax.xml.parsers.SAXParserFactory.setSchema [ 

Method setSchema(javax.xml.validation.Schema)] method. 



49




Exceptions 


ception 



Since 1.5 

Get the javax.xml.SecureProcessing object specified through the javax.xml.parsers.SAXParserFactory.setSecurePro 

cessing [ Method setSecureProcessing(javax.xml.SecureProcessing)] method. 



Indicates whether or not the factory is configured to produce parsers which are namespace aware. 



Indicates whether or not the factory is configured to produce parsers which validate the XML content during parse. 



Exceptions 


ception 



Since 1.5 

Get state of XInclude processing. 


static SAXParserFactory newInstance(); 

Exceptions 

FactoryConfigurationErr 

or 

if the implementation is not available or cannot be instantiated. 

Obtain a new instance of a SAXParserFactory. This static method creates a new factory instance This method 

uses the following ordered lookup procedure to determine the SAXParserFactory implementation class to load: 

• Use the javax.xml.parsers.SAXParserFactory system property. 





50







API will look for a classname in the file META-INF/services/javax.xml.parsers.SAXParserFactory 

in jars available to the runtime. 

• Platform default SAXParserFactory instance. 

Once an application has obtained a reference to a SAXParserFactory it can use the factory to configure and obtain 

parser instances. 

Method newSAXParser() 

public SAXParser abstract newSAXParser() 

throws ParserConfigurationException, org.xml.sax.SAXException; 

Exceptions 


tion 

SAXException 


for SAX errors. 

Creates a new instance of a SAXParser using the currently configured factory parameters. 

Method setFeature(String, boolean) 

public void abstract setFeature(java.lang.String name, 



Parameters 

name 

value 

The name of the feature to be set. 

The value of the feature to be set. 

Exceptions 


tion 


ception 


tion 




property. 

See Also 

org.xml.sax.XMLReader.setFeature 

Sets the particular feature in the underlying implementation of org.xml.sax.XMLReader. A list of the core features 

and properties can be found at http://www.saxproject.org/ 

51




Method setNamespaceAware(boolean) 


Parameters 

awareness 

true if the parser produced by this code will provide support for XML namespaces; false other 

wise. 

Specifies that the parser produced by this code will provide support for XML namespaces. By default the value of this 


Method setSchema(Schema) 


Parameters 

schema 

Schema to use, null to remove a schema. 

Exceptions 


ception 



Since 1.5 

Set the javax.xml.validation.Schema to be used by parsers created from this factory. 

When a javax.xml.validation.Schema is non-null, a parser will use a validator created from it to validate documents 

before it passes information down to the application. 

When errors are found by the validator, the parser is responsible to report them to the user-specified org.xml.sax.Er 

rorHandler, just like any other errors found by the parser itself. 

A validator may modify the SAX event stream (for example by adding default values that were missing in documents), 

and a parser is responsible to make sure that the application will receive those modified event stream. 

Initialy, null is set as the javax.xml.validation.Schema. 

This processing will take effect even if the javax.xml.parsers.SAXParserFactory.isValidating [ Method isValidating()] 

method returns false. 

It is an error to use the http://java.sun.com/xml/jaxp/properties/schemaSource property and/or 

the http://java.sun.com/xml/jaxp/properties/schemaLanguage property in conjunction with a 

non-null javax.xml.validation.Schema object. Such configuration will cause a javax.xml.parsers.ParserConfigurationEx 

ception [ Exception ParserConfigurationException] exception when the javax.xml.parsers.SAXParserFactory.newS 

AXParser [ Method newSAXParser()] is invoked. 

Note for implmentors 

A parser must be able to work with any javax.xml.validation.Schema implementation. 

52




Method setSecureProcessing(SecureProcessing) 


Parameters 

secureProcessing 

If a non-null object is specified, the parser will observe the settings of the specified 

javax.xml.SecureProcessing. Set null to remove the previously set javax.xml.SecurePro 

cessing object from this javax.xml.parsers.SAXParserFactory [ Class SAXParserFactory]. 

Exceptions 


ception 



Since 1.5 

Associate the javax.xml.SecureProcessing configuration for this SAXParserFactory. 

The field is initially set to 

null 

, meaning the parsers created by this factory will work in a way specified by the relevant specs. 

Method setValidating(boolean) 


Parameters 

validating 

true if the parser produced by this code will validate documents as they are parsed; false oth 

erwise. 

Specifies that the parser produced by this code will validate documents as they are parsed. By default the value of this 


Method setXIncludeAware(boolean) 


Parameters 

state 

Set XInclude processing to true or false 

Exceptions 


ception 



Since 1.5 

53




Set state of XInclude processing. 

If XInclude markup is found in the document instance, should it be processed as specified in XML Inclusions (XInclude) 


XInclude processing defaults to false. 

Exception ParserConfigurationException 

Synopsis 

Indicates a serious configuration error. 

} 

public ParserConfigurationException extends Exception { 

public ParserConfigurationException(); 

public ParserConfigurationException(java.lang.String msg); 

Author 





| 

java.lang.Throwable 

| 

java.lang.Exception 

| 

javax.xml.parsers.ParserConfigurationException 

Members 

Constructor ParserConfigurationException() 

public ParserConfigurationException(); 

Create a new ParserConfigurationException with no detail mesage. 

Constructor ParserConfigurationException(String) 

public ParserConfigurationException(java.lang.String msg); 

Parameters 

msg 

The error message for the exception. 

54




Create a new ParserConfigurationException with the String specified as an error message. 

Error FactoryConfigurationError 

Synopsis 

Thrown when a problem with configuration with the Parser Factories exists. This error will typically be thrown when 

the class of a parser factory specified in the system properties cannot be found or instantiated. 

} 

public FactoryConfigurationError extends Error { 

public FactoryConfigurationError(); 

public FactoryConfigurationError(java.lang.String msg); 

public FactoryConfigurationError(java.lang.Exception e); 

public FactoryConfigurationError(java.lang.Exception e, 

java.lang.String msg); 

public String getMessage(); 

public Exception getException(); 

Author 





| 


| 

java.lang.Error 

| 

javax.xml.parsers.FactoryConfigurationError 

Members 

Constructor FactoryConfigurationError() 

public FactoryConfigurationError(); 

Create a new FactoryConfigurationError with no detail mesage. 

Constructor FactoryConfigurationError(Exception) 

public FactoryConfigurationError(java.lang.Exception e); 

55




Parameters 

eThe exception to be encapsulated in a FactoryConfigurationError. 

Create a new FactoryConfigurationError with a given Exception base cause of the error. 

Constructor FactoryConfigurationError(Exception, String) 

public FactoryConfigurationError(java.lang.Exception e, 


Parameters 

e 

msg 

The exception to be encapsulated in a FactoryConfigurationError 

The detail message. 

Create a new FactoryConfigurationError with the given Exception base cause and detail message. 

Constructor FactoryConfigurationError(String) 

public FactoryConfigurationError(java.lang.String msg); 

Parameters 

msg 


Create a new FactoryConfigurationError with the String specified as an error message. 

Method getException() 


Return the actual exception (if any) that caused this exception to be raised. 

Method getMessage() 


Return the message (if any) for this error . If there is no message for the exception and there is an encapsulated exception 

then the message of that exception, if it exists will be returned. Else the name of the encapsulated exception will be 

returned. 

56



Chapter 9. Package javax.xml.transform 

This package defines the generic APIs for processing transformation instructions, and performing a transformation 

from source to result. These interfaces have no dependencies on SAX or the DOM standard, and try to make as few 

assumptions as possible about the details of the source and result of a transformation. It achieves this by defining 

javax.xml.transform.Source [ Interface Source] and javax.xml.transform.Result [ Interface Result] interfaces. 

To define concrete classes for the user, the API defines specializations of the interfaces found at the root level. These 

interfaces are found in javax.xml.transform.sax [ Chapter 11, Package javax.xml.transform.sax], javax.xml.transform.dom 

[ Chapter 10, Package javax.xml.transform.dom], and javax.xml.transform.stream [ Chapter 12, Package 

javax.xml.transform.stream]. 

Creating Objects 

The API allows a concrete javax.xml.transform.TransformerFactory [ Class TransformerFactory] object to be created 

from the static function javax.xml.transform.TransformerFactory.newInstance [ Method newInstance()]. 

Specification of Inputs and Outputs 

This API defines two interface objects called javax.xml.transform.Source [ Interface Source] and javax.xml.trans 

form.Result [ Interface Result]. In order to pass Source and Result objects to the interfaces, concrete classes must be 

used. Three concrete representations are defined for each of these objects: javax.xml.transform.stream.StreamSource 

[ Class StreamSource] and javax.xml.transform.stream.StreamResult [ Class StreamResult], javax.xml.transform.sax.SAX 

Source [ Class SAXSource] and javax.xml.transform.sax.SAXResult [ Class SAXResult], and javax.xml.trans 

form.dom.DOMSource [ Class DOMSource] and javax.xml.transform.dom.DOMResult [ Class DOMResult]. Each 

of these objects defines a FEATURE string (which is i the form of a URL), which can be passed into javax.xml.trans 

form.TransformerFactory.getFeature [ Method getFeature(java.lang.String)] to see if the given type of Source or Result 

object is supported. For instance, to test if a DOMSource and a StreamResult is supported, you can apply the following 

test. 


if (tfactory.getFeature(DOMSource.FEATURE) && tfactory.getFeature(StreamResult.FEATURE)) { 

... 

} 

Qualified Name Representation 

Namespaces [http://www.w3.org/TR/REC-xml-names] present something of a problem area when dealing with XML 

objects. Qualified Names appear in XML markup as prefixed names. But the prefixes themselves do not hold identity. 

Rather, it is the URIs that they contextually map to that hold the identity. Therefore, when passing a Qualified Name 

like "xyz:foo" among Java programs, one must provide a means to map "xyz" to a namespace. 

One solution has been to create a "QName" object that holds the namespace URI, as well as the prefix and local name, 

but this is not always an optimal solution, as when, for example, you want to use unique strings as keys in a dictionary 

57


Package javax.xml.transform 


object. Not having a string representation also makes it difficult to specify a namespaced identity outside the context 

of an XML document. 

In order to pass namespaced values to transformations, for instance as a set of properties to the Serializer, this specific 

ation defines that a String "qname" object parameter be passed as two-part string, the namespace URI enclosed in curly 

braces ({}), followed by the local name. If the qname has a null URI, then the String object only contains the local 

name. An application can safely check for a non-null URI by testing to see if the first character of the name is a '{' 

character. 

For example, if a URI and local name were obtained from an element defined with , then the Qualified Name would be "{http://xyz.foo.com/yada/baz.html}foo". Note 

that the prefix is lost. 

Result Tree Serialization 

Serialization of the result tree to a stream can be controlled with the javax.xml.transform.Transformer.setOutputProp 

erties [ Method setOutputProperties(java.util.Properties)] and the javax.xml.transform.Transformer.setOutputProperty 

[ Method setOutputProperty(java.lang.String, java.lang.String)] methods. Strings that match the XSLT specification 

for xsl:output attributes [http://www.w3.org/TR/xslt#output] can be referenced from the javax.xml.transform.OutputKeys 

[ Class OutputKeys] class. Other strings can be specified as well. If the transformer does not recognize an output key, 

a java.lang.IllegalArgumentException is thrown, unless the key name is namespace qualified [#qname-delimiter]. 

Output key names that are qualified by a namespace are ignored or passed on to the serializer mechanism. 

If all that is desired is the simple identity transformation of a source to a result, then javax.xml.transform.Transformer 

Factory [ Class TransformerFactory] provides a javax.xml.transform.TransformerFactory.newTransformer [ Method 

newTransformer()] method with no arguments. This method creates a Transformer that effectively copies the source 

to the result. This method may be used to create a DOM from SAX events or to create an XML or HTML stream from 

a DOM or SAX events. 

Exceptions and Error Reporting 

The transformation API throw three types of specialized exceptions. A javax.xml.transform.TransformerFactoryCon 

figurationError [ Error TransformerFactoryConfigurationError] is parallel to the javax.xml.parsers.FactoryConfigura 

tionError, and is thrown when a configuration problem with the TransformerFactory exists. This error will typically 

be thrown when the transformation factory class specified with the "javax.xml.transform.TransformerFactory" system 

property cannot be found or instantiated. 

A javax.xml.transform.TransformerConfigurationException [ Exception TransformerConfigurationException] may 

be thrown if for any reason a Transformer can not be created. A TransformerConfigurationException may be thrown 

if there is a syntax error in the transformation instructions, for example when javax.xml.transform.TransformerFact 

ory.newTransformer [ Method newTransformer(javax.xml.transform.Source)] is called. 

javax.xml.transform.TransformerException [ Exception TransformerException] is a general exception that occurs 

during the course of a transformation. A transformer exception may wrap another exception, and if any of the 

javax.xml.transform.TransformerException.printStackTrace [ Method printStackTrace()] methods are called on it, it 

will produce a list of stack dumps, starting from the most recent. The transformer exception also provides a 

javax.xml.transform.SourceLocator [ Interface SourceLocator] object which indicates where in the source tree or 

transformation instructions the error occurred. javax.xml.transform.TransformerException.getMessageAndLocation [ 

Method getMessageAndLocation()] may be called to get an error message with location info, and javax.xml.trans 

form.TransformerException.getLocationAsString [ Method getLocationAsString()] may be called to get just the location 

string. 

Transformation warnings and errors are sent to an javax.xml.transform.ErrorListener [ Interface ErrorListener], at 

which point the application may decide to report the error or warning, and may decide to throw an Exception for 

58




a non-fatal error. The ErrorListener may be set via javax.xml.transform.TransformerFactory.setErrorListener [ 

Method setErrorListener(javax.xml.transform.ErrorListener)] for reporting errors that have to do with syntax errors in 

the transformation instructions, or via javax.xml.transform.Transformer.setErrorListener [ Method setErrorListen 

er(javax.xml.transform.ErrorListener)] to report errors that occur during the transformation. The ErrorListener 

on both objects will always be valid and non- null, whether set by the application or a default implementation provided 

by the processor. The default implementation provided by the processor will report all warnings and errors to Sys 

tem.err and does not throw any Exceptions. Applications are strongly encouraged to register and use ErrorL 

isteners that insure proper behavior for warnings and errors. 

Resolution of URIs within a transformation 

The API provides a way for URIs referenced from within the stylesheet instructions or within the transformation to be 

resolved by the calling application. This can be done by creating a class that implements the javax.xml.transform.URI 

Resolver [ Interface URIResolver] interface, with its one method, javax.xml.transform.URIResolver.resolve [ Method 

resolve(java.lang.String, java.lang.String)], and use this class to set the URI resolution for the transformation instructions 

or transformation with javax.xml.transform.TransformerFactory.setURIResolver [ Method setURIResolv 

er(javax.xml.transform.URIResolver)] or javax.xml.transform.Transformer.setURIResolver [ Method setURIResolv 

er(javax.xml.transform.URIResolver)]. The URIResolver.resolve method takes two String arguments, the URI 

found in the stylesheet instructions or built as part of the transformation process, and the base URI in effect when the 

URI passed as the first argument was encountered. The returned javax.xml.transform.Source [ Interface Source] object 

must be usable by the transformer, as specified in its implemented features. 

Class OutputKeys 

Synopsis 

Provides string constants that can be used to set output properties for a Transformer, or to retrieve output properties 

from a Transformer or Templates object. 

A properties in this class are read-only. 

public OutputKeys { 

} 

See Also section 16 of the XSL Transformations (XSLT) W3C Recommendation 

[http://www.w3.org/TR/xslt#output] 



| 

javax.xml.transform.OutputKeys 

Members 

Field CDATA_SECTION_ELEMENTS 

static java.lang.String CDATA_SECTION_ELEMENTS ; 

See Also section 16 of the XSL Transformations (XSLT) W3C Recommendation. 


59




cdata-section-elements = expanded names expanded names. 

cdata-section-elements specifies a whitespace delimited list of the names of elements whose text node children 

should be output using CDATA sections. 

Field DOCTYPE_PUBLIC 

static java.lang.String DOCTYPE_PUBLIC ; 



doctype-public = string string. 

See the documentation for the javax.xml.transform.OutputKeys.DOCTYPE_SYSTEM [ Field DOCTYPE_SYSTEM] 

property for a description of what the value of the key should be. 

Field DOCTYPE_SYSTEM 

static java.lang.String DOCTYPE_SYSTEM ; 



doctype-system = string string. 

doctype-public specifies the public identifier to be used in the document type declaration. 

If the doctype-system property is specified, the xml output method should output a document type declaration imme 

diately before the first element. The name following




Field INDENT 

characters in the range #x21 to #x7E (i.e., printable ASCII characters). The value should either be a charset registered 

with the Internet Assigned Numbers Authority [IANA] [#IANA], [RFC2278] [#RFC2278] or start with X-. 

static java.lang.String INDENT ; 



indent = "yes" | "no". 

indent specifies whether the Transformer may add additional whitespace when outputting the result tree; the value 

must be yes or no. 

Field MEDIA_TYPE 

static java.lang.String MEDIA_TYPE ; 

See Also s ection 16 of the XSL Transformations (XSLT) W3C Recommendation 


media-type = string string. 

media-type specifies the media type (MIME content type) of the data that results from outputting the result tree. 

The charset parameter should not be specified explicitly; instead, when the top-level media type is text, a 

charset parameter should be added according to the character encoding actually used by the output method. 

Field METHOD 

static java.lang.String METHOD ; 



method = "xml" | "html" | "text" | expanded name expanded name. 

The method attribute identifies the overall method that should be used for outputting the result tree. Other nonnamespaced 

values may be used, such as "xhtml", but, if accepted, the handling of such values is implementation 

defined. If any of the method values are not accepted and are not namespace qualified, then javax.xml.transform.Trans 

former.setOutputProperty [ Method setOutputProperty(java.lang.String, java.lang.String)] or javax.xml.transform.Trans 

former.setOutputProperties [ Method setOutputProperties(java.util.Properties)] will throw a java.lang.IllegalArgu 

mentException. 

Field OMIT_XML_DECLARATION 

static java.lang.String OMIT_XML_DECLARATION ; 



omit-xml-declaration = "yes" | "no". 

omit-xml-declaration specifies whether the XSLT processor should output an XML declaration; the value 

must be yes or no. 

61




Field STANDALONE 

static java.lang.String STANDALONE ; 



standalone = "yes" | "no". 

standalone specifies whether the Transformer should output a standalone document declaration; the value must 

be yes or no. 

Field VERSION 

static java.lang.String VERSION ; 



version = nmtoken nmtoken. 

version specifies the version of the output method. 

When the output method is "xml", the version value specifies the version of XML to be used for outputting the result 

tree. The default value for the xml output method is 1.0. When the output method is "html", the version value indicates 

the version of the HTML. The default value for the xml output method is 4.0, which specifies that the result should be 

output as HTML conforming to the HTML 4.0 Recommendation [HTML]. If the output method is "text", the version 

property is ignored. 

Class Transformer 

Synopsis 

An instance of this abstract class can transform a source tree into a result tree. 

An instance of this class can be obtained with the TransformerFactory.newTransformer [ Method newTrans 

former(javax.xml.transform.Source)] method. This instance may then be used to process XML from a variety of sources 

and write the transformation output to a variety of sinks. 

An object of this class may not be used in multiple threads running concurrently. Different Transformers may be used 

concurrently by different threads. 

A Transformer may be used multiple times. Parameters and output properties are preserved across transformations. 

public Transformer { 

protected Transformer(); 

public void abstract transform(javax.xml.transform.Source xmlSource, 

javax.xml.transform.Result outputTarget) 

throws TransformerException; 

public void abstract setParameter(java.lang.String name, 

java.lang.Object value); 

62




public Object abstract getParameter(java.lang.String name); 

public void abstract clearParameters(); 

public void abstract setURIResolver(javax.xml.transform.URIResolver resolver); 

public URIResolver abstract getURIResolver(); 

public void abstract setOutputProperties(java.util.Properties oformat); 

public Properties abstract getOutputProperties(); 

public void abstract setOutputProperty(java.lang.String name, 

java.lang.String value) 


public String abstract getOutputProperty(java.lang.String name) 


public void abstract setErrorListener(javax.xml.transform.ErrorListener listener) 


public ErrorListener abstract getErrorListener(); 

} 

Author 





| 

javax.xml.transform.Transformer 

Members 

Constructor Transformer() 

protected Transformer(); 

Default constructor is protected on purpose. 

Method clearParameters() 

public void abstract clearParameters(); 

Clear all parameters set with setParameter and setParameters. 

Method getErrorListener() 


Get the error event handler in effect for the transformation. 

63




Method getOutputProperties() 

public Properties abstract getOutputProperties(); 

See Also 

javax.xml.transform.OutputKeys [Class OutputKeys], java.util.Properties, XSL Transformations 

(XSLT) Version 1.0 [http://www.w3.org/TR/xslt#output] 

Get a copy of the output properties for the transformation. 

The properties returned should contain properties set by the user, and properties set by the stylesheet, and these prop 

erties are "defaulted" by default properties specified by section 16 of the XSL Transformations (XSLT) W3C Recom 

mendation [http://www.w3.org/TR/xslt#output]. The properties that were specifically set by the user or the stylesheet 

should be in the base Properties list, while the XSLT default properties that were not specifically set should be the 

default Properties list. Thus, getOutputProperties().getProperty(String key) will obtain any property in that was set by 

javax.xml.transform.Transformer.setOutputProperty [ Method setOutputProperty(java.lang.String, java.lang.String)], 

javax.xml.transform.Transformer.setOutputProperties [ Method setOutputProperties(java.util.Properties)], in the 

stylesheet, or the default properties, while getOutputProperties().get(String key) will only retrieve properties that were 

explicitly set by javax.xml.transform.Transformer.setOutputProperty [ Method setOutputProperty(java.lang.String, 

java.lang.String)], javax.xml.transform.Transformer.setOutputProperties [ Method setOutputProperties(java.util.Prop 

erties)], or in the stylesheet. 

Note that mutation of the Properties object returned will not effect the properties that the transformation contains. 

If any of the argument keys are not recognized and are not namespace qualified, the property will be ignored and not 

returned. In other words the behaviour is not orthogonal with setOutputProperties [ Method setOutputProper 

ties(java.util.Properties)]. 

Method getOutputProperty(String) 

public String abstract getOutputProperty(java.lang.String name) 


Parameters 

name 

returns 

A non-null String that specifies an output property name, which may be namespace qualified. 

The string value of the output property, or null if no property was found. 

Exceptions 


If the property is not supported. 

See Also 

javax.xml.transform.OutputKeys [Class OutputKeys] 

Get an output property that is in effect for the transformation. The property specified may be a property that was set 

with setOutputProperty, or it may be a property specified in the stylesheet. 

Method getParameter(String) 

public Object abstract getParameter(java.lang.String name); 

Parameters 

name 

of Object to get 

64




returns 

A parameter that has been set with setParameter. 

Get a parameter that was explicitly set with setParameter or setParameters. 

This method does not return a default parameter value, which cannot be determined until the node context is evaluated 

during the transformation process. 

Method getURIResolver() 


Get an object that will be used to resolve URIs used in document(), etc. 

Method setErrorListener(ErrorListener) 

public void abstract setErrorListener(javax.xml.transform.ErrorListener listener) 


Parameters 

listener 

The new error listener. 

Exceptions 


if listener is null. 

Set the error event listener in effect for the transformation. 

Method setOutputProperties(Properties) 

public void abstract setOutputProperties(java.util.Properties oformat); 

Parameters 

oformat 

See Also 

A set of output properties that will be used to override any of the same properties in affect for the 

transformation. 

javax.xml.transform.OutputKeys [Class OutputKeys], java.util.Properties 

Set the output properties for the transformation. These properties will override properties set in the Templates with 

xsl:output. 

If argument to this function is null, any properties previously set are removed, and the value will revert to the value 

defined in the templates object. 

Pass a qualified property key name as a two-part string, the namespace URI enclosed in curly braces ({}), followed 

by the local name. If the name has a null URL, the String only contain the local name. An application can safely check 

for a non-null URI by testing to see if the first character of the name is a '{' character. 

For example, if a URI and local name were obtained from an element defined with , then the qualified name would be "{http://xyz.foo.com/yada/baz.html}foo". Note 

that no prefix is used. 

An IllegalArgumentException is thrown if any of the argument keys are not recognized and are not namespace 

qualified. 

65




Method setOutputProperty(String, String) 

public void abstract setOutputProperty(java.lang.String name, 

java.lang.String value) 


Parameters 

name 

value 

A non-null String that specifies an output property name, which may be namespace qualified. 

The non-null string value of the output property. 

Exceptions 


If the property is not supported, and is not qualified with a namespace. 

See Also 

javax.xml.transform.OutputKeys [Class OutputKeys] 

Set an output property that will be in effect for the transformation. 

Pass a qualified property name as a two-part string, the namespace URI enclosed in curly braces ({}), followed by the 

local name. If the name has a null URL, the String only contain the local name. An application can safely check for a 

non-null URI by testing to see if th first character of the name is a '{' character. 



The Properties object that was passed to javax.xml.transform.Transformer.setOutputProperties [ Method setOutput 

Properties(java.util.Properties)] won't be effected by calling this method. 

Method setParameter(String, Object) 

public void abstract setParameter(java.lang.String name, 


Parameters 

name The name of the parameter, which may begin with a namespace URI in curly braces ({}). 

value 

The value object. This can be any valid Java object. It is up to the processor to provide the proper object 

coersion or to simply pass the object on for use in an extension. 

Add a parameter for the transformation. 

Pass a qualified name as a two-part string, the namespace URI enclosed in curly braces ({}), followed by the local 

name. If the name has a null URL, the String only contain the local name. An application can safely check for a nonnull 

URI by testing to see if the first character of the name is a '{' character. 



66




Method setURIResolver(URIResolver) 


Parameters 

resolver 

An object that implements the URIResolver interface, or null. 

Set an object that will be used to resolve URIs used in document(). 

If the resolver argument is null, the URIResolver value will be cleared, and the default behavior will be used. 

Method transform(Source, Result) 

public void abstract transform(javax.xml.transform.Source xmlSource, 

javax.xml.transform.Result outputTarget) 


Parameters 

xmlSource 

outputTarget 

The XML input to transform. 

The Result of transforming the xmlSource. 

Exceptions 

TransformerException 

If an unrecoverable error occurs during the course of the transformation. 

Transform the XML Source to a Result. Specific transformation behavior is determined by the settings of the 

TransformerFactory in effect when the Transformer was instantiated and any modifications made to the 

Transformer instance. 

The Result of transforming an empty Source is an empty Result. 

Empty Source and Result Definitions 

Source 

javax.xml.transform.sax.SAXSource 

[Class SAXSource] 

javax.xml.transform.dom.DOMSource 

[Class DOMSource] 

javax.xml.transform.stream.Stream 

Source [Class StreamSource] 

Result 

Empty Representation 


[Constructor SAXSource()] which uses 

org.xml.sax.InputSource to create an 

empty SAXSource 


[Constructor DOMSource()] which 

uses javax.xml.parsers.DocumentBuild 

er#newDocument() to create an empty 

DOMSource 

javax.xml.transform.stream.Stream 

Source [Constructor StreamSource()] 

which uses java.io.InputStream to cre 

ate an empty StreamSource 

Empty Representation 

67




Empty Source and Result Definitions 

javax.xml.transform.sax.SAXResult 

[Class SAXResult] 

The SAXResult that was passed as 

a parameter is left unchanged. No 

methods in SAXResult are invoked. 

No methods in any registered Con 

tentHandler or LexicalHand 

ler are invoked. 

javax.xml.transform.dom.DOMResult The DOMResult that was passed as 

[Class DOMResult] 

a parameter is left unchanged. No 

methods in DOMResult are invoked. 

javax.xml.transform.stream.StreamRes 

ult [Class StreamResult] 

Class TransformerFactory 

Synopsis 

The StreamResult that was passed 

as a parameter is left unchanged. No 

methods in StreamResult are in 

voked. 

A TransformerFactory instance can be used to create javax.xml.transform.Transformer [ Class Transformer] and 

javax.xml.transform.Templates [ Interface Templates] objects. 

The system property that determines which Factory implementation to create is named "javax.xml.trans 

form.TransformerFactory". This property names a concrete subclass of the TransformerFactory abstract 

class. If the property is not defined, a platform default is be used. 

public TransformerFactory { 

protected TransformerFactory(); 

static TransformerFactory newInstance() 

throws TransformerFactoryConfigurationError; 

public Transformer abstract newTransformer(javax.xml.transform.Source source) 

throws TransformerConfigurationException; 

public Transformer abstract newTransformer() 


public Templates abstract newTemplates(javax.xml.transform.Source source) 


public Source abstract getAssociatedStylesheet(javax.xml.transform.Source source, 

java.lang.String media, 

java.lang.String title, 

java.lang.String charset) 




68




public boolean abstract getFeature(java.lang.String name); 



public Object abstract getAttribute(java.lang.String name); 

public void abstract setErrorListener(javax.xml.transform.ErrorListener listener); 


} 

Author 




| 

javax.xml.transform.TransformerFactory 

Members 

Constructor TransformerFactory() 

protected TransformerFactory(); 

Default constructor is protected on purpose. 

Method getAssociatedStylesheet(Source, String, String, String) 

public Source abstract getAssociatedStylesheet(javax.xml.transform.Source source, 

java.lang.String media, 

java.lang.String title, 

java.lang.String charset) 


Parameters 

source 

media 

title 

charset 

returns 

The XML source document. 

The media attribute to be matched. May be null, in which case the prefered templates will be used 

(i.e. alternate = no). 

The value of the title attribute to match. May be null. 

The value of the charset attribute to match. May be null. 

A Source Object suitable for passing to the TransformerFactory. 

Exceptions 

TransformerConfigura 

tionException 

An Exception is thrown if an error occurings during parsing of the source. 

69




See Also 

Associating Style Sheets with XML documents Version 1.0 [http://www.w3.org/TR/xml-stylesheet/] 

Get the stylesheet specification(s) associated with the XML Source document via the xml-stylesheet processing in 

struction [http://www.w3.org/TR/xml-stylesheet/] that match the given criteria. Note that it is possible to return several 

stylesheets, in which case they are applied as if they were a list of imports or cascades in a single stylesheet. 

Method getAttribute(String) 

public Object abstract getAttribute(java.lang.String name); 

Parameters 

name 

returns 


value The value of the attribute. 

Allows the user to retrieve specific attributes on the underlying implementation. An IllegalArgumentException 

is thrown if the underlying implementation doesn't recognize the attribute. 

Method getErrorListener() 


Get the error event handler for the TransformerFactory. 


public boolean abstract getFeature(java.lang.String name); 

Parameters 

name 

returns 

The feature name, which is an absolute URI. 

The current state of the feature (true or false). 

Look up the value of a feature. 

The feature name is any absolute URI. 

Method getURIResolver() 


Get the object that is used by default during the transformation to resolve URIs used in document(), xsl:import, or 

xsl:include. 


static TransformerFactory newInstance() 

throws TransformerFactoryConfigurationError; 

70




Exceptions 

TransformerFactoryCon 

figurationError 

Thrown if the implementation is not available or cannot be instantiated. 

Obtain a new instance of a TransformerFactory. This static method creates a new factory instance This method 

uses the following ordered lookup procedure to determine the TransformerFactory implementation class to load: 

• Use the javax.xml.transform.TransformerFactory system property. 








API will look for a classname in the file META-INF/services/javax.xml.transform.Transformer 

Factory in jars available to the runtime. 

• Platform default TransformerFactory instance. 

Once an application has obtained a reference to a TransformerFactory it can use the factory to configure and 

obtain parser instances. 

Method newTemplates(Source) 

public Templates abstract newTemplates(javax.xml.transform.Source source) 


Parameters 

source 

returns 

An object that holds a URL, input stream, etc. 

A Templates object capable of being used for transformation purposes, never null. 

Exceptions 


tionException 

May throw this during the parse when it is constructing the Templates object and fails. 

Process the Source into a Templates object, which is a a compiled representation of the source. This Templates object 

may then be used concurrently across multiple threads. Creating a Templates object allows the TransformerFactory to 

do detailed performance optimization of transformation instructions, without penalizing runtime transformation. 

Method newTransformer() 

public Transformer abstract newTransformer() 


71




Exceptions 


tionException 

Thrown if it is not possible to create a Transformer instance. 

Create a new Transformer that performs a copy of the Source to the Result. i.e. the 

"identity transform". 

Method newTransformer(Source) 

public Transformer abstract newTransformer(javax.xml.transform.Source source) 


Parameters 

source 

returns 

Source of XSLT document used to create Transformer. Examples of XML Sources include 

DOMSource [ Class DOMSource], SAXSource [ Class SAXSource], and StreamSource [ Class 

StreamSource]. 

A Transformer object that may be used to perform a transformation in a single Thread, never 

null. 

Exceptions 


tionException 

Thrown if there are errors when parsing the Source or it is not possible to create a 

Transformer instance. 

See Also 

XSL Transformations (XSLT) Version 1.0 [http://www.w3.org/TR/xslt] 

Process the Source into a Transformer Object. The Source is an XSLT document that conforms to XSL 

Transformations (XSLT) Version 1.0 [http://www.w3.org/TR/xslt]. Care must be taken not to use this Transformer 

in multiple Threads running concurrently. Different TransformerFactories can be used concurrently by dif 

ferent Threads. 

Method setAttribute(String, Object) 



Parameters 

name 

value 


The value of the attribute. 

Allows the user to set specific attributes on the underlying implementation. An attribute in this context is defined to 

be an option that the implementation provides. An IllegalArgumentException is thrown if the underlying 

implementation doesn't recognize the attribute. 

Method setErrorListener(ErrorListener) 

public void abstract setErrorListener(javax.xml.transform.ErrorListener listener); 

72




Parameters 

listener 

The new error listener. 

Set the error event listener for the TransformerFactory, which is used for the processing of transformation instructions, 

and not for the transformation itself. An IllegalArgumentException is thrown if the ErrorListener 

listener is null. 

Method setURIResolver(URIResolver) 


Parameters 

resolver 

An object that implements the URIResolver interface, or null. 

Set an object that is used by default during the transformation to resolve URIs used in xsl:import, or xsl:include. 

Interface ErrorListener 

Synopsis 

To provide customized error handling, implement this interface and use the setErrorListener method to register 

an instance of the implmentation with the javax.xml.transform.Transformer [ Class Transformer]. The Transformer 

then reports all errors and warnings through this interface. 

If an application does not register its own custom ErrorListener, the default ErrorListener is used which 

reports all warnings and errors to System.err and does not throw any Exceptions. Applications are strongly 

encouraged to register and use ErrorListeners that insure proper behavior for warnings and errors. 

For transformation errors, a Transformer must use this interface instead of throwing an Exception: it is up to 

the application to decide whether to throw an Exception for different types of errors and warnings. Note however 

that the Transformer is not required to continue with the transformation after a call to javax.xml.transform.ErrorL 

istener.fatalError [ Method fatalError(javax.xml.transform.TransformerException)]. 

Transformers may use this mechanism to report XML parsing errors as well as transformation errors. 

implements public ErrorListener { 

} 

public void warning(javax.xml.transform.TransformerException exception) 


public void error(javax.xml.transform.TransformerException exception) 


public void fatalError(javax.xml.transform.TransformerException exception) 



javax.xml.transform.ErrorListener 

73




Members 

Method error(TransformerException) 

public void error(javax.xml.transform.TransformerException exception) 


Parameters 

exception 

The error information encapsulated in a transformer exception. 

Exceptions 

javax.xml.transform.Trans 

formerException 

if the application chooses to discontinue the transformation. 

See Also 

javax.xml.transform.TransformerException [Exception TransformerException] 

Receive notification of a recoverable error. 

The transformer must continue to try and provide normal transformation after invoking this method. It should still be 

possible for the application to process the document through to the end if no other errors are encountered. 

Method fatalError(TransformerException) 

public void fatalError(javax.xml.transform.TransformerException exception) 


Parameters 

exception 

The error information encapsulated in a TransformerException. 

Exceptions 




See Also 


Receive notification of a non-recoverable error. 

The Transformer must continue to try and provide normal transformation after invoking this method. It should still 

be possible for the application to process the document through to the end if no other errors are encountered, but there 

is no guarantee that the output will be useable. 

Method warning(TransformerException) 

public void warning(javax.xml.transform.TransformerException exception) 


Parameters 

exception 

The warning information encapsulated in a transformer exception. 

74




Exceptions 




See Also 


Receive notification of a warning. 

javax.xml.transform.Transformer [ Class Transformer] can use this method to report conditions that are not errors or 

fatal errors. The default behaviour is to take no action. 

After invoking this method, the Transformer must continue with the transformation. It should still be possible for the 

application to process the document through to the end. 

Interface Result 

Synopsis 

An object that implements this interface contains the information needed to build a transformation result tree. 

implements public Result { 

} 

public void setSystemId(java.lang.String systemId); 

public String getSystemId(); 

Author 



javax.xml.transform.Result 

Members 

Field PI_DISABLE_OUTPUT_ESCAPING 

static java.lang.String PI_DISABLE_OUTPUT_ESCAPING ; 

See Also 

disable-output-escaping in XSLT Specification [http://www.w3.org/TR/xslt#disable-output-escaping] 

The name of the processing instruction that is sent if the result tree disables output escaping. 

Normally, result tree serialization escapes & and < (and possibly other characters) when outputting text nodes. This 

ensures that the output is well-formed XML. However, it is sometimes convenient to be able to produce output that is 

almost, but not quite well-formed XML; for example, the output may include ill-formed sections that will be transformed 

into well-formed XML by a subsequent non-XML aware process. If a processing instruction is sent with this name, 

serialization should be output without any escaping. 

Result DOM trees may also have PI_DISABLE_OUTPUT_ESCAPING and PI_ENABLE_OUTPUT_ESCAPING 

inserted into the tree. 

75




Field PI_ENABLE_OUTPUT_ESCAPING 

static java.lang.String PI_ENABLE_OUTPUT_ESCAPING ; 

See Also 

disable-output-escaping in XSLT Specification [http://www.w3.org/TR/xslt#disable-output-escaping] 

The name of the processing instruction that is sent if the result tree enables output escaping at some point after having 

received a PI_DISABLE_OUTPUT_ESCAPING processing instruction. 

Method getSystemId() 


Get the system identifier that was set with setSystemId. 

Method setSystemId(String) 


Parameters 

systemId 

The system identifier as a URI string. 

Set the system identifier for this Result. 

If the Result is not to be written to a file, the system identifier is optional. The application may still want to provide 

one, however, for use in error messages and warnings, or to resolve relative output identifiers. 

Interface Source 

Synopsis 

An object that implements this interface contains the information needed to act as source input (XML source or trans 

formation instructions). 

implements public Source { 

} 




javax.xml.transform.Source 

Members 



76







Parameters 

systemId 

The system identifier as a URL string. 

Set the system identifier for this Source. 

The system identifier is optional if the source does not get its data from a URL, but it may still be useful to provide 

one. The application can use a system identifier, for example, to resolve relative URIs and to include in error messages 

and warnings. 

Interface SourceLocator 

Synopsis 

This interface is primarily for the purposes of reporting where an error occurred in the XML source or transformation 

instructions. 

implements public SourceLocator { 

} 

public String getPublicId(); 


public int getLineNumber(); 

public int getColumnNumber(); 


javax.xml.transform.SourceLocator 

Members 

Method getColumnNumber() 

public int getColumnNumber(); 

See Also 

javax.xml.transform.SourceLocator.getLineNumber [Method getLineNumber()] 

Return the character position where the current document event ends. 

Warning: The return value from the method is intended only as an approximation for the sake of error reporting; it is 

not intended to provide sufficient information to edit the character content of the original XML document. 

The return value is an approximation of the column number in the document entity or external parsed entity where the 

markup that triggered the event appears. 

77




Method getLineNumber() 

public int getLineNumber(); 

See Also 

javax.xml.transform.SourceLocator.getColumnNumber [Method getColumnNumber()] 

Return the line number where the current document event ends. 

Warning: The return value from the method is intended only as an approximation for the sake of error reporting; it is 

not intended to provide sufficient information to edit the character content of the original XML document. 

The return value is an approximation of the line number in the document entity or external parsed entity where the 

markup that triggered the event appears. 

Method getPublicId() 


See Also 

javax.xml.transform.SourceLocator.getSystemId [Method getSystemId()] 

Return the public identifier for the current document event. 

The return value is the public identifier of the document entity or of the external parsed entity in which the markup 

that triggered the event appears. 



See Also 

javax.xml.transform.SourceLocator.getPublicId [Method getPublicId()] 

Return the system identifier for the current document event. 

The return value is the system identifier of the document entity or of the external parsed entity in which the markup 

that triggered the event appears. 

If the system identifier is a URL, the parser must resolve it fully before passing it to the application. 

Interface Templates 

Synopsis 

An object that implements this interface is the runtime representation of processed transformation instructions. 

Templates must be threadsafe for a given instance over multiple threads running concurrently, and may be used multiple 

times in a given session. 

implements public Templates { 

public Transformer newTransformer() 


public Properties getOutputProperties(); 

78




} 

Members 


javax.xml.transform.Templates 

Method getOutputProperties() 

public Properties getOutputProperties(); 

Get the static properties for xsl:output. The object returned will be a clone of the internal values. Accordingly, it can 

be mutated without mutating the Templates object, and then handed in to javax.xml.transform.Transformer.setOutput 

Properties [ Method setOutputProperties(java.util.Properties)]. 

The properties returned should contain properties set by the stylesheet, and these properties are "defaulted" by default 

properties specified by section 16 of the XSL Transformations (XSLT) W3C Recommendation 

[http://www.w3.org/TR/xslt#output]. The properties that were specifically set by the stylesheet should be in the base 

Properties list, while the XSLT default properties that were not specifically set should be in the "default" Properties 

list. Thus, getOutputProperties().getProperty(String key) will obtain any property in that was set by the stylesheet, or 

the default properties, while getOutputProperties().get(String key) will only retrieve properties that were explicitly set 

in the stylesheet. 

For XSLT, Attribute Value Templates [http://www.w3.org/TR/xslt#attribute-value-templates] attribute values will be 

returned unexpanded (since there is no context at this point). The namespace prefixes inside Attribute Value Templates 

will be unexpanded, so that they remain valid XPath values. (For XSLT 1.0, this is not a problem since Attribute Value 

Templates are not allowed for xsl:output attributes. However, the will be allowed in versions after 1.1.) 

Method newTransformer() 

public Transformer newTransformer() 


Exceptions 


tionException 

if a Transformer can not be created. 

Create a new transformation context for this Templates object. 

Interface URIResolver 

Synopsis 

An object that implements this interface that can be called by the processor to turn a URI used in document(), xsl:import, 

or xsl:include into a Source object. 

implements public URIResolver { 

public Source resolve(java.lang.String href, 

java.lang.String base) 


79




} 

Members 


javax.xml.transform.URIResolver 

Method resolve(String, String) 

public Source resolve(java.lang.String href, 

java.lang.String base) 


Parameters 

href 

base 

returns 

An href attribute, which may be relative or absolute. 

The base URI in effect when the href attribute was encountered. 

A Source object, or null if the href cannot be resolved, and the processor should try to resolve the 

URI itself. 

Exceptions 

TransformerException 

if an error occurs when trying to resolve the URI. 

Called by the processor when it encounters an xsl:include, xsl:import, or document() function. 

Exception TransformerConfigurationException 

Synopsis 

Indicates a serious configuration error. 

} 

public TransformerConfigurationException extends TransformerException { 

public TransformerConfigurationException(); 

public TransformerConfigurationException(java.lang.String msg); 

public TransformerConfigurationException(java.lang.Throwable e); 

public TransformerConfigurationException(java.lang.String msg, 

java.lang.Throwable e); 

public TransformerConfigurationException(java.lang.String message, 

javax.xml.transform.SourceLocator locator); 


javax.xml.transform.SourceLocator locator, 


80




Members 



| 


| 


| 

javax.xml.transform.TransformerException 

| 

javax.xml.transform.TransformerConfigurationException 

Constructor TransformerConfigurationException() 

public TransformerConfigurationException(); 

Create a new TransformerConfigurationException with no detail mesage. 

Constructor TransformerConfigurationException(String) 

public TransformerConfigurationException(java.lang.String msg); 

Parameters 

msg 


Create a new TransformerConfigurationException with the String specified as an error message. 

Constructor TransformerConfigurationException(String, SourceLocator) 



Parameters 

message 

locator 

The error or warning message. 

The locator object for the error or warning. 

Create a new TransformerConfigurationException from a message and a Locator. 

This constructor is especially useful when an application is creating its own exception from within a DocumentHandler 

callback. 

81




Constructor TransformerConfigurationException(String, SourceLocator, 

Throwable) 




Parameters 

message 

locator 

e 

The error or warning message, or null to use the message from the embedded exception. 


Any exception. 

Wrap an existing exception in a TransformerConfigurationException. 

Constructor TransformerConfigurationException(String, Throwable) 

public TransformerConfigurationException(java.lang.String msg, 


Parameters 

e 

msg 

The exception to be encapsulated in a TransformerConfigurationException 


Create a new TransformerConfigurationException with the given Exception base cause and detail 

message. 

Constructor TransformerConfigurationException(Throwable) 

public TransformerConfigurationException(java.lang.Throwable e); 

Parameters 

eThe exception to be encapsulated in a TransformerConfigurationException. 

Create a new TransformerConfigurationException with a given Exception base cause of the error. 

Exception TransformerException 

Synopsis 

This class specifies an exceptional condition that occured during the transformation process. 

public TransformerException extends Exception { 

public TransformerException(java.lang.String message); 

public TransformerException(java.lang.Throwable e); 

82




public TransformerException(java.lang.String message, 







public SourceLocator getLocator(); 

public void setLocator(javax.xml.transform.SourceLocator location); 

public Throwable getException(); 

public Throwable getCause(); 

public Throwable initCause(java.lang.Throwable cause); 

public String getMessageAndLocation(); 

public String getLocationAsString(); 

public void printStackTrace(); 

public void printStackTrace(java.io.PrintStream s); 

public void printStackTrace(java.io.PrintWriter s); 

} 



| 


| 


| 

javax.xml.transform.TransformerException 

Members 

Constructor TransformerException(String) 

public TransformerException(java.lang.String message); 

Parameters 

message 


Create a new TransformerException. 

83




Constructor TransformerException(String, SourceLocator) 



Parameters 

message 

locator 



Create a new TransformerException from a message and a Locator. 

This constructor is especially useful when an application is creating its own exception from within a DocumentHandler 

callback. 

Constructor TransformerException(String, SourceLocator, Throwable) 




Parameters 

message 

locator 

e 



Any exception 

Wrap an existing exception in a TransformerException. 

Constructor TransformerException(String, Throwable) 



Parameters 

message 

e 


Any exception 

Wrap an existing exception in a TransformerException. 

This is used for throwing processor exceptions before the processing has started. 

Constructor TransformerException(Throwable) 

public TransformerException(java.lang.Throwable e); 

Parameters 

eThe exception to be wrapped. 

84




Create a new TransformerException wrapping an existing exception. 

Method getCause() 

public Throwable getCause(); 

Returns the cause of this throwable or null if the cause is nonexistent or unknown. (The cause is the throwable that 

caused this throwable to get thrown.) 


public Throwable getException(); 

See Also 

javax.xml.transform.TransformerException.getCause [Method getCause()] 

This method retrieves an exception that this exception wraps. 

Method getLocationAsString() 

public String getLocationAsString(); 

Get the location information as a string. 

Method getLocator() 

public SourceLocator getLocator(); 

Method getLocator retrieves an instance of a SourceLocator object that specifies where an error occured. 

Method getMessageAndLocation() 

public String getMessageAndLocation(); 

Get the error message with location information appended. 

Method initCause(Throwable) 

public Throwable initCause(java.lang.Throwable cause); 

Parameters 

cause 

the cause (which is saved for later retrieval by the javax.xml.transform.TransformerException.getCause 

[ Method getCause()] method). (A 

null 

value is permitted, and indicates that the cause is nonexistent or unknown.) 

returns 

a reference to this Throwable instance. 

Exceptions 


if cause is this throwable. (A throwable cannot be its own cause.) 

85




IllegalStateException 

if this throwable was created with javax.xml.transform.TransformerException [ Construct 

or TransformerException(java.lang.Throwable)] or javax.xml.transform.TransformerEx 

ception [ Constructor TransformerException(java.lang.String, java.lang.Throwable)], or 

this method has already been called on this throwable. 

Initializes the cause of this throwable to the specified value. (The cause is the throwable that caused this throwable to 

get thrown.) 

This method can be called at most once. It is generally called from within the constructor, or immediately after creating 

the throwable. If this throwable was created with javax.xml.transform.TransformerException [ Constructor Transformer 

Exception(java.lang.Throwable)] or javax.xml.transform.TransformerException [ Constructor TransformerExcep 

tion(java.lang.String, java.lang.Throwable)], this method cannot be called even once. 

Method printStackTrace() 

public void printStackTrace(); 

Print the the trace of methods from where the error originated. This will trace all nested exception objects, as well as 

this object. 

Method printStackTrace(PrintStream) 

public void printStackTrace(java.io.PrintStream s); 

Parameters 

sThe stream where the dump will be sent to. 


this object. 

Method printStackTrace(PrintWriter) 

public void printStackTrace(java.io.PrintWriter s); 

Parameters 

sThe writer where the dump will be sent to. 


this object. 

Method setLocator(SourceLocator) 

public void setLocator(javax.xml.transform.SourceLocator location); 

Parameters 

location 

A SourceLocator object, or null to clear the location. 

Method setLocator sets an instance of a SourceLocator object that specifies where an error occured. 

86




Error TransformerFactoryConfigurationError 

Synopsis 

Thrown when a problem with configuration with the Transformer Factories exists. This error will typically be thrown 

when the class of a transformation factory specified in the system properties cannot be found or instantiated. 

} 

public TransformerFactoryConfigurationError extends Error { 

public TransformerFactoryConfigurationError(); 

public TransformerFactoryConfigurationError(java.lang.String msg); 

public TransformerFactoryConfigurationError(java.lang.Exception e); 

public TransformerFactoryConfigurationError(java.lang.Exception e, 






| 


| 

java.lang.Error 

| 

javax.xml.transform.TransformerFactoryConfigurationError 

Members 

Constructor TransformerFactoryConfigurationError() 

public TransformerFactoryConfigurationError(); 

Create a new TransformerFactoryConfigurationError with no detail mesage. 

Constructor TransformerFactoryConfigurationError(Exception) 

public TransformerFactoryConfigurationError(java.lang.Exception e); 

Parameters 

eThe exception to be encapsulated in a TransformerFactoryConfigurationError. 

Create a new TransformerFactoryConfigurationError with a given Exception base cause of the error. 

87




Constructor TransformerFactoryConfigurationError(Exception, String) 

public TransformerFactoryConfigurationError(java.lang.Exception e, 


Parameters 

e 

msg 

The exception to be encapsulated in a TransformerFactoryConfigurationError 


Create a new TransformerFactoryConfigurationError with the given Exception base cause and detail 

message. 

Constructor TransformerFactoryConfigurationError(String) 

public TransformerFactoryConfigurationError(java.lang.String msg); 

Parameters 

msg 


Create a new TransformerFactoryConfigurationError with the String specified as an error message. 



Return the actual exception (if any) that caused this exception to be raised. 

Method getMessage() 


Return the message (if any) for this error . If there is no message for the exception and there is an encapsulated exception 

then the message of that exception will be returned. 

88



C h a p t e r 1 0 . P a c k a g e 

javax.xml.transform.dom 

This package implements DOM-specific transformation APIs. 

The javax.xml.transform.dom.DOMSource [ Class DOMSource] class allows the client of the implementation of this 

API to specify a DOM org.w3c.dom.Node as the source of the input tree. The model of how the Transformer deals 

with the DOM tree in terms of mismatches with the XSLT data model [http://www.w3.org/TR/xslt#data-model] or 

other data models is beyond the scope of this document. Any of the nodes derived from org.w3c.dom.Node are legal 

input. 

The javax.xml.transform.dom.DOMResult [ Class DOMResult] class allows a org.w3c.dom.Node to be specified to 

which result DOM nodes will be appended. If an output node is not specified, the transformer will use 

javax.xml.parsers.DocumentBuilder#newDocument to create an output org.w3c.dom.Document node. If a node is 

specified, it should be one of the following: org.w3c.dom.Document, org.w3c.dom.Element, or org.w3c.dom.Document 

Fragment. Specification of any other node type is implementation dependent and undefined by this API. If the result 

is a org.w3c.dom.Document, the output of the transformation must have a single element root to set as the document 

element. 

The javax.xml.transform.dom.DOMLocator [ Interface DOMLocator] node may be passed to javax.xml.transform.Trans 

formerException [ Exception TransformerException] objects, and retrieved by trying to cast the result of the 

javax.xml.transform.TransformerException.getLocator [ Method getLocator()] method. The implementation has no 

responsibility to use a DOMLocator instead of a javax.xml.transform.SourceLocator [ Interface SourceLocator] (though 

line numbers and the like do not make much sense for a DOM), so the result of getLocator must always be tested with 

an instanceof. 

Class DOMResult 

Synopsis 

Acts as a holder for a transformation result tree in the form of a Document Object Model (DOM) tree. 

If no output DOM source is set, the transformation will create a Document node as the holder for the result of the 

transformation, which may be retrieved with javax.xml.transform.dom.DOMResult.getNode [ Method getNode()]. 

public DOMResultimplements Result { 

public DOMResult(); 

public DOMResult(org.w3c.dom.Node node); 

public DOMResult(org.w3c.dom.Node node, 

java.lang.String systemId); 


org.w3c.dom.Node nextSibling); 


org.w3c.dom.Node nextSibling, 


89


Package javax.xml.transform.dom 


public void setNode(org.w3c.dom.Node node); 

public Node getNode(); 

public void setNextSibling(org.w3c.dom.Node nextSibling); 

public Node getNextSibling(); 



} 

Author 





| 

javax.xml.transform.dom.DOMResult 

Members 

Constructor DOMResult() 

public DOMResult(); 

Zero-argument default constructor. 

node, siblingNode and systemId will be set to null. 

Constructor DOMResult(Node) 

public DOMResult(org.w3c.dom.Node node); 

Parameters 

node 

The DOM node that will contain the result tree. 

Use a DOM node to create a new output target. 

In practice, the node should be a org.w3c.dom.Document node, a org.w3c.dom.DocumentFragment node, or a 

org.w3c.dom.Element node. In other words, a node that accepts children. 

siblingNode and systemId will be set to null. 

Constructor DOMResult(Node, Node) 


org.w3c.dom.Node nextSibling); 

90




Parameters 

node 

nextSibling 

Exceptions 



Since 1.5 


The child node where the result nodes should be inserted before. 

If nextSibling is not a sibling of node. 

If node is null and nextSibling is not null. 

Use a DOM node to create a new output target specifying the child node where the result nodes should be inserted 

before. 

In practice, node and nextSibling should be a org.w3c.dom.Document node, a org.w3c.dom.DocumentFragment 

node, or a org.w3c.dom.Element node. In other words, a node that accepts children. 

Use nextSibling to specify the child node where the result nodes should be inserted before. If nextSibling is 

not a sibling of node, then an IllegalArgumentException is thrown. If node is null and nextSibling 

is not null, then an IllegalArgumentException is thrown. If nextSibling is null, then the behavior is 

the same as calling javax.xml.transform.dom.DOMResult [ Constructor DOMResult(org.w3c.dom.Node)], i.e. append 

the result nodes as the last child of the specified node. 

systemId will be set to null. 

Constructor DOMResult(Node, Node, String) 


org.w3c.dom.Node nextSibling, 


Parameters 

node 

nextSibling 

systemId 


The child node where the result nodes should be inserted before. 

The system identifier which may be used in association with this node. 

Exceptions 





Since 1.5 

Use a DOM node to create a new output target specifying the child node where the result nodes should be inserted 

before and the specified System ID. 

In practice, node and nextSibling should be a org.w3c.dom.Document node, a org.w3c.dom.DocumentFragment 

node, or a org.w3c.dom.Element node. In other words, a node that accepts children. 

91






is not null, then an IllegalArgumentException is thrown. If nextSibling is null, then the behavior is 

the same as calling javax.xml.transform.dom.DOMResult [ Constructor DOMResult(org.w3c.dom.Node, 

java.lang.String)], i.e. append the result nodes as the last child of the specified node and use the specified System ID. 

Constructor DOMResult(Node, String) 



Parameters 

node 

systemId 


The system identifier which may be used in association with this node. 

Use a DOM node to create a new output target with the specified System ID. 



siblingNode will be set to null. 

Field FEATURE 

static java.lang.String FEATURE ; 

If javax.xml.transform.TransformerFactory.getFeature [ Method getFeature(java.lang.String)] returns true when 

passed this value as an argument, the Transformer supports Result output of this type. 

Method getNextSibling() 

public Node getNextSibling(); 

Since 1.5 

Get the child node where the result nodes will be inserted before. 

If no node was set via javax.xml.transform.dom.DOMResult [ Constructor DOMResult(org.w3c.dom.Node, 

org.w3c.dom.Node)], javax.xml.transform.dom.DOMResult [ Constructor DOMResult(org.w3c.dom.Node, 

org.w3c.dom.Node, java.lang.String)] or javax.xml.transform.dom.DOMResult.setNextSibling [ Method setNextSib 

ling(org.w3c.dom.Node)], then null will be returned. 

Method getNode() 


Get the node that will contain the result DOM tree. 

If no node was set via javax.xml.transform.dom.DOMResult [ Constructor DOMResult(org.w3c.dom.Node)], 

javax.xml.transform.dom.DOMResult [ Constructor DOMResult(org.w3c.dom.Node, java.lang.String)], 

javax.xml.transform.dom.DOMResult [ Constructor DOMResult(org.w3c.dom.Node, org.w3c.dom.Node)], 

javax.xml.transform.dom.DOMResult [ Constructor DOMResult(org.w3c.dom.Node, org.w3c.dom.Node, 

java.lang.String)] or javax.xml.transform.dom.DOMResult.setNode [ Method setNode(org.w3c.dom.Node)], then the 

92




node will be set by the transformation, and may be obtained from this method once the transformation is complete. 

Calling this method before the transformation will return null. 



Get the System Identifier. 

If no System ID was set via javax.xml.transform.dom.DOMResult [ Constructor DOMResult(org.w3c.dom.Node, 

java.lang.String)], javax.xml.transform.dom.DOMResult [ Constructor DOMResult(org.w3c.dom.Node, 

org.w3c.dom.Node, java.lang.String)] or javax.xml.transform.dom.DOMResult.setSystemId [ Method setSys 

temId(java.lang.String)], then null will be returned. 

Method setNextSibling(Node) 

public void setNextSibling(org.w3c.dom.Node nextSibling); 

Parameters 

nextSibling 

The child node where the result nodes will be inserted before. 

Exceptions 





Since 1.5 

Set the child node where the result nodes will be inserted before. 

In practice, nextSibling should be a org.w3c.dom.Document node, a org.w3c.dom.DocumentFragment node, or 

a org.w3c.dom.Element node. In other words, a node that accepts children. 



is not null, then an IllegalStateException is thrown. If nextSibling is null. then the behavior is the 

same as calling javax.xml.transform.dom.DOMResult [ Constructor DOMResult(org.w3c.dom.Node)], i.e. append the 

result nodes as the last child of the specified node. 

Method setNode(Node) 


Parameters 

node 

The node to which the transformation will be appended. 

Exceptions 



If nextSibling is not null and nextSibling is not a child of node. 


93




Set the node that will contain the result DOM tree. 



An IllegalStateException is thrown if nextSibling is not null and node is not a parent of nextSib 

ling. An IllegalStateException is thrown if node is null and nextSibling is not null. 



Parameters 

systemId 


Set the systemId that may be used in association with the node. 

Class DOMSource 

Synopsis 

Acts as a holder for a transformation Source tree in the form of a Document Object Model (DOM) tree. 

} 

public DOMSourceimplements Source { 

public DOMSource(); 

public DOMSource(org.w3c.dom.Node n); 

public DOMSource(org.w3c.dom.Node node, 

java.lang.String systemID); 



public void setSystemId(java.lang.String systemID); 


Author 



See Also 


Document Object Model (DOM) Level 2 Specification [http://www.w3.org/TR/DOM-Level-2] 


| 


94




Members 

Constructor DOMSource() 

public DOMSource(); 

See Also javax.xml.transform.Transformer.transform [Method transform(javax.xml.transform.Source, 

javax.xml.transform.Result)] 

Zero-argument default constructor. If this constructor is used, and no DOM source is set using javax.xml.trans 

form.dom.DOMSource.setNode [ Method setNode(org.w3c.dom.Node)] , then the Transformer will create an 

empty source org.w3c.dom.Document using javax.xml.parsers.DocumentBuilder#newDocument(). The Result of 

transforming an empty Source is always an empty Result. 

Constructor DOMSource(Node) 

public DOMSource(org.w3c.dom.Node n); 

Parameters 

nThe DOM node that will contain the Source tree. 

Create a new input source with a DOM node. The operation will be applied to the subtree rooted at this node. In XSLT, 

a "/" pattern still means the root of the tree (not the subtree), and the evaluation of global variables and parameters is 

done from the root node also. 

Constructor DOMSource(Node, String) 

public DOMSource(org.w3c.dom.Node node, 

java.lang.String systemID); 

Parameters 

node 

systemID 

The DOM node that will contain the Source tree. 

Specifies the base URI associated with node. 

Create a new input source with a DOM node, and with the system ID also passed in as the base URI. 

Field FEATURE 


If javax.xml.transform.TransformerFactory.getFeature [ Method getFeature(java.lang.String)] returns true when passed 

this value as an argument, the Transformer supports Source input of this type. 

Method getNode() 


Get the node that represents a Source DOM tree. 

95






Get the base ID (URL or system ID) from where URLs will be resolved. 

Method setNode(Node) 


Parameters 

node 

The node that is to be transformed. 

Set the node that will represents a Source DOM tree. 



Parameters 

systemID 

Base URL for this DOM tree. 

Set the base ID (URL or system ID) from where URLs will be resolved. 

Interface DOMLocator 

Synopsis 

Indicates the position of a node in a source DOM, intended primarily for error reporting. To use a DOMLocator, the 

receiver of an error must downcast the javax.xml.transform.SourceLocator [ Interface SourceLocator] object returned 

by an exception. A javax.xml.transform.Transformer [ Class Transformer] may use this object for purposes other than 

error reporting, for instance, to indicate the source node that originated a result node. 

implements public DOMLocator, SourceLocator { 

} 

public Node getOriginatingNode(); 


javax.xml.transform.dom.DOMLocator 

Members 

Method getOriginatingNode() 

public Node getOriginatingNode(); 

Return the node where the event occurred. 

96



Chapter 11. Package javax.xml.transform.sax 

This package implements SAX2-specific transformation APIs. It provides classes which allow input from 

org.xml.sax.ContentHandler events, and also classes that produce org.xml.sax.ContentHandler events. It also provides 

methods to set the input source as an org.xml.sax.XMLReader, or to use a org.xml.sax.InputSource as the source. It 

also allows the creation of a org.xml.sax.XMLFilter, which enables transformations to "pull" from other transformations, 

and lets the transformer to be used polymorphically as an org.xml.sax.XMLReader. 

The javax.xml.transform.sax.SAXSource [ Class SAXSource] class allows the setting of an org.xml.sax.XMLReader 

to be used for "pulling" parse events, and an org.xml.sax.InputSource that may be used to specify the SAX source. 

The javax.xml.transform.sax.SAXResult [ Class SAXResult] class allows the setting of a org.xml.sax.ContentHandler 

to be the receiver of SAX2 events from the transformation. 

The javax.xml.transform.sax.SAXTransformerFactory [ Class SAXTransformerFactory] extends javax.xml.trans 

form.TransformerFactory [ Class TransformerFactory] to provide factory methods for creating javax.xml.trans 

form.sax.TemplatesHandler [ Interface TemplatesHandler], javax.xml.transform.sax.TransformerHandler [ Interface 

TransformerHandler], and org.xml.sax.XMLReader instances. 

To obtain a javax.xml.transform.sax.SAXTransformerFactory [ Class SAXTransformerFactory], the caller must cast 

the javax.xml.transform.TransformerFactory [ Class TransformerFactory] instance returned from javax.xml.trans 

form.TransformerFactory.newInstance [ Method newInstance()]. 

The javax.xml.transform.sax.TransformerHandler [ Interface TransformerHandler] interface allows a transformation 

to be created from SAX2 parse events, which is a "push" model rather than the "pull" model that normally occurs for 

a transformation. Normal parse events are received through the org.xml.sax.ContentHandler interface, lexical events 

such as startCDATA and endCDATA are received through the org.xml.sax.ext.LexicalHandler interface, and events 

that signal the start or end of disabling output escaping are received via org.xml.sax.ContentHandler.processingInstruc 

tion, with the target parameter being javax.xml.transform.Result.PI_DISABLE_OUTPUT_ESCAPING [ Field 

PI_DISABLE_OUTPUT_ESCAPING] and javax.xml.transform.Result.PI_ENABLE_OUTPUT_ESCAPING [ Field 

PI_ENABLE_OUTPUT_ESCAPING]. If parameters, output properties, or other features need to be set on the Trans 

former handler, a javax.xml.transform.Transformer [ Class Transformer] reference will need to be obtained from 

javax.xml.transform.sax.TransformerHandler.getTransformer [ Method getTransformer()], and the methods invoked 

from that reference. 

The javax.xml.transform.sax.TemplatesHandler [ Interface TemplatesHandler] interface allows the creation of 

javax.xml.transform.Templates [ Interface Templates] objects from SAX2 parse events. Once the org.xml.sax.Con 

tentHandler events are complete, the Templates object may be obtained from javax.xml.transform.sax.TemplatesHand 

ler.getTemplates [ Method getTemplates()]. Note that javax.xml.transform.sax.TemplatesHandler.setSystemId [ 

Method setSystemId(java.lang.String)] should normally be called in order to establish a base system ID from which 

relative URLs may be resolved. 

The javax.xml.transform.sax.SAXTransformerFactory.newXMLFilter [ Method newXMLFilter(javax.xml.trans 

form.Source)] method allows the creation of a org.xml.sax.XMLFilter, which encapsulates the SAX2 notion of a "pull" 

transformation. The following illustrates several transformations chained together. Each filter points to a parent 

org.xml.sax.XMLReader, and the final transformation is caused by invoking org.xml.sax.XMLReader.parse on the final 

reader in the chain. 

Class SAXResult 

Acts as an holder for a transformation Result. 

97


Package javax.xml.transform.sax 


Synopsis 

public SAXResultimplements Result { 

public SAXResult(); 

public SAXResult(org.xml.sax.ContentHandler handler); 

public void setHandler(org.xml.sax.ContentHandler handler); 

public ContentHandler getHandler(); 

public void setLexicalHandler(org.xml.sax.ext.LexicalHandler handler); 

public LexicalHandler getLexicalHandler(); 



} 

Author 




| 

javax.xml.transform.sax.SAXResult 

Members 

Constructor SAXResult() 

public SAXResult(); 


Constructor SAXResult(ContentHandler) 

public SAXResult(org.xml.sax.ContentHandler handler); 

Parameters 

handler 

Must be a non-null ContentHandler reference. 

Create a SAXResult that targets a SAX2 org.xml.sax.ContentHandler. 

Field FEATURE 



this value as an argument, the Transformer supports Result output of this type. 

98




Method getHandler() 

public ContentHandler getHandler(); 

Get the org.xml.sax.ContentHandler that is the Result. 

Method getLexicalHandler() 

public LexicalHandler getLexicalHandler(); 

Get a SAX2 org.xml.sax.ext.LexicalHandler for the output. 




Method setHandler(ContentHandler) 

public void setHandler(org.xml.sax.ContentHandler handler); 

Parameters 

handler 

Must be a non-null ContentHandler reference. 

Set the target to be a SAX2 org.xml.sax.ContentHandler. 

Method setLexicalHandler(LexicalHandler) 

public void setLexicalHandler(org.xml.sax.ext.LexicalHandler handler); 

Parameters 

handler 

A non-null LexicalHandler for handling lexical parse events. 

Set the SAX2 org.xml.sax.ext.LexicalHandler for the output. 

This is needed to handle XML comments and the like. If the lexical handler is not set, an attempt should be made by 

the transformer to cast the org.xml.sax.ContentHandler to a LexicalHandler. 



Parameters 

systemId 


Method setSystemId Set the systemID that may be used in association with the org.xml.sax.ContentHandler. 

99




Class SAXSource 

Synopsis 

Acts as an holder for SAX-style Source. 

} 

public SAXSourceimplements Source { 

public SAXSource(); 

public SAXSource(org.xml.sax.XMLReader reader, 

org.xml.sax.InputSource inputSource); 

public SAXSource(org.xml.sax.InputSource inputSource); 

public void setXMLReader(org.xml.sax.XMLReader reader); 

public XMLReader getXMLReader(); 

public void setInputSource(org.xml.sax.InputSource inputSource); 

public InputSource getInputSource(); 



static InputSource sourceToInputSource(javax.xml.transform.Source source); 

Author 





| 


Members 

Constructor SAXSource() 

public SAXSource(); 



Zero-argument default constructor. If this constructor is used, and no SAX source is set using javax.xml.trans 

form.sax.SAXSource.setInputSource [ Method setInputSource(org.xml.sax.InputSource)] , then the Transformer 

will create an empty source org.xml.sax.InputSource using new InputSource(). The Result of transforming an empty 

Source is always an empty Result. 

100




Constructor SAXSource(InputSource) 

public SAXSource(org.xml.sax.InputSource inputSource); 

Parameters 

inputSource 

An input source reference that must be non-null and that will be passed to the parse method 

of the reader. 

Create a SAXSource, using a SAX InputSource. The javax.xml.transform.Transformer [ Class Transformer] or 

javax.xml.transform.sax.SAXTransformerFactory [ Class SAXTransformerFactory] creates a reader via 

org.xml.sax.helpers.XMLReaderFactory (if setXMLReader is not used), sets itself as the reader's org.xml.sax.Con 

tentHandler, and calls reader.parse(inputSource). 

Constructor SAXSource(XMLReader, InputSource) 

public SAXSource(org.xml.sax.XMLReader reader, 

org.xml.sax.InputSource inputSource); 

Parameters 

reader 

inputSource 

An XMLReader to be used for the parse. 

A SAX input source reference that must be non-null and that will be passed to the reader 

parse method. 

Create a SAXSource, using an org.xml.sax.XMLReader and a SAX InputSource. The javax.xml.transform.Transformer 

[ Class Transformer] or javax.xml.transform.sax.SAXTransformerFactory [ Class SAXTransformerFactory] will set 

itself to be the reader's org.xml.sax.ContentHandler, and then will call reader.parse(inputSource). 

Field FEATURE 




Method getInputSource() 

public InputSource getInputSource(); 

Get the SAX InputSource to be used for the Source. 



Get the base ID (URI or system ID) from where URIs will be resolved. 

Method getXMLReader() 

public XMLReader getXMLReader(); 

Get the XMLReader to be used for the Source. 

101




Method setInputSource(InputSource) 

public void setInputSource(org.xml.sax.InputSource inputSource); 

Parameters 

inputSource 

A valid InputSource reference. 

Set the SAX InputSource to be used for the Source. 



Parameters 

systemId 


Set the system identifier for this Source. If an input source has already been set, it will set the system ID or that input 

source, otherwise it will create a new input source. 

The system identifier is optional if there is a byte stream or a character stream, but it is still useful to provide one, since 

the application can use it to resolve relative URIs and can include it in error messages and warnings (the parser will 

attempt to open a connection to the URI only if no byte stream or character stream is specified). 

Method setXMLReader(XMLReader) 

public void setXMLReader(org.xml.sax.XMLReader reader); 

Parameters 

reader 

A valid XMLReader or XMLFilter reference. 

Set the XMLReader to be used for the Source. 

Method sourceToInputSource(Source) 

static InputSource sourceToInputSource(javax.xml.transform.Source source); 

Parameters 

source 

returns 

Must be a non-null Source reference. 

An InputSource, or null if Source can not be converted. 

Attempt to obtain a SAX InputSource object from a Source object. 

Class SAXTransformerFactory 

This class extends TransformerFactory to provide SAX-specific factory methods. It provides two types of ContentHand 

lers, one for creating Transformers, the other for creating Templates objects. 

102




Synopsis 

If an application wants to set the ErrorHandler or EntityResolver for an XMLReader used during a transformation, it 

should use a URIResolver to return the SAXSource which provides (with getXMLReader) a reference to the XMLReader. 

} 

public SAXTransformerFactory extends TransformerFactory { 

protected SAXTransformerFactory(); 

public TransformerHandler abstract newTransformerHandler(javax.xml.transform.Source src) 

throws javax.xml.transform.TransformerConfigurationException; 

public TransformerHandler abstract newTransformerHandler(javax.xml.transform.Templates te 


public TransformerHandler abstract newTransformerHandler() 


public TemplatesHandler abstract newTemplatesHandler() 


public XMLFilter abstract newXMLFilter(javax.xml.transform.Source src) 


public XMLFilter abstract newXMLFilter(javax.xml.transform.Templates templates) 




| 

javax.xml.transform.TransformerFactory 

| 

javax.xml.transform.sax.SAXTransformerFactory 

Members 

Constructor SAXTransformerFactory() 

protected SAXTransformerFactory(); 

The default constructor is protected on purpose. 

Field FEATURE 



this value as an argument, the TransformerFactory returned from javax.xml.transform.TransformerFactory.newInstance 

[ Method newInstance()] may be safely cast to a SAXTransformerFactory. 

103




Field FEATURE_XMLFILTER 

static java.lang.String FEATURE_XMLFILTER ; 


this value as an argument, the javax.xml.transform.sax.SAXTransformerFactory.newXMLFilter [ Method newXML 

Filter(javax.xml.transform.Source)] and javax.xml.transform.sax.SAXTransformerFactory.newXMLFilter [ Method 

newXMLFilter(javax.xml.transform.Templates)] methods are supported. 

Method newTemplatesHandler() 

public TemplatesHandler abstract newTemplatesHandler() 


Exceptions 


tionException 

If for some reason the TemplatesHandler cannot be created. 

Get a TemplatesHandler object that can process SAX ContentHandler events into a Templates object. 

Method newTransformerHandler() 

public TransformerHandler abstract newTransformerHandler() 


Exceptions 


tionException 

If for some reason the TransformerHandler cannot be created. 

Get a TransformerHandler object that can process SAX ContentHandler events into a Result. The transformation is 

defined as an identity (or copy) transformation, for example to copy a series of SAX parse events into a DOM tree. 

Method newTransformerHandler(Source) 

public TransformerHandler abstract newTransformerHandler(javax.xml.transform.Source src) 


Parameters 

src 

returns 

The Source of the transformation instructions. 

TransformerHandler ready to transform SAX events. 

Exceptions 


tionException 

If for some reason the TransformerHandler can not be created. 

Get a TransformerHandler object that can process SAX ContentHandler events into a Result, based on the transformation 

instructions specified by the argument. 

104




Method newTransformerHandler(Templates) 

public TransformerHandler abstract newTransformerHandler(javax.xml.transform.Templates te 


Parameters 

templates 

returns 

The compiled transformation instructions. 

TransformerHandler ready to transform SAX events. 

Exceptions 


tionException 

If for some reason the TransformerHandler can not be created. 

Get a TransformerHandler object that can process SAX ContentHandler events into a Result, based on the Templates 

argument. 

Method newXMLFilter(Source) 

public XMLFilter abstract newXMLFilter(javax.xml.transform.Source src) 


Parameters 

src 

returns 

The Source of the transformation instructions. 

An XMLFilter object, or null if this feature is not supported. 

Exceptions 


tionException 


Create an XMLFilter that uses the given Source as the transformation instructions. 

Method newXMLFilter(Templates) 

public XMLFilter abstract newXMLFilter(javax.xml.transform.Templates templates) 


Parameters 

templates 

returns 

The compiled transformation instructions. 

An XMLFilter object, or null if this feature is not supported. 

Exceptions 


tionException 


Create an XMLFilter, based on the Templates argument.. 

105




Interface TemplatesHandler 

Synopsis 

A SAX ContentHandler that may be used to process SAX parse events (parsing transformation instructions) into a 

Templates object. 

Note that TemplatesHandler does not need to implement LexicalHandler. 

implements public TemplatesHandler, ContentHandler { 

} 

public Templates getTemplates(); 




javax.xml.transform.sax.TemplatesHandler 

Members 



Get the base ID (URI or system ID) from where relative URLs will be resolved. 

Method getTemplates() 

public Templates getTemplates(); 

When a TemplatesHandler object is used as a ContentHandler for the parsing of transformation instructions, it creates 

a Templates object, which the caller can get once the SAX events have been completed. 



Parameters 

systemID 

Base URI for this stylesheet. 

Set the base ID (URI or system ID) for the Templates object created by this builder. This must be set in order to resolve 

relative URIs in the stylesheet. This must be called before the startDocument event. 

Interface TransformerHandler 

A TransformerHandler listens for SAX ContentHandler parse events and transforms them to a Result. 

106




Synopsis 

implements public TransformerHandler, ContentHandler, LexicalHandler, DTDHandler { 

} 

public void setResult(javax.xml.transform.Result result) 




public Transformer getTransformer(); 


javax.xml.transform.sax.TransformerHandler 

Members 



Get the base ID (URI or system ID) from where relative URLs will be resolved. 

Method getTransformer() 

public Transformer getTransformer(); 

Get the Transformer associated with this handler, which is needed in order to set parameters and output properties. 

Method setResult(Result) 

public void setResult(javax.xml.transform.Result result) 


Parameters 

result 

A Result instance, should not be null. 

Exceptions 


if result is invalid for some reason. 

Set the Result associated with this TransformerHandler to be used for the transformation. 



107




Parameters 

systemID 

Base URI for the source tree. 

Set the base ID (URI or system ID) from where relative URLs will be resolved. 

108



C h a p t e r 1 2 . P a c k a g e 

javax.xml.transform.stream 

This package implements stream- and URI- specific transformation APIs. 

The javax.xml.transform.stream.StreamSource [ Class StreamSource] class provides methods for specifying 

java.io.InputStream input, java.io.Reader input, and URL input in the form of strings. Even if an input stream or 

reader is specified as the source, javax.xml.transform.stream.StreamSource.setSystemId [ Method setSys 

temId(java.lang.String)] should still be called, so that the transformer can know from where it should resolve relative 

URIs. The public identifier is always optional: if the application writer includes one, it will be provided as part of the 

javax.xml.transform.SourceLocator [ Interface SourceLocator] information. 

The javax.xml.transform.stream.StreamResult [ Class StreamResult] class provides methods for specifying 

java.io.OutputStream, java.io.Writer, or an output system ID, as the output of the transformation result. 

Normally streams should be used rather than readers or writers, for both the Source and Result, since readers and 

writers already have the encoding established to and from the internal Unicode format. However, there are times when 

it is useful to write to a character stream, such as when using a StringWriter in order to write to a String, or in the case 

of reading source XML from a StringReader. 

Class StreamResult 

Synopsis 

Acts as an holder for a transformation result, which may be XML, plain Text, HTML, or some other form of markup. 

public StreamResultimplements Result { 

public StreamResult(); 

public StreamResult(java.io.OutputStream outputStream); 

public StreamResult(java.io.Writer writer); 

public StreamResult(java.lang.String systemId); 

public StreamResult(java.io.File f); 

public void setOutputStream(java.io.OutputStream outputStream); 

public OutputStream getOutputStream(); 

public void setWriter(java.io.Writer writer); 

public Writer getWriter(); 


public void setSystemId(java.io.File f); 


109


Package javax.xml.transform.stream 


} 

Author 




| 

javax.xml.transform.stream.StreamResult 

Members 

Constructor StreamResult() 

public StreamResult(); 


Constructor StreamResult(File) 

public StreamResult(java.io.File f); 

Parameters 

fMust a non-null File reference. 

Construct a StreamResult from a File. 

Constructor StreamResult(OutputStream) 

public StreamResult(java.io.OutputStream outputStream); 

Parameters 

outputStream 

A valid OutputStream reference. 

Construct a StreamResult from a byte stream. Normally, a stream should be used rather than a reader, so that the 

transformer may use instructions contained in the transformation instructions to control the encoding. 

Constructor StreamResult(String) 

public StreamResult(java.lang.String systemId); 

Parameters 

systemId 

Must be a String that conforms to the URI syntax. 

Construct a StreamResult from a URL. 

Constructor StreamResult(Writer) 

public StreamResult(java.io.Writer writer); 

110




Parameters 

writer 

A valid Writer reference. 

Construct a StreamResult from a character stream. Normally, a stream should be used rather than a reader, so that the 

transformer may use instructions contained in the transformation instructions to control the encoding. However, there 

are times when it is useful to write to a character stream, such as when using a StringWriter. 

Field FEATURE 



this value as an argument, the Transformer supports Result output of this type. 

Method getOutputStream() 

public OutputStream getOutputStream(); 

Get the byte stream that was set with setOutputStream. 




Method getWriter() 

public Writer getWriter(); 

Get the character stream that was set with setWriter. 

Method setOutputStream(OutputStream) 

public void setOutputStream(java.io.OutputStream outputStream); 

Parameters 

outputStream 

A valid OutputStream reference. 

Set the ByteStream that is to be written to. Normally, a stream should be used rather than a reader, so that the transformer 

may use instructions contained in the transformation instructions to control the encoding. 

Method setSystemId(File) 


Parameters 


Set the system ID from a File reference. 

111






Parameters 

systemId 


Set the systemID that may be used in association with the byte or character stream, or, if neither is set, use this value 

as a writeable URI (probably a file name). 

Method setWriter(Writer) 

public void setWriter(java.io.Writer writer); 

Parameters 

writer 

A valid Writer reference. 

Set the writer that is to receive the result. Normally, a stream should be used rather than a writer, so that the transformer 

may use instructions contained in the transformation instructions to control the encoding. However, there are times 

when it is useful to write to a writer, such as when using a StringWriter. 

Class StreamSource 

Synopsis 

Acts as an holder for a transformation Source in the form of a stream of XML markup. 

public StreamSourceimplements Source { 

public StreamSource(); 

public StreamSource(java.io.InputStream inputStream); 

public StreamSource(java.io.InputStream inputStream, 


public StreamSource(java.io.Reader reader); 

public StreamSource(java.io.Reader reader, 


public StreamSource(java.lang.String systemId); 

public StreamSource(java.io.File f); 

public void setInputStream(java.io.InputStream inputStream); 

public InputStream getInputStream(); 

public void setReader(java.io.Reader reader); 

public Reader getReader(); 

112




public void setPublicId(java.lang.String publicId); 





} 

Author 





| 

javax.xml.transform.stream.StreamSource 

Members 

Constructor StreamSource() 

public StreamSource(); 



Zero-argument default constructor. If this constructor is used, and no Stream source is set using javax.xml.trans 

form.stream.StreamSource.setInputStream [ Method setInputStream(java.io.InputStream)] or javax.xml.trans 

form.stream.StreamSource.setReader [ Method setReader(java.io.Reader)], then the Transformer will create an 

empty source java.io.InputStream using new InputStream(). The Result of transforming an empty Source is always 

an empty Result. 

Constructor StreamSource(File) 

public StreamSource(java.io.File f); 

Parameters 


Construct a StreamSource from a File. 

Constructor StreamSource(InputStream) 

public StreamSource(java.io.InputStream inputStream); 

Parameters 

inputStream 

A valid InputStream reference to an XML stream. 

113




Construct a StreamSource from a byte stream. Normally, a stream should be used rather than a reader, so the XML 

parser can resolve character encoding specified by the XML declaration. 

If this constructor is used to process a stylesheet, normally setSystemId should also be called, so that relative URI 

references can be resolved. 

Constructor StreamSource(InputStream, String) 

public StreamSource(java.io.InputStream inputStream, 


Parameters 

inputStream 

systemId 



Construct a StreamSource from a byte stream. Normally, a stream should be used rather than a reader, so that the XML 

parser can resolve character encoding specified by the XML declaration. 

This constructor allows the systemID to be set in addition to the input stream, which allows relative URIs to be processed. 

Constructor StreamSource(Reader) 

public StreamSource(java.io.Reader reader); 

Parameters 

reader 

A valid Reader reference to an XML character stream. 

Construct a StreamSource from a character reader. Normally, a stream should be used rather than a reader, so that the 

XML parser can resolve character encoding specified by the XML declaration. However, in many cases the encoding 

of the input stream is already resolved, as in the case of reading XML from a StringReader. 

Constructor StreamSource(Reader, String) 

public StreamSource(java.io.Reader reader, 


Parameters 

reader 

systemId 

A valid Reader reference to an XML character stream. 


Construct a StreamSource from a character reader. Normally, a stream should be used rather than a reader, so that the 

XML parser may resolve character encoding specified by the XML declaration. However, in many cases the encoding 

of the input stream is already resolved, as in the case of reading XML from a StringReader. 

Constructor StreamSource(String) 

public StreamSource(java.lang.String systemId); 

114




Parameters 

systemId 


Construct a StreamSource from a URL. 

Field FEATURE 




Method getInputStream() 

public InputStream getInputStream(); 

Get the byte stream that was set with setByteStream. 

Method getPublicId() 


Get the public identifier that was set with setPublicId. 

Method getReader() 

public Reader getReader(); 

Get the character stream that was set with setReader. 




Method setInputStream(InputStream) 

public void setInputStream(java.io.InputStream inputStream); 

Parameters 

inputStream 


Set the byte stream to be used as input. Normally, a stream should be used rather than a reader, so that the XML parser 

can resolve character encoding specified by the XML declaration. 

If this Source object is used to process a stylesheet, normally setSystemId should also be called, so that relative URL 

references can be resolved. 

Method setPublicId(String) 

public void setPublicId(java.lang.String publicId); 

115




Parameters 

publicId 

The public identifier as a string. 

Set the public identifier for this Source. 

The public identifier is always optional: if the application writer includes one, it will be provided as part of the location 

information. 

Method setReader(Reader) 

public void setReader(java.io.Reader reader); 

Parameters 

reader 

A valid Reader reference to an XML CharacterStream. 

Set the input to be a character reader. Normally, a stream should be used rather than a reader, so that the XML parser 

can resolve character encoding specified by the XML declaration. However, in many cases the encoding of the input 

stream is already resolved, as in the case of reading XML from a StringReader. 

Method setSystemId(File) 


Parameters 


Set the system ID from a File reference. 



Parameters 

systemId 

The system identifier as a URL string. 

Set the system identifier for this Source. 

The system identifier is optional if there is a byte stream or a character stream, but it is still useful to provide one, since 

the application can use it to resolve relative URIs and can include it in error messages and warnings (the parser will 

attempt to open a connection to the URI only if there is no byte stream or character stream specified). 

116



Chapter 13. Package javax.xml.namespace 

XML Namespace processing. 

The following XML standards apply: 

• XML Schema Part2: Datatypes specification [http://www.w3.org/TR/xmlschema-2/#QName] 

• Namespaces in XML [http://www.w3.org/TR/REC-xml-names/#ns-qualnames] 

• Namespaces in XML Errata [http://www.w3.org/XML/xml-names-19990114-errata] 

Class QName 

Synopsis 

QName represents a qualified name as defined in the XML specifications: XML Schema Part2: Datatypes specification 

[http://www.w3.org/TR/xmlschema-2/#QName], Namespaces in XML 

[http://www.w3.org/TR/REC-xml-names/#ns-qualnames], Namespaces in XML Errata 

[http://www.w3.org/XML/xml-names-19990114-errata]. 

The value of a QName contains a Namespace URI, local part and prefix. 

The prefix is included in QName to retain lexical information when present in an XML input source. The prefix is NOT 

used in QName.equals(Object) [ Method equals(java.lang.Object)] or to compute the QName.hashCode() [ Method 

hashCode()]. Equality and the hash code are defined using only the Namespace URI and local part. 

If not specified, the Namespace URI is set to XMLConstants.NULL_NS_URI. If not specified, the prefix is set to XM 

LConstants.DEFAULT_NS_PREFIX. 

QName is immutable. 

public QNameimplements Serializable { 

public QName(java.lang.String namespaceURI, 

java.lang.String localPart); 


java.lang.String localPart, 

java.lang.String prefix); 

public QName(java.lang.String localPart); 

public String getNamespaceURI(); 

public String getLocalPart(); 

public String getPrefix(); 

final boolean equals(java.lang.Object objectToTest); 

final int hashCode(); 

public String toString(); 

117


Package javax.xml.namespace 


static QName valueOf(java.lang.String qNameAsString); 

} 

Author 



Since 1.5 

See Also 


XML Schema Part2: Datatypes specification [http://www.w3.org/TR/xmlschema-2/#QName], 

Namespaces in XML [http://www.w3.org/TR/REC-xml-names/#ns-qualnames], Namespaces in 

XML Errata [http://www.w3.org/XML/xml-names-19990114-errata] 


| 

javax.xml.namespace.QName 

Members 

Constructor QName(String) 

public QName(java.lang.String localPart); 

Parameters 

localPart 

local part of the QName 

See Also QName(String namespaceURI, String localPart) [Constructor QName(java.lang.String, 

java.lang.String)], QName(String namespaceURI, String localPart, String prefix) [Constructor 

QName(java.lang.String, java.lang.String, java.lang.String)] 

QName constructor specifying the local part. 

If the local part is null an IllegalArgumentException is thrown. A local part of "" is allowed to preserve 

compatible behavior with QName 1.0. 

When using this constructor, the Namespace URI is set to XMLConstants.NULL_NS_URI and the prefix is set to XM 

LConstants.DEFAULT_NS_PREFIX. 

In an XML context, all Element and Attribute names exist in the context of a Namespace. Making this explicit during 

the construction of a QName helps prevent hard to diagnosis XML validity errors. The constructors QName(String 

namespaceURI, String localPart) [Constructor QName(java.lang.String, java.lang.String)] and 

javax.xml.namespace.QName [Constructor QName(java.lang.String, java.lang.String, java.lang.String)] are preferred. 

The local part is not validated as a NCName [http://www.w3.org/TR/REC-xml-names/#NT-NCName] as specified in 

Namespaces in XML [http://www.w3.org/TR/REC-xml-names/]. XMLUtils.isValidNCName(NCName) and XMLUtils.is 

ValidNCName(ncName, xmlVersion) can be used to validate NCNames. 

118




Constructor QName(String, String) 


java.lang.String localPart); 

Parameters 

namespaceURI 

localPart 

See Also 

Namespace URI of the QName 


QName(String namespaceURI, String localPart, String prefix) [Constructor QName(java.lang.String, 

java.lang.String, java.lang.String)] 

QName constructor specifying the Namespace URI and local part. 

If the Namespace URI is null, it is set to XMLConstants.NULL_NS_URI. This value represents no explicitly defined 

Namespace as defined by the Namespaces in XML [http://www.w3.org/TR/REC-xml-names/#ns-qualnames] specific 

ation. This action preserves compatible behavior with QName 1.0. Explicitly providing the XMLCon 

stants.NULL_NS_URI value is the preferred coding style. 



When using this constructor, the prefix is set to XMLConstants.DEFAULT_NS_PREFIX. 

The Namespace URI is not validated as a URI reference [http://www.ietf.org/rfc/rfc2396.txt]. The local part is not 

validated as a NCName [http://www.w3.org/TR/REC-xml-names/#NT-NCName] as specified in Namespaces in XML 

[http://www.w3.org/TR/REC-xml-names/]. XMLUtils.isValidNCName(NCName) and XMLUtils.isValidNCName(nc 

Name, xmlVersion) can be used to validate NCNames. 

Constructor QName(String, String, String) 


java.lang.String localPart, 

java.lang.String prefix); 

Parameters 

namespaceURI 

localPart 

prefix 

Namespace URI of the QName 


prefix of the QName 

QName constructor specifying the Namespace URI, local part and prefix. 

If the Namespace URI is null, it is set to XMLConstants.NULL_NS_URI. This value represents no explicitly defined 

Namespace as defined by the Namespaces in XML [http://www.w3.org/TR/REC-xml-names/#ns-qualnames] specific 

ation. This action preserves compatible behavior with QName 1.0. Explicitly providing the XMLCon 

stants.NULL_NS_URI value is the preferred coding style. 



119




If the prefix is null, an IllegalArgumentException is thrown. Use XMLConstants.DEFAULT_NS_PREFIX 

to explicitly indicate that no prefix is present or the prefix is not relevant. 

The Namespace URI is not validated as a URI reference [http://www.ietf.org/rfc/rfc2396.txt]. The local part and prefix 

are not validated as a NCName [http://www.w3.org/TR/REC-xml-names/#NT-NCName] as specified in Namespaces 

in XML [http://www.w3.org/TR/REC-xml-names/]. XMLUtils.isValidNCName(NCName) and XMLUtils.isValidNC 

Name(ncName, xmlVersion) can be used to validate NCNames. 

Method equals(Object) 

final boolean equals(java.lang.Object objectToTest); 

Parameters 

objectToTest 

returns 

the Object to test for equality with this QName 

true if the given Object is equal to this QName else false 

Test this QName for equality with another Object. 

If the Object to be tested is not a QName or is null, then this method returns false. 

Two QNames are considered equal if and only if both the Namespace URI and local part are equal. This method uses 

String.equals() to check equality of the Namespace URI and local part. The prefix is NOT used to determine 

equality. 

This method satisfies the general contract of Object.equals(Object) 

Method getLocalPart() 

public String getLocalPart(); 

Get the local part of this QName. 

Method getNamespaceURI() 

public String getNamespaceURI(); 

Get the Namespace URI of this QName. 

Method getPrefix() 

public String getPrefix(); 

Get the prefix of this QName. 

The prefix assigned to a QName might NOT be valid in a different context. For example, a QName may be assigned a 

prefix in the context of parsing a document but that prefix may be invalid in the context of a different document. 

Method hashCode() 

final int hashCode(); 

Generate the hash code for this QName. 

120




The hash code is calculated using both the Namespace URI and the local part of the QName. The prefix is NOT used 

to calculate the hash code. 

This method satisfies the general contract of Object.hashCode(). 

Method toString() 


String representation of this QName. 

The commonly accepted way of representing a QName as a String was defined [http://jclark.com/xml/xmlns.htm] 

by James Clark. Although this is not a standard specification, it is in common use, e.g. javax.xml.transform.Trans 

former#setParameter(String name, Object value). This implementation represents a QName as: "{" + Namespace URI 

+ "}" + local part. If the Namespace URI .equals(XMLConstants.NULL_NS_URI), only the local part is returned. 

An appropriate use of this method is for debugging or logging for human consumption. 

Note the prefix value is NOT returned as part of the String representation. 

This method satisfies the general contract of Object.toString(). 

Method valueOf(String) 

static QName valueOf(java.lang.String qNameAsString); 

Parameters 

qNameAsString 

returns 

See Also 

String representation of the QName 

QName corresponding to the given String 

QName.toString() [Method toString()] 

QName derived from parsing the formatted String. 

If the String is null or does not conform to QName.toString() [ Method toString()] formatting, an IllegalAr 

gumentException is thrown. 

The StringMUST be in the form returned by QName.toString() [Method toString()]. 

The commonly accepted way of representing a QName as a String was defined [http://jclark.com/xml/xmlns.htm] 

by James Clark. Although this is not a standard specification, it is in common use, e.g. javax.xml.transform.Trans 

former#setParameter(String name, Object value). This implementation parses a String formatted as: "{" + Namespace 

URI + "}" + local part. If the Namespace URI .equals(XMLConstants.NULL_NS_URI), only the local part 

should be provided. 

The prefix value CANNOT be represented in the String and will be set to XMLConstants.DEFAULT_NS_PREFIX. 

This method does not do full validation of the resulting QName. 

The Namespace URI is not validated as a URI reference [http://www.ietf.org/rfc/rfc2396.txt]. The local part is not 

validated as a NCName [http://www.w3.org/TR/REC-xml-names/#NT-NCName] as specified in Namespaces in XML 

[http://www.w3.org/TR/REC-xml-names/]. XMLUtils.isValidNCName(NCName) and XMLUtils.isValidNCName(nc 

Name, xmlVersion) can be used to validate NCNames. 

121




Interface NamespaceContext 

Interface for read only XML Namespace context processing. 

An XML Namespace has the properties: 

• Namespace URI: Namespace name expressed as a URI to which the prefix is bound 

• prefix: syntactically, this is the part of the attribute name following the XMLConstants.XMLNS_ATTRIBUTE 

("xmlns") in the Namespace declaration 

example: 

All get*(*) methods operate in the current scope for Namespace URI and prefix resolution. 

Note that a Namespace URI can be bound to multiple prefixes in the current scope. This can occur when multiple XM 

LConstants.XMLNS_ATTRIBUTE ("xmlns") Namespace declarations occur in the same Start-Tag and refer to the 

same Namespace URI. e.g. 

 

This can also occur when the same Namespace URI is used in multiple XMLConstants.XMLNS_ATTRIBUTE 

("xmlns") Namespace declarations in the logical parent element hierarchy. e.g. 

 

 

... 

 

 

Synopsis 

A prefix can only be bound to a single Namespace URI in the current scope. 

implements public NamespaceContext { 

public String getNamespaceURI(java.lang.String prefix); 

public String getPrefix(java.lang.String namespaceURI); 

public Iterator getPrefixes(java.lang.String namespaceURI); 

} 

Author 


122





Since 1.5 

See Also 


javax.XMLConstants for declarations of common XML values, XML Schema Part2: Datatypes 

[http://www.w3.org/TR/xmlschema-2/#QName], Namespaces in XML 

[http://www.w3.org/TR/REC-xml-names/#ns-qualnames], Namespaces in XML Errata 

[http://www.w3.org/XML/xml-names-19990114-errata] 

javax.xml.namespace.NamespaceContext 

Members 

Method getNamespaceURI(String) 

public String getNamespaceURI(java.lang.String prefix); 

Parameters 

prefix 

returns 

prefix to look up 

Namespace URI bound to prefix in the current scope 

Get Namespace URI bound to a prefix in the current scope. 

When requesting a Namespace URI by prefix, the following table describes the returned Namespace URI value for all 

possible prefix values: 

getNamespaceURI(prefix) return value for specified prefixes 

prefix parameter 

DEFAULT_NS_PREFIX ("") 

bound prefix 

unbound prefix 

Namespace URI return value 

default Namespace URI in the current 

scope or XMLCon 

stants.NULL_NS_URI("") when 

there is no default Namespace URI in 

the current scope 

Namespace URI bound to prefix in 

current scope 

X M L C o n 

stants.NULL_NS_URI("") 

XMLConstants.XML_NS_PREFIX XMLConstants.XML_NS_URI 

("xml") 

( " h t 

tp://www.w3.org/XML/1998/namespace") 

XMLConstants.XMLNS_ATTRIB 

UTE ("xmlns") 

null 


UTE_NS_URI ("ht 

tp://www.w3.org/2000/xmlns/") 

IllegalArgumentException is 

thrown 

123




Method getPrefix(String) 

public String getPrefix(java.lang.String namespaceURI); 

Parameters 

namespaceURI 

returns 

URI of Namespace to lookup 

prefix bound to Namespace URI in current context 

Get prefix bound to Namespace URI in the current scope. 

To get all prefixes bound to a Namespace URI in the current scope, use javax.xml.namespace.NamespaceContext.get 

Prefixes [ Method getPrefixes(java.lang.String)]. 

When requesting a prefix by Namespace URI, the following table describes the returned prefix value for all Namespace 

URI values: 

getPrefix(namespaceURI) return value for specified Namespace 

URIs 

Namespace URI parameter 

 

bound Namespace URI 

unbound Namespace URI 

XMLConstants.XML_NS_URI 

( " h t 





null 

Method getPrefixes(String) 

prefix value returned 

XMLConstants.DE 

FAULT_NS_PREFIX ("") 

prefix bound to Namespace URI in the 

current scope, if multiple prefixes are 

bound to the Namespace URI in the 

current scope, a single arbitrary prefix, 

whose choice is implementation de 

pendent, is returned 

null 

XMLConstants.XML_NS_PREFIX 

("xml") 


UTE ("xmlns") 


thrown 

public Iterator getPrefixes(java.lang.String namespaceURI); 

Parameters 

namespaceURI 

returns 

URI of Namespace to lookup 

Iterator for all prefixes bound to the Namespace URI in the current scope 

Get all prefixes bound to a Namespace URI in the current scope. 

124




An Iterator over String elements is returned in an arbitrary, implementation dependent, order. 

The Iterator is not modifiable. e.g. the remove() method will throw UnsupportedOperationException. 

When requesting prefixes by Namespace URI, the following table describes the returned prefixes value for all Namespace 

URI values: 

getPrefixes(namespaceURI) return value for specified Namespace 

URIs 

Namespace URI parameter 

bound Namespace URI, including the 

 

unbound Namespace URI 

XMLConstants.XML_NS_URI 

( " h t 





null 

prefixes value returned 

Iterator over prefixes bound to 

Namespace URI in the current scope 

in an arbitrary, implementation depend 

ent, order 

empty Iterator 

Iterator with one element set to 

XMLConstants.XML_NS_PREFIX 

("xml") 

Iterator with one element set to 


UTE ("xmlns") 


thrown 

125



Chapter 14. Package javax.xml.xpath 

XPath API for XPath 1.0. 

API provides access to the XPath evaluation environment and expression results independent of the underlying data 

object model. 

The following XML standards apply: 

• XML Path Language (XPath) Version 1.0 [http://www.w3.org/TR/xpath] 

About XPath 

The XPath language provides a simple, concise syntax for accessing individual parts of an XML document. XPath is 

a W3C-defined language and an official W3C recommendation; the W3C hosts the XML Path Language (XPath) 

Version 1.0 specification. XPath started in life in 1999 as a supplement to the XSLT and XPointer languages, but has 

more recently become popular as a stand-alone language. 

The Java XPath API evaluates expressions and returns one of five types: 

• Node 

• NodeList (an unordered collection of nodes without duplicates) 

• Boolean 

• Double 

• String 

The type returned is determined by both the type of expression and a value passed to the XPath object. 

XPath Examples 

Given the following sample XML document: 

 

 

 

 

green 

 

 

the subsequent table shows examples for performing common tasks with XPath in the context of the sample document. 

126


Package javax.xml.xpath 


XPath Expression 

/ 

/widgets/widget 

//* 

//widgets 

Description 

selects the document's root element 

selects all of the children of the root 

element with an element 

name 

selects all of the elements in the docu 

ment; the document hierarchy will be 

flattened 

selects all elements named 

anywhere they occur in the document 

/widgets/widget[@name="c"] selects the child of the root 

element that contains an 

attribute "name" with the value "c"; 

note that the child of the 

is not returned 

//widget[@name="c"]/style 

Using the XPath API 

selects the element with a 

parent element containing 

an attribute "name" with the value "c" 

As stated earlier, the evaluation of XPath expressions can return their results as one of five types: Node, NodeList, 

Boolean, Double, and String. It is not the syntax of the expression that determines the result type, but the context 

in which it is evaluated. 

To illustrate how different types may be used with the same expression, consider the evaluation of the following XPath 

expression against the sample document above: 

/widgets/widget[@name="a"]/@quantity 

The expression above selects the value of the "quantity" attribute on a child of that contains 

an attribute "name" set to a value of "a". Because of value of "quantity" is 6, it can be evaluated as either a String 

or a Double. The following code evaluates the expression as a Double: 

// parse the XML as a W3C Document 

DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder(); 

org.w3c.Document document = builder.parse(new File("/widgets.xml")); 

// evaluate the XPath expression against the Document 

XPath xpath = XPathFactory.newInstance().newXPath(); 

String expression = "/widgets/widget[@name='a']/@quantity"; 

Double quantity = (Double) xpath.evaluate(expression, document, XPathConstants.NUMBE 

The third argument of the XPath.evaluate method in the example above specifies that the result of the evaluation 

should be a Double, which is the Java implementation of the XPath Number type. To evaluate the same expression 

as a String, the third argument must be changed thusly: 

127




String quantity = (String) xpath.evaluate(expression, document, 

XPathConstants.STRING); 

Because the W3C DOM API (and thus the JAXP API) models element attributes as nodes, the same attribute value 

can also be evaluated as a Node, as shown: 

Node quantity = (Node) xpath.evaluate(expression, document, XPathConstants.NODE); 

Attr attr = (Attr) quantity; 

Finally, each expression can be evaluated as a Boolean to indicate whether or not the expression was successful in 

evaluating to any result. This too is shown: 

Boolean result = (Boolean) xpath.evaluate(expression, document, 

XPathConstants.BOOLEAN); 

Note that when the third argument is left off of the XPath.evaluate method, all expressions are evaluated to a 

String value. 

Additional Information 

There's much more to XPath than we've discussed here. For more information, you may read the W3C XPath specific 

ation [http://www.w3.org/TR/xpath], or refer to one of the many books on the subject. The default implement of this 

interface provides an XPath evaluation engine fully compliant with the W3C specification. 

• @author Ben Galbraith [mailto:Ben@galbraiths.org] 

• @author Norm Walsh [mailto:Norman.Walsh@Sun.com] 

• @author Jeff Suttor [mailto:Jeff.Suttor@Sun.com] 

• @version $Revision: 1.6 $, $Date: 2003/12/10 17:47:45 $ 

• @see XML Path Language (XPath) Version 1.0 [http://www.w3.org/TR/xpath] 

• @since 1.5 

Class XPathConstants 

Synopsis 

XPath constants. 

} 

public XPathConstants { 

final String toString(); 

Author 

Norman Walsh [mailto:Norman.Walsh@Sun.COM], Jeff Suttor [mailto:Jeff.Suttor@Sun.COM] 

128





Since 1.5 

See Also 


XML Path Language (XPath) Version 1.0 [http://www.w3.org/TR/xpath] 


| 

javax.xml.xpath.XPathConstants 

Members 

Field BOOLEAN 

static javax.xml.namespace.QName BOOLEAN ; 

The XPath 1.0 boolean data type. 

Field DOM_OBJECT_MODEL 

Field NODE 

static java.lang.String DOM_OBJECT_MODEL ; 

The URI for the DOM object model, "http://java.sun.com/jaxp/xpath/dom". 

static javax.xml.namespace.QName NODE ; 

The XPath 1.0 NodeSet data type. 

Field NODESET 

static javax.xml.namespace.QName NODESET ; 

The XPath 1.0 NodeSet data type. 

Field NUMBER 

static javax.xml.namespace.QName NUMBER ; 

The XPath 1.0 number data type. 

Field STRING 

static javax.xml.namespace.QName STRING ; 

The XPath 1.0 string data type. 



129




Human readable String of all XPathConstants public fields. 

This method satisfies the general contract of java.lang.Object.toString. 

Class XPathFactory 

Synopsis 

XPathFactory provides instances of XPaths. 

} 

public XPathFactory { 

protected XPathFactory(); 

static XPathFactory newInstance() 

throws XPathFactoryConfigurationException; 

static XPathFactory newInstance(java.lang.String uri) 


public XPath abstract newXPath(); 

Author 

Norman Walsh [mailto:Norman.Walsh@Sun.com], Jeff Suttor [mailto:Jeff.Suttor@Sun.com] 


Since 1.5 



| 

javax.xml.xpath.XPathFactory 

Members 

Constructor XPathFactory() 

protected XPathFactory(); 

Protected constructor as javax.xml.xpath.XPathFactory.newInstance [ Method newInstance()] or 

javax.xml.xpath.XPathFactory.newInstance [ Method newInstance(java.lang.String)] should be used to create a new 

instance of an XPathFactory. 


static XPathFactory newInstance() 


130




Exceptions 

XPathFactoryConfigura 

tionException 

If the default object model is unavailable. 

Get a new XPathFactory instance using the default object model. 

Method newInstance(String) 

static XPathFactory newInstance(java.lang.String uri) 


Parameters 

uri 

returns 

Identifies the underlying object model. 

New instance of an XPathFactory. 

Exceptions 

XPathFactoryConfigura 

tionException 

NullPointerException 

If the specified object model is unavailable. 

If uri is null. 

Get a new XPathFactory instance using the specified object model. 

A NullPointerException is thrown if uri is null. 

Method newXPath() 

public XPath abstract newXPath(); 

Return a new XPath using the underlying object model determined when the XPathFactory was instantiated. 

Interface XPath 

XPath provides access to the XPath evaluation environment and expressions. 

Evaluation of XPath Expressions. 

context 

variables 

If a request is made to evaluate the expression in the ab 

sence of a context item, simple expressions, such as "1+1", 

can be evaluated. Any expression that refers to the context 

will throw an javax.xml.xpath.XPathExpressionException 

[Exception XPathExpressionException]. 

If the expression contains a variable reference, its value 

will be found through the javax.xml.xpath.XPathVari 

ableResolver [Interface XPathVariableResolver] set with 

javax.xml.xpath.XPath.setXPathVariableResolver [Method 

setXPathVariableResolver(javax.xml.xpath.XPathVari 

ableResolver)]. An javax.xml.xpath.XPathExpressionEx 

ception [Exception XPathExpressionException] is raised 

131





functions 

QNames 

result 

if the variable resolver is undefined or the resolver returns 

null for the variable. The value of a variable must be 

immutable through the course of any single evaluation. 

If the expression contains a function reference, the function 

will be found through the javax.xml.xpath.XPathFunction 

Resolver [Interface XPathFunctionResolver] set with 

javax.xml.xpath.XPath.setXPathFunctionResolver 

[Method 

setXPathFunctionResolv 

er(javax.xml.xpath.XPathFunctionResolver)]. An 

javax.xml.xpath.XPathExpressionException [Exception 

XPathExpressionException] is raised if the function resolv 

er is undefined or the function resolver returns null for 

the function. 

QNames in the expression are resolved against the XPath 

namespace context set with javax.xml.xpath.XPath.set 

NamespaceContext [Method setNamespaceCon 

text(javax.xml.namespace.NamespaceContext)]. 

This result of evaluating an expression is converted to an 

instance of the desired return type. Valid return types are 

defined in javax.xml.xpath.XPathConstants [Class 

XPathConstants]. Conversion to the return type follows 

XPath conversion rules. 

Synopsis 

implements public XPath { 

public void setXPathVariableResolver(javax.xml.xpath.XPathVariableResolver resolver); 

public XPathVariableResolver getXPathVariableResolver(); 

public void setXPathFunctionResolver(javax.xml.xpath.XPathFunctionResolver resolver); 

public XPathFunctionResolver getXPathFunctionResolver(); 

public void setNamespaceContext(javax.xml.namespace.NamespaceContext nsContext); 

public NamespaceContext getNamespaceContext(); 

public XPathExpression compile(java.lang.String expression) 

throws XPathExpressionException; 

public Object evaluate(java.lang.String expression, 

java.lang.Object item, 

javax.xml.namespace.QName returnType) 


public String evaluate(java.lang.String expression, 

java.lang.Object item) 


132





java.net.URL documentURL, 




java.net.URL documentURL) 



org.xml.sax.InputSource source, 




org.xml.sax.InputSource source) 


} 

Author 

Norman Walsh [Norman.Walsh@Sun.com], Jeff Suttor [Jeff.Suttor@Sun.com] 


Since 1.5 

See Also 


XML Path Language (XPath) Version 1.0 [http://www.w3.org/TR/xpath] 

javax.xml.xpath.XPath 

Members 

Method compile(String) 

public XPathExpression compile(java.lang.String expression) 


Parameters 

expression 

returns 

The XPath expression. 

Compiled XPath expression. 

Exceptions 

XPathExpressionExcep 

tion 


If expression cannot be compiled. 

If expression is null. 

Compile an XPath expression for later evaluation. 

If expression is null, a NullPointerException is thrown. 

133




Method evaluate(String, InputSource) 


org.xml.sax.InputSource source) 


Parameters 

expression 

source 

returns 


The InputSource of the document to evaluate over. 

The String that is the result of evaluating the expression and converting the result to a 

String. 

Exceptions 


tion 


If expression cannot be evaluated. 

If expression or source is null. 

Evaluate an XPath expression in the context of the specified InputSource and return the result as a String. 

This method calls javax.xml.xpath.XPath.evaluate [ Method evaluate(java.lang.String, org.xml.sax.InputSource, 

javax.xml.namespace.QName)] with a returnType of javax.xml.xpath.XPathConstants.STRING [ Field STRING]. 

See Evaluation of XPath Expressions [#XPath-evaluation] for context item evaluation, variable, function and QName 

resolution and return type conversion. 

If expression or source is null, then a NullPointerException is thrown. 

Method evaluate(String, InputSource, QName) 


org.xml.sax.InputSource source, 



Parameters 

expression 

source 

returnType 

returns 


The input source of the document to evaluate over. 

The desired return type. 

The Object that encapsulates the result of evaluating the expression. 

Exceptions 


tion 


134




IllegalArgumentException If returnType is not one of the types defined in javax.xml.xpath.XPathConstants [ 

Class XPathConstants]. 


If expression, source or returnType is null. 

Evaluate an XPath expression in the context of the specified InputSource and return the result as the specified 

type. 

This method builds a data model for the org.xml.sax.InputSource and calls javax.xml.xpath.XPath.evaluate [ Method 

evaluate(java.lang.String, java.lang.Object, javax.xml.namespace.QName)] on the resulting document object. 



If returnType is not one of the types defined in javax.xml.xpath.XPathConstants [ Class XPathConstants], then an 

IllegalArgumentException is thrown. 

If expression, source or returnType is null, then a NullPointerException is thrown. 

Method evaluate(String, Object) 


java.lang.Object item) 


Parameters 

expression 

item 

returns 


The starting context (node or node list, for example). 


String. 

Exceptions 


tion 



If expression is null. 

Evaluate an XPath expression in the specified context and return the result as a String. 

This method calls javax.xml.xpath.XPath.evaluate [ Method evaluate(java.lang.String, java.lang.Object, 




A null value for item indicates that the expression should be evaluated without a context. If expression is null, 

then a NullPointerException is thrown. 

135




Method evaluate(String, Object, QName) 


java.lang.Object item, 



Parameters 

expression 

item 

returnType 

returns 




Result of evaluating an XPath expression as an Object of returnType. 

Exceptions 


tion 





If expression or returnType is null. 

Evaluate an XPath expression in the specified context and return the result as the specified type. 





A null value for item indicates that the expression should be evaluated without a context. If expression or re 

turnType is null, then a NullPointerException is thrown. 

Method evaluate(String, URL) 


java.net.URL documentURL) 


Parameters 

expression 

documentURL 

returns 


The URL of the document to evaluate over. 


String. 

136




Exceptions 


tion 



If expression or documentURL is null. 

Evaluate an XPath expression in the context of the specified document and return the result as a String. 

This method calls javax.xml.xpath.XPath.evaluate [ Method evaluate(java.lang.String, java.net.URL, 




If expression or documentURL is null, then a NullPointerException is thrown. 

Method evaluate(String, URL, QName) 


java.net.URL documentURL, 



Parameters 

expression 

documentURL 

returnType 

returns 




The Object that encapsulates the result of evaluating the expression. 

Exceptions 


tion 





If expression, documentURL or returnType is null. 

Evaluate an XPath expression in the context of the specified document and return the result as the specified type. 

This method builds a data model for the document identified by the URL and calls javax.xml.xpath.XPath.evaluate [ 

Method evaluate(java.lang.String, java.lang.Object, javax.xml.namespace.QName)] on the resulting document object. 





If expression, documentURL or returnType is null, then a NullPointerException is thrown. 

137




Method getNamespaceContext() 

public NamespaceContext getNamespaceContext(); 

Return the current namespace context. 

null is returned in no namespace context is in effect. 

Method getXPathFunctionResolver() 

public XPathFunctionResolver getXPathFunctionResolver(); 

Return the current function resolver. 

null is returned in no function resolver is in effect. 

Method getXPathVariableResolver() 

public XPathVariableResolver getXPathVariableResolver(); 

Return the current variable resolver. 

null is returned in no variable resolver is in effect. 

Method setNamespaceContext(NamespaceContext) 

public void setNamespaceContext(javax.xml.namespace.NamespaceContext nsContext); 

Parameters 

nsContext 

Namespace context to use. 

Exceptions 


If nsContext is null. 

Establish a namespace context. 

A NullPointerException is thrown if nsContext is null. 

Method setXPathFunctionResolver(XPathFunctionResolver) 

public void setXPathFunctionResolver(javax.xml.xpath.XPathFunctionResolver resolver); 

Parameters 

resolver 

XPath function resolver. 

Exceptions 


If resolver is null. 

Establish a function resolver. 

138




A NullPointerException is thrown if resolver is null. 

Method setXPathVariableResolver(XPathVariableResolver) 

public void setXPathVariableResolver(javax.xml.xpath.XPathVariableResolver resolver); 

Parameters 

resolver 

Variable resolver. 

Exceptions 


If resolver is null. 

Establish a variable resolver. 

A NullPointerException is thrown if resolver is null. 

Interface XPathExpression 

XPathExpression provides access to compiled XPath expressions. 


context 

variables 

functions 

QNames 

result 

If a request is made to evaluate the expression in the ab 

sence of a context item, simple expressions, such as "1+1", 

can be evaluated. Any expression that refers to the context 

will throw an javax.xml.xpath.XPathExpressionException 

[Exception XPathExpressionException]. 

If the expression contains a variable reference, its value 

will be found through the javax.xml.xpath.XPathVari 

ableResolver [Interface XPathVariableResolver]. An 


XPathExpressionException] is raised if the variable resolv 

er is undefined or the resolver returns null for the vari 

able. The value of a variable must be immutable through 

the course of any single evaluation. 

If the expression contains a function reference, the function 

will be found through the javax.xml.xpath.XPathFunction 

Resolver [Interface XPathFunctionResolver]. An 


XPathExpressionException] is raised if the function resolv 

er is undefined or the function resolver returns null for 

the function. 

QNames in the expression are resolved against the XPath 

namespace context. 

This result of evaluating an expression is converted to an 

instance of the desired return type. Valid return types are 

defined in javax.xml.xpath.XPathConstants [Class 

XPathConstants]. Conversion to the return type follows 

XPath conversion rules. 

139




Synopsis 

implements public XPathExpression { 

} 

public Object evaluate(java.lang.Object item, 



public String evaluate(java.lang.Object item) 


public Object evaluate(java.net.URL documentURL, 



public String evaluate(java.net.URL documentURL) 


public Object evaluate(org.xml.sax.InputSource source, 



public String evaluate(org.xml.sax.InputSource source) 


Author 



Since 1.5 

See Also XML Path Language (XPath) Version 1.0, Expressions 

[http://www.w3.org/TR/xpath#section-Expressions] 


javax.xml.xpath.XPathExpression 

Members 

Method evaluate(InputSource) 

public String evaluate(org.xml.sax.InputSource source) 


Parameters 

source 

returns 


The String that is the result of evaluating the expression and converting the result to a String. 

140




Exceptions 


tion 


If the expression cannot be evaluated. 

If source is null. 

Evaluate the compiled XPath expression in the context of the specified InputSource and return the result as a 

String. 

This method calls javax.xml.xpath.XPathExpression.evaluate [ Method evaluate(org.xml.sax.InputSource, 


See Evaluation of XPath Expressions [#XPathExpression-evaluation] for context item evaluation, variable, function 

and QName resolution and return type conversion. 

If source is null, then a NullPointerException is thrown. 

Method evaluate(InputSource, QName) 

public Object evaluate(org.xml.sax.InputSource source, 



Parameters 

source 

returnType 

returns 



The Object that is the result of evaluating the expression and converting the result to re 

turnType. 

Exceptions 


tion 





If source or returnType is null. 

Evaluate the compiled XPath expression in the context of the specified InputSource and return the result as the 

specified type. 

This method builds a data model for the org.xml.sax.InputSource and calls javax.xml.xpath.XPathExpression.evaluate 

[ Method evaluate(java.lang.Object, javax.xml.namespace.QName)] on the resulting document object. 





If source or returnType is null, then a NullPointerException is thrown. 

141




Method evaluate(Object) 

public String evaluate(java.lang.Object item) 


Parameters 

item 

returns 


The String that is the result of evaluating the expression and converting the result to a String. 

Exceptions 


tion 


Evaluate the compiled XPath expression in the specified context and return the result as a String. 

This method calls javax.xml.xpath.XPathExpression.evaluate [ Method evaluate(java.lang.Object, 




A null value for item indicates that the expression should be evaluated without a context. 

Method evaluate(Object, QName) 

public Object evaluate(java.lang.Object item, 



Parameters 

item 

returnType 

returns 



The Object that is the result of evaluating the expression and converting the result to re 

turnType. 

Exceptions 


tion 





If returnType is null. 

Evaluate the compiled XPath expression in the specified context and return the result as the specified type. 



142






A null value for item indicates that the expression should be evaluated without a context. If returnType is null, 

then a NullPointerException is thrown. 

Method evaluate(URL) 

public String evaluate(java.net.URL documentURL) 


Parameters 

documentURL 

returns 



String. 

Exceptions 


tion 



If documentURL is null. 

Evaluate the compiled XPath expression in the context of the specified document and return the result as a String. 

This method calls javax.xml.xpath.XPathExpression.evaluate [ Method evaluate(java.net.URL, 




If documentURL is null, then a NullPointerException is thrown. 

Method evaluate(URL, QName) 

public Object evaluate(java.net.URL documentURL, 



Parameters 

documentURL 

returnType 

returns 



The Object that is the result of evaluating the expression and converting the result to 

returnType. 

Exceptions 


tion 


143







If documentURL or returnType is null. 

Evaluate the compiled XPath expression in the context of the specified document and return the result as the specified 

type. 

This method builds a data model for the document identified by the java.net.URL and calls javax.xml.xpath.XPathEx 

pression.evaluate [ Method evaluate(java.lang.Object, javax.xml.namespace.QName)] on the resulting document object. 





If documentURL or returnType is null, then a NullPointerException is thrown. 

Interface XPathFunction 

Synopsis 

XPathFunction provides access to XPath functions. 

Functions are identified by QName and arity in XPath. 

implements public XPathFunction { 

} 

public Object evaluate(java.util.List args) 

throws XPathFunctionException; 

Author 



Since 1.5 


javax.xml.xpath.XPathFunction 

Members 

Method evaluate(List) 

public Object evaluate(java.util.List args) 

throws XPathFunctionException; 

Parameters 

args 

The arguments, null is a valid value. 

144




returns 

Exceptions 

The result of evaluating the XPath function as an Object. 

XPathFunctionException 

If args cannot be evaluated with this XPath function. 

Evaluate the function with the specified arguments. 

Interface XPathFunctionResolver 

Synopsis 

XPathFunctionResolver provides access to the set of user defined XPathFunctions. 

XPath functions are resolved by name and arity. The resolver is not needed for XPath built-in functions and the resolver 

cannot be used to override those functions. 

implements public XPathFunctionResolver { 

} 

public XPathFunction resolveFunction(javax.xml.namespace.QName functionName, 

int arity); 

Author 



Since 1.5 

See Also XML Path Language (XPath) Version 1.0, Core Function Library 

[http://www.w3.org/TR/xpath#corelib] 


javax.xml.xpath.XPathFunctionResolver 

Members 

Method resolveFunction(QName, int) 

public XPathFunction resolveFunction(javax.xml.namespace.QName functionName, 

int arity); 

Parameters 

functionName 

arity 

returns 

The function name. 

The number of arguments that the returned function must accept. 

The function or null if no function named functionName with arity arguments 

exists. 

145




Exceptions 


If functionName or arity is null. 

Find a function in the set of available functions. 

If functionName or arity is null, then a NullPointerException is thrown. 

Interface XPathVariableResolver 

Synopsis 

XPathVariableResolver provides access to the set of user defined XPath variables. 

The XPathVariableResolver and the XPath evaluator must adhere to a contract that cannot be directly enforced 

by the API. Although variables may be mutable, that is, an application may wish to evaluate the same XPath expression 

more than once with different variable values, in the course of evaluating any single XPath expression, a variable's 

value must be immutable. 

implements public XPathVariableResolver { 

} 

public Object resolveVariable(javax.xml.namespace.QName variableName); 

Author 



Since 1.5 


javax.xml.xpath.XPathVariableResolver 

Members 

Method resolveVariable(QName) 

public Object resolveVariable(javax.xml.namespace.QName variableName); 

Parameters 

variableName 

returns 

The QName of the variable name. 

The variables value, or null if no variable named variableName exists. The value 

returned must be of a type appropriate for the underlying object model. 

Exceptions 


If variableName is null. 

Find a variable in the set of available variables. 

146




If variableName is null, then a NullPointerException is thrown. 

Exception XPathException 

Synopsis 

XPathException represents a generic XPath exception. 

} 

public XPathException extends Exception { 

public XPathException(java.lang.String message); 

public XPathException(java.lang.Exception cause); 

public XPathException(java.lang.String message, 

java.lang.Exception cause); 

Author 

Norman Walsh [Norman.Walsh@Sun.com], Jeff Suttor [mailto:Jeff.Suttor@Sun.COM] 


Since 1.5 



| 


| 


| 

javax.xml.xpath.XPathException 

Members 

Constructor XPathException(Exception) 

public XPathException(java.lang.Exception cause); 

Parameters 

cause 

The cause. 

Exceptions 


if cause is null. 

Constructs a new XPathException with the specified cause. 

147




If cause is null, then a NullPointerException is thrown. 

Constructor XPathException(String) 

public XPathException(java.lang.String message); 

Parameters 

message 


Exceptions 


If message is null. 

Constructs a new XPathException with the specified detail message. 

The cause is not initialized. 

If message is null, then a NullPointerException is thrown. 

Constructor XPathException(String, Exception) 

public XPathException(java.lang.String message, 


Parameters 

message 

cause 


The cause. A null value is permitted, and indicates that the cause is nonexistent or unknown. 

Exceptions 



Constructs a new XPathException with the specified detail message and cause. 


Exception XPathExpressionException 

Synopsis 

XPathExpressionException represents an error in an XPath expression. 

public XPathExpressionException extends XPathException { 

public XPathExpressionException(java.lang.String message); 

public XPathExpressionException(java.lang.Exception cause); 

public XPathExpressionException(java.lang.String message, 


148




} 

Author 



Since 1.5 



| 


| 


| 


| 

javax.xml.xpath.XPathExpressionException 

Members 

Constructor XPathExpressionException(Exception) 

public XPathExpressionException(java.lang.Exception cause); 

Parameters 

cause 

The cause. 

Exceptions 



Constructs a new XPathExpressionException with the specified cause. 


Constructor XPathExpressionException(String) 

public XPathExpressionException(java.lang.String message); 

Parameters 

message 


Exceptions 



Constructs a new XPathExpressionException with the specified detail message. 

149






Constructor XPathExpressionException(String, Exception) 

public XPathExpressionException(java.lang.String message, 


Parameters 

message 

cause 



Exceptions 



Constructs a new XPathExpressionException with the specified detail message and cause. 


Exception XPathFactoryConfigurationException 

Synopsis 

XPathFactoryConfigurationException represents a configuration error in a XPathFactory environment. 

} 

public XPathFactoryConfigurationException extends XPathException { 

public XPathFactoryConfigurationException(java.lang.String message); 

public XPathFactoryConfigurationException(java.lang.Exception cause); 

public XPathFactoryConfigurationException(java.lang.String message, 


Author 



Since 1.5 



| 


| 


150




Members 


| 


| 

javax.xml.xpath.XPathFactoryConfigurationException 

Constructor XPathFactoryConfigurationException(Exception) 

public XPathFactoryConfigurationException(java.lang.Exception cause); 

Parameters 

cause 

The cause. 

Exceptions 



Constructs a new XPathFactoryConfigurationException with the specified cause. 


Constructor XPathFactoryConfigurationException(String) 

public XPathFactoryConfigurationException(java.lang.String message); 

Parameters 

message 


Exceptions 



Constructs a new XPathFactoryConfigurationException with the specified detail message. 



Constructor XPathFactoryConfigurationException(String, Exception) 

public XPathFactoryConfigurationException(java.lang.String message, 


Parameters 

message 

cause 



151




Exceptions 



Constructs a new XPathFactoryConfigurationException with the specified detail message and cause. 


Exception XPathFunctionException 

Synopsis 

XPathFunctionException represents an error with an XPath function. 

} 

public XPathFunctionException extends XPathExpressionException { 

public XPathFunctionException(java.lang.String message); 

public XPathFunctionException(java.lang.Exception cause); 

public XPathFunctionException(java.lang.String message, 


Author 



Since 1.5 



| 


| 


| 


| 

javax.xml.xpath.XPathExpressionException 

| 

javax.xml.xpath.XPathFunctionException 

Members 

Constructor XPathFunctionException(Exception) 

public XPathFunctionException(java.lang.Exception cause); 

152




Parameters 

cause 

The cause. 

Exceptions 



Constructs a new XPathFunctionException with the specified cause. 


Constructor XPathFunctionException(String) 

public XPathFunctionException(java.lang.String message); 

Parameters 

message 


Exceptions 



Constructs a new XPathFunctionException with the specified detail message. 



Constructor XPathFunctionException(String, Exception) 

public XPathFunctionException(java.lang.String message, 


Parameters 

message 

cause 



Exceptions 



Constructs a new XPathFunctionException with the specified detail message and cause. 


153



Chapter 15. Package javax.xml.validation 

Provides classes for schem-language agnostic validation. 

Class AbstractSchemaImpl 

Synopsis 

Partial implementation of javax.xml.validation.Schema [ Class Schema]. 

This class is intended to be used as the base class by the implementations of the validation API, to promote consistent 

behaviors among javax.xml.validation.Schema [ Class Schema] implementations. 

The only remaining method that has to be implemented by the derived class is javax.xml.validation.Schema.newVal 

idatorHandler [ Method newValidatorHandler()]. 

} 

public AbstractSchemaImpl extends Schema { 

protected AbstractSchemaImpl(); 

public Validator newValidator(); 

Author 

Kohsuke Kawaguchi [mailto:Kohsuke.Kawaguchi@Sun.com] 

Version $Revision: 1.3 $, $Date: 2003/12/06 00:21:37 $ 

Since 1.5 



| 

javax.xml.validation.Schema 

| 

javax.xml.validation.AbstractSchemaImpl 

Members 

Constructor AbstractSchemaImpl() 

protected AbstractSchemaImpl(); 

A do-nothing constructor. 

Method newValidator() 

public Validator newValidator(); 

See Also 

javax.xml.validation.Schema.newValidator [Method newValidator()] 

154


Package javax.xml.validation 


Creates a default implementation of javax.xml.validation.Validator [ Class Validator] by using javax.xml.valida 

tion.Schema.newValidatorHandler [ Method newValidatorHandler()]. 

Class Schema 

Synopsis 

Immutable in-memory representation of grammar. 

This object represents a set of constraints that can be checked/ enforced against an XML document. 

A javax.xml.validation.Schema [ Class Schema] object is thread safe and applications are encouraged to share it across 

many parsers in many threads. 

A javax.xml.validation.Schema [ Class Schema] object is immutable in the sense that it shouldn't change the set of 

constraints once it is created. In other words, if an application validates the same document twice against the same 

javax.xml.validation.Schema [ Class Schema], it must always produce the same result. 

A javax.xml.validation.Schema [ Class Schema] object is usually created from javax.xml.validation.SchemaFactory [ 

Class SchemaFactory]. 

Two kinds of validators can be created from a javax.xml.validation.Schema [ Class Schema] object. One is 

javax.xml.validation.Validator [ Class Validator], which provides highly-level validation operations that cover typical 

use cases. The other is javax.xml.validation.ValidatorHandler [ Class ValidatorHandler], which works on top of SAX 

for better modularity. 

This specification does not refine the java.lang.Object.equals method. In other words, if you parse the same schema 

twice, you may still get !schemaA.equals(schemaB). 

} 

public Schema { 

protected Schema(); 

public Validator abstract newValidator(); 

public ValidatorHandler abstract newValidatorHandler(); 

Author 



Since 1.5 

See Also 


XML Schema Part 1: Structures [http://www.w3.org/TR/xmlschema-1/], Extensible Markup Lan 

guage (XML) 1.1 [http://www.w3.org/TR/xml11/], Extensible Markup Language (XML) 1.0 

(Second Edition) [http://www.w3.org/TR/REC-xml] 


| 

javax.xml.validation.Schema 

155




Members 

Constructor Schema() 

protected Schema(); 

Constructor for the derived class. 

The constructor does nothing. 

Method newValidator() 

public Validator abstract newValidator(); 

Creates a new javax.xml.validation.Validator [ Class Validator] for this javax.xml.validation.Schema [ Class Schema]. 

A validator enforces/checks the set of constraints this object represents. 

Method newValidatorHandler() 

public ValidatorHandler abstract newValidatorHandler(); 

Creates a new javax.xml.validation.ValidatorHandler [ Class ValidatorHandler] for this javax.xml.validation.Schema 

[ Class Schema]. 

Class SchemaFactory 

Factory that creates javax.xml.validation.Schema [ Class Schema] objects. Entry-point to the validation API. 

javax.xml.validation.SchemaFactory [ Class SchemaFactory] is a schema compiler. It reads external representations 

of schemas and prepare them for validation. 

The javax.xml.validation.SchemaFactory [ Class SchemaFactory] class is not thread-safe. In other words, it is applic 

ations' responsibility to ensure that at most one thread is using a javax.xml.validation.SchemaFactory [ Class Schema 

Factory] object at any given moment. Implementations are encouraged to mark methods as 

synchronized 

to protect itself from broken clients. 

javax.xml.validation.SchemaFactory [ Class SchemaFactory] is not re-entrant. While one of the newSchema method 

is being invoked, applications may not attempt to recursively invoke the newSchema method even from the same 

thread. 

Schema Language 

This spec uses a namespace URI to designate a schema language. The following table shows the values defined by 

this specification. 

To be compliant with the spec, the implementation is only required to support W3C XML Schema 1.0, however if it 

chooses to support other schema languages listed here, it must conform to the relevant behaviors described in this spec. 

156




Schema languages not listed here are expected to introduce their own URIs to represent themselves. The 

javax.xml.validation.SchemaFactory [ Class SchemaFactory] class is capable of locating other implementations for 

other schema languages at run-time. 

Please note that this draft does not support DTD for the following reasons, and we are interested in how people feel 

on this issue. The expert group felt that the DTD support would inevitably introduce significant complexity, and that 

the benefit doesn't worth the cost. 

value 

http://www.w3.org/2001/XMLSchema 

http://relaxng.org/ns/structure/1.0 

language 

W3C XML Schema 1.0 

[http://www.w3.org/TR/xmlschema-1] 

RELAX NG 1.0 [http://www.relaxng.org/] 

Synopsis 

public SchemaFactory { 

protected SchemaFactory(); 

static SchemaFactory newInstance(java.lang.String schemaLanguage); 

public boolean getFeature(java.lang.String name) 


public void setFeature(java.lang.String name, 



public void setProperty(java.lang.String name, 

java.lang.Object object) 


public Object getProperty(java.lang.String name) 


public void abstract setErrorHandler(org.xml.sax.ErrorHandler errorHandler); 

public ErrorHandler abstract getErrorHandler(); 

public void abstract setResourceResolver(org.w3c.dom.ls.LSResourceResolver resourceResolv 

public LSResourceResolver abstract getResourceResolver(); 

public Schema newSchema(javax.xml.transform.Source schema) 


public Schema newSchema(java.io.File schema) 


public Schema newSchema(java.net.URL schema) 


public Schema abstract newSchema(javax.xml.transform.Source[] schemas) 


157




public Schema abstract newSchema() 


} 

Author 



Since 1.5 



| 

javax.xml.validation.SchemaFactory 

Members 

Constructor SchemaFactory() 

protected SchemaFactory(); 

Constructor for derived classes. 


Derived classes should create javax.xml.validation.SchemaFactory [ Class SchemaFactory] objects that have null 

org.xml.sax.ErrorHandler and null org.w3c.dom.ls.LSResourceResolver. 

Method getErrorHandler() 


See Also 

javax.xml.validation.SchemaFactory.setErrorHandler [Method setErrorHandler(org.xml.sax.Er 

rorHandler)] 

Gets the current org.xml.sax.ErrorHandler set to this javax.xml.validation.SchemaFactory [ Class SchemaFactory]. 




Parameters 

name 

returns 

The feature name, which is a non-null fully-qualified URI. 

The current value of the feature (true or false). 

Exceptions 

org.xml.sax.SAXNotRe 

cognizedException 

If the feature value can't be assigned or retrieved. 

158




org.xml.sax.SAXNotSup 

portedException 


When the javax.xml.validation.SchemaFactory [ Class SchemaFactory] recognizes the 

feature name but cannot determine its value at this time. 

if the name parameter is null. 

See Also 

javax.xml.validation.SchemaFactory.setFeature [Method setFeature(java.lang.String, boolean)] 

Look up the value of a feature flag. 

The feature name is any fully-qualified URI. It is possible for a javax.xml.validation.SchemaFactory [ Class Schema 

Factory] to recognize a feature name but temporarily be unable to return its value. 

Implementors are free (and encouraged) to invent their own features, using names built on their own URIs. 




Parameters 

name 

returns 

The property name, which is a non-null fully-qualified URI. 

The current value of the property. 

Exceptions 






If the property value can't be assigned or retrieved. 

When the XMLReader recognizes the property name but cannot determine its value at 

this time. 


See Also javax.xml.validation.SchemaFactory.setProperty [Method setProperty(java.lang.String, 

java.lang.Object)] 

Look up the value of a property. 

The property name is any fully-qualified URI. It is possible for a javax.xml.validation.SchemaFactory [ Class Schem 

aFactory] to recognize a property name but temporarily be unable to return its value. 

javax.xml.validation.SchemaFactory [ Class SchemaFactory]s are not required to recognize any specific property 

names. 

Implementors are free (and encouraged) to invent their own properties, using names built on their own URIs. 

Method getResourceResolver() 


See Also 

javax.xml.validation.SchemaFactory.setErrorHandler [Method setErrorHandler(org.xml.sax.Er 

rorHandler)] 

159




Gets the current org.w3c.dom.ls.LSResourceResolver set to this javax.xml.validation.SchemaFactory [ Class Schema 

Factory]. 

Method newInstance(String) 

static SchemaFactory newInstance(java.lang.String schemaLanguage); 

Parameters 

schemaLanguage 

returns 

Specifies the schema language which the returned SchemaFactory will understand. See 

the list of available schema languages [#schemaLanguage] for the possible values. 

New instance of a SchemaFactory 

Exceptions 



If no implementation of the schema language is available. 

If the 

schemLanguage 

parameter is null. 

See Also 

javax.xml.validation.SchemaFactoryFinder [Class SchemaFactoryFinder] 

Looks for an implementation of the javax.xml.validation.SchemaFactory [ Class SchemaFactory] class for a given 

schema language and returns it. 

This method is just a convenience method of: 

new javax.xml.validation.SchemaFactoryFinder [ 

Class SchemaFactoryFinder](classLoader).newFactory(schemaLanguage); 

where 

classLoader 

is the context class loader (in JDK1.2 or later) or the system class loader (in JDK versions earlier than 1.2) 

Method newSchema() 

public Schema abstract newSchema() 


160




Exceptions 


ception 

SAXException 

If this operation is not supported by the callee. 

If this operation is supported but failed for some reason. 

Creates a special javax.xml.validation.Schema [ Class Schema] object. 

The exact semantics of the returned javax.xml.validation.Schema [ Class Schema] object depends on the schema language 

that this javax.xml.validation.SchemaFactory [ Class SchemaFactory] is created for. 

Also, implementations are allowed to use implementation-specific property/feature to alter the semantics of this 

method. 


RELAX NG 

For XML Schema, this method creates a javax.xml.validation.Schema [ Class Schema] object that performs validation 

by using location hints specified in documents. 

The returned javax.xml.validation.Schema [ Class Schema] object assumes that if documents refer to the same URL 

in the schema location hints, they will always resolve to the same schema document. This asusmption allows imple 

mentations to reuse parsed results of schema documents so that multiple validations against the same schema will run 

faster. 

Note that the use of schema location hints introduces a vulnerability to denial-of-service attacks. 

RELAX NG does not support this operation. 

Method newSchema(File) 

public Schema newSchema(java.io.File schema) 


Parameters 

schema 

returns 

File that represents a schema. 

New Schema from parsing schema. 

Exceptions 

SAXException 


If a SAX error occurs during parsing. 

if 

schema 

is null. 

Parses the specified File as a schema and returns it as a Schema. 

161




This is a convenience method for javax.xml.validation.SchemaFactory.newSchema [ Method newSchema(javax.xml.trans 

form.Source)]. 

Method newSchema(Source) 

public Schema newSchema(javax.xml.transform.Source schema) 


Parameters 

schema 

returns 

Source that represents a schema. 


Exceptions 

SAXException 



if 

schema 

is null. 

Parses the specified source as a schema and returns it as a schema. 


form.Source[])]. 

Method newSchema(Source[]) 

public Schema abstract newSchema(javax.xml.transform.Source[] schemas) 


Parameters 

schemas 

returns 

inputs to be parsed. javax.xml.validation.SchemaFactory [ Class SchemaFactory] is required to re 

cognize javax.xml.transform.sax.SAXSource, javax.xml.transform.stream.StreamSource, and 

javax.xml.transform.dom.DOMSource. 

Always return a non-null valid javax.xml.validation.Schema [ Class Schema] object. Note that when 

an error has been reported, there is no guarantee that the returned javax.xml.validation.Schema [ 

Class Schema] object is meaningful. 

Exceptions 

SAXException 



If an error is found during processing the specified inputs. When an org.xml.sax.Er 

rorHandler is set, errors are reported to there first. See javax.xml.validation.SchemaFact 

ory.setErrorHandler [ Method setErrorHandler(org.xml.sax.ErrorHandler)]. 

If the schemas parameter itself is null or any item in the array is null. 

If any item in the array is not recognized by this method. 

162




Parses the specified source(s) as a schema and returns it as a schema. 

The callee will read all the javax.xml.transform.Sources and combine them into a single schema. The exact semantics 

of the combination depends on the schema language that this javax.xml.validation.SchemaFactory [ Class SchemaFactory] 

object is created for. 

When an org.xml.sax.ErrorHandler is set, the callee will report all the errors found in sources to the handler. If the 

handler throws an exception, it will abort the schema compilation and the same exception will be thrown from this 

method. Also, after an error is reported to a handler, the callee is allowed to abort the further processing by throwing 

it. If an error handler is not set, the callee will throw the first error it finds in the sources. 


RELAX NG 

For XML Schema, all definitions in all the sources are pulled together and assembled into one schema, as specified in 

the section 4.2 of the XML Schema spec. 

If the parsed set of schemas includes error(s) as specified in the section 5.1 of the XML Schema spec, then the error 

must be reported to the org.xml.sax.ErrorHandler. 

For RELAX NG, when multiple sources s1,s2,...,sn are specified, it will be treated as if the following single input was 

given. 

 

 

 

 

 

... 

 

 

 

 

Method newSchema(URL) 

public Schema newSchema(java.net.URL schema) 


Parameters 

schema 

returns 

URL that represents a schema. 


Exceptions 

SAXException 



if 

163




schema 

is null. 

Parses the specified URL as a schema and returns it as a Schema. 


form.Source)]. 



Parameters 

errorHandler 

A new error handler to be set. This parameter can be null. 

Sets the org.xml.sax.ErrorHandler to receive errors encountered during the newSchema method invocation. 

Error handler can be used to customize the error handling process during schema parsing. When an org.xml.sax.Er 

rorHandler is set, errors found during the parsing of schemas will be first sent to the org.xml.sax.ErrorHandler. 

The error handler can abort the parsing of a schema immediately by throwing org.xml.sax.SAXException from the 

handler. Or for example it can print an error to the screen and try to continue the processing by returning normally 

from the org.xml.sax.ErrorHandler 

If any java.lang.Throwable (or instances of its derived classes) is thrown from an org.xml.sax.ErrorHandler, the caller 

of the newSchema method will be thrown the same java.lang.Throwable object. 

javax.xml.validation.SchemaFactory [ Class SchemaFactory] is not allowed to throw org.xml.sax.SAXException without 

first reporting it to org.xml.sax.ErrorHandler. 

Applications can call this method even during a javax.xml.validation.Schema [ Class Schema] is being parsed. 

When the org.xml.sax.ErrorHandler is null, the implementation will behave as if the following org.xml.sax.ErrorHandler 

is set: 

class DraconianErrorHandler implements 

org.xml.sax.ErrorHandler { 

public void fatalError( 

org.xml.sax.SAXParseException e ) throws 

org.xml.sax.SAXException { 

throw e; 

} 

public void error( 



throw e; 

} 

public void warning( 



164




} 

} 

// noop 

When a new javax.xml.validation.SchemaFactory [ Class SchemaFactory] object is created, initially this field is set 

to null. This field will NOT be inherited to javax.xml.validation.Schema [ Class Schema]s, javax.xml.validation.Val 

idator [ Class Validator]s, or javax.xml.validation.ValidatorHandler [ Class ValidatorHandler]s that are created from 

this javax.xml.validation.SchemaFactory [ Class SchemaFactory]. 





Parameters 

name 

value 


The requested value of the feature (true or false). 

Exceptions 








feature name but cannot set the requested value. 


See Also 

javax.xml.validation.SchemaFactory.getFeature [Method getFeature(java.lang.String)] 

Set the value of a feature flag. 

Feature can be used to control the way a javax.xml.validation.SchemaFactory [ Class SchemaFactory] parses schemas, 

although javax.xml.validation.SchemaFactory [ Class SchemaFactory]s are not required to recognize any specific 

feature names. 

The feature name is any fully-qualified URI. It is possible for a javax.xml.validation.SchemaFactory [ Class Schema 

Factory] to expose a feature value but to be unable to change the current value. 





Parameters 

name 

object 


The requested value for the property. 

165




Exceptions 








property name but cannot set the requested value. 


Set the value of a property. 

The property name is any fully-qualified URI. It is possible for a javax.xml.validation.SchemaFactory [ Class Schem 

aFactory] to recognize a property name but to be unable to change the current value. 

javax.xml.validation.SchemaFactory [ Class SchemaFactory]s are not required to recognize setting any specific property 

names. 

Method setResourceResolver(LSResourceResolver) 


Parameters 

resourceResolver 

A new resource resolver to be set. This parameter can be null. 

Sets the org.w3c.dom.ls.LSResourceResolver to customize resource resolution when parsing schemas. 

javax.xml.validation.SchemaFactory [ Class SchemaFactory] uses a org.w3c.dom.ls.LSResourceResolver when it needs 

to locate external resources while parsing schemas, although exactly what constitutes "locating external resources" is 

up to each schema language. For example, for W3C XML Schema, this includes files 

 

d or 

 

ed, and DTD referenced from schema files, etc. 

Applications can call this method even during a javax.xml.validation.Schema [ Class Schema] is being parsed. 

When the org.w3c.dom.ls.LSResourceResolver is null, the implementation will behave as if the following 

org.w3c.dom.ls.LSResourceResolver is set: 

class DumbDOMResourceResolver implements 

org.w3c.dom.ls.LSResourceResolver { 

public 

org.w3c.dom.ls.LSInput resolveResource( 

String publicId, String systemId, String baseURI) { 

166




} 

} 

return null; // always return null 

If a org.w3c.dom.ls.LSResourceResolver throws a java.lang.RuntimeException (or instances of its derived classes), 

then the javax.xml.validation.SchemaFactory [ Class SchemaFactory] will abort the parsing and the caller of the 

newSchema method will receive the same java.lang.RuntimeException. When a new javax.xml.validation.Schema 

Factory [ Class SchemaFactory] object is created, initially this field is set to null. This field will NOT be inherited to 

javax.xml.validation.Schema [ Class Schema]s, javax.xml.validation.Validator [ Class Validator]s, or javax.xml.valid 

ation.ValidatorHandler [ Class ValidatorHandler]s that are created from this javax.xml.validation.SchemaFactory [ 

Class SchemaFactory]. 

Class SchemaFactoryFinder 

Implementation of javax.xml.validation.SchemaFactoryLoader [ Class SchemaFactoryLoader] that locates 

javax.xml.validation.SchemaFactory [ Class SchemaFactory] dynamically. 

Applications should first consider using the javax.xml.validation.SchemaFactory.newInstance [ Method newIn 

stance(java.lang.String)] method before using this class. 

This class implements the actual logic of the abovementioned method, and applications may use this class directly for 

more flexible processing (such as to specify the java.lang.ClassLoader, etc.) 

Resolution Process 

To find a javax.xml.validation.SchemaFactory [ Class SchemaFactory] object for a given schema language, this loader 

looks the following places in this order: 

1. If the system property "javax.xml.validation.SchemaFactory:schemaLanguage" is present 

(where schemaLanguage is the name of the schema language that the loader is looking for), then its value is read 

as ':'-separated list of class names. The loader will try to create a new instance of these classes in the order of the 

list, and it returns the first one that it succeeds. 

2. $java.home/lib/jaxp.properties is read and the value associated with the key being the system 

property above is looked for. If present, the value is processed just like above. 

3. If the system property "javax.xml.validation.SchemaFactoryLoader" is present, then the value 

is read as a ':'-separated list of class names. For each class in this list, if the loader can create a new instance of 

the class, then its javax.xml.validation.SchemaFactoryLoader.newFactory [ Method newFactory(java.lang.String)] 

method is used to try to locate a javax.xml.validation.SchemaFactory [ Class SchemaFactory] object. 

4. If the above step fails, then $java.home/lib/jaxp.properties is read and the value associated with 

the key being the system property above is read. If present, the value is processed just like above. 

5. META-INF/services/javax.xml.validation.SchemaFactoryLoader in the jar files are searched, 

and if files are present, they are read in the order they are found, and class names are extracted from each file. 

The format of this file will be explained later. Instance of those classes are created one by one and their 

javax.xml.validation.SchemaFactoryLoader.newFactory [ Method newFactory(java.lang.String)] method is used 

to try to locate a javax.xml.validation.SchemaFactory [ Class SchemaFactory] object. 

6. Platform default SchemaFactoryLoader instance is consulted. 

167




If everything fails, the javax.xml.validation.SchemaFactoryFinder.newFactory [ Method newFactory(java.lang.String)] 

method returns null. 

Tip for Trouble-shooting 

Setting the jaxp.debug system property will cause javax.xml.validation.SchemaFactoryFinder [ Class SchemaFact 

oryFinder] to print a lot of debug messages to 

System.err 

about what it is doing and where it is looking at. 

If you have problems loading javax.xml.validation.SchemaFactory [ Class SchemaFactory]s, try: 

java -Djaxp.debug=1 YourProgram .... 

F i l e F o r m a t o f 

META-INF/services/javax.xml.validation.SchemaFactoryLoader 

Example 

File is assumed to be encoded in UTF-8. Lines starting from '#' or lines that only consists of whitespaces will be ignored. 

Other lines will be trimed and considered as a class name. 

# my service property file 

# this class will be consulted first. 

org.acme.foo.MySchemaFactoryLoaderImpl 

# then if the above loader can't find it, 

# this will be used second 

org.acme.foo.AnotherSchemaFactoryLoaderImpl 

# EOF 

Synopsis 

public SchemaFactoryFinder extends SchemaFactoryLoader { 

public SchemaFactoryFinder(java.lang.ClassLoader loader); 

public SchemaFactory newFactory(java.lang.String schemaLanguage); 

} 

168




Author 

Kohsuke Kawaguchi [Kohsuke.Kawaguchi@Sun.com] 


Since 1.5 



| 

javax.xml.validation.SchemaFactoryLoader 

| 

javax.xml.validation.SchemaFactoryFinder 

Members 

Constructor SchemaFactoryFinder(ClassLoader) 

public SchemaFactoryFinder(java.lang.ClassLoader loader); 

Parameters 

loader 

to be used to load resource, javax.xml.validation.SchemaFactory [ Class SchemaFactory], and 

javax.xml.validation.SchemaFactoryLoader [ Class SchemaFactoryLoader] implementations during 

the resolution process. If this parameter is null, the default system class loader will be used. 

Constructor that specifies ClassLoader to use to find SchemaFactory. 

Method newFactory(String) 

public SchemaFactory newFactory(java.lang.String schemaLanguage); 

Parameters 


returns 

See the list of available schema languages [../SchemaFactory.html#schemaLanguage] 

null if the callee fails to create one. 

Exceptions 


If the 



Creates a new javax.xml.validation.SchemaFactory [ Class SchemaFactory] object for the specified schema language. 

Class SchemaFactoryLoader 

Factory that creates javax.xml.validation.SchemaFactory [ Class SchemaFactory]. 

169




Synopsis 

This class is intended to be used by the implementations of the validation API, not by users. 

public SchemaFactoryLoader { 

protected SchemaFactoryLoader(); 

public SchemaFactory abstract newFactory(java.lang.String schemaLanguage); 

} 

Author 

Kohsuke Kawaguchi [Kohsuke.Kawaguchi@Sun.com] 


Since 1.5 



| 

javax.xml.validation.SchemaFactoryLoader 

Members 

Constructor SchemaFactoryLoader() 

protected SchemaFactoryLoader(); 

A do-nothing constructor. 

Method newFactory(String) 

public SchemaFactory abstract newFactory(java.lang.String schemaLanguage); 

Parameters 


returns 

See the list of available schema languages [../SchemaFactory.html#schemaLanguage]. 

null if the callee fails to create one. 

Exceptions 


If the 



Creates a new javax.xml.validation.SchemaFactory [ Class SchemaFactory] object for the specified schema language. 

170




Class TypeInfoProvider 

Synopsis 

This class provides access to the type information determined by javax.xml.validation.ValidatorHandler [ Class Valid 

atorHandler]. 

Some schema languages, such as W3C XML Schema, encourages a validator to report the "type" it assigns to each 

attribute/element. Those applications who wish to access this type information can invoke methods defined on this 

"interface" to access such type information. 

Implementation of this "interface" can be obtained through the javax.xml.validation.ValidatorHandler.getTypeInfoPro 

vider [ Method getTypeInfoProvider()] method. 

} 

public TypeInfoProvider { 

protected TypeInfoProvider(); 

public TypeInfo abstract getElementTypeInfo(); 

public TypeInfo abstract getAttributeTypeInfo(int index); 

public boolean abstract isIdAttribute(int index); 

public boolean abstract isSpecified(int index); 

Author 



Since 1.5 

See Also 


org.w3c.dom.TypeInfo 


| 

javax.xml.validation.TypeInfoProvider 

Members 

Constructor TypeInfoProvider() 

protected TypeInfoProvider(); 

Constructor for the derived class. 


171




Method getAttributeTypeInfo(int) 

public TypeInfo abstract getAttributeTypeInfo(int index); 

Parameters 

index 

The index of the attribute. The same index for the org.xml.sax.Attributes object passed to the 

startElement 

callback. 

returns 

An immutable org.w3c.dom.TypeInfo object that represents the type of the specified attribute. Note 

that the caller can keep references to the obtained org.w3c.dom.TypeInfo longer than the callback 

scope. Otherwise, this method returns null if the validator is unable to determine the type. 

Exceptions 

IndexOutOfBoundsExcep 

tion 


If the index is invalid. 

If this method is called from other org.xml.sax.ContentHandler methods. 

Returns the immutable org.w3c.dom.TypeInfo object for the specified attribute of the current element. 

The method may only be called by the startElement event of the org.xml.sax.ContentHandler that the application sets 

to the javax.xml.validation.ValidatorHandler [ Class ValidatorHandler]. 

Method getElementTypeInfo() 

public TypeInfo abstract getElementTypeInfo(); 

Exceptions 



Returns the immutable org.w3c.dom.TypeInfo object for the current element. 



Method isIdAttribute(int) 

public boolean abstract isIdAttribute(int index); 

Parameters 

index 


startElement 

callback. 

172




returns 

Exceptions 

true if the type of the specified attribute is ID. 


tion 




Returns 

true 

if the specified attribute is determined to be ID. 

A javax.xml.parsers.DocumentBuilder uses this information to properly implement org.w3c.dom.Attr.isId. 



Method isSpecified(int) 

public boolean abstract isSpecified(int index); 

Parameters 

index 


startElement 

callback. 

returns 

true 

if the attribute was present before the validator processes input. 

false 

if the attribute was added by the validator. 

Exceptions 


tion 




Returns 

173




false 

if the attribute was added by the validator. 

This method provides information necessary for a javax.xml.parsers.DocumentBuilder to determine what the DOM 

tree should return from the org.w3c.dom.Attr.getSpecified method. 



A general guideline for validators is to return true if the attribute was originally present in the pipeline, and false if it 

was added by the validator. 

Class Validator 

A processor that checks an XML document against javax.xml.validation.Schema [ Class Schema]. 

A validator is a thread-unsafe and non-reentrant object. In other words, it is applications' responsibility to make sure 

that one javax.xml.validation.Validator [ Class Validator] object is not used from more than one thread at any given 

time, and while the 

validate 

method is invoked, applications may not recursively call the 

validate 

method. 

Synopsis 

public Validator { 

protected Validator(); 

public void validate(javax.xml.transform.Source source) 


public void abstract validate(javax.xml.transform.Source source, 

javax.xml.transform.Result result) 






174














} 

Author 



Since 1.5 



| 

javax.xml.validation.Validator 

Members 

Constructor Validator() 

protected Validator(); 



Derived classes should create javax.xml.validation.Validator [ Class Validator] objects that have 

null 

org.xml.sax.ErrorHandler and 

null 

org.w3c.dom.ls.LSResourceResolver. 



175




See Also 

javax.xml.validation.Validator.setErrorHandler [Method setErrorHandler(org.xml.sax.ErrorHandler)] 

Gets the current org.xml.sax.ErrorHandler set to this javax.xml.validation.Validator [ Class Validator]. 




Parameters 

name 

returns 



Exceptions 







When the javax.xml.validation.Validator [ Class Validator] recognizes the feature name 

but cannot determine its value at this time. 

When the name parameter is null. 

See Also 

javax.xml.validation.Validator.setFeature [Method setFeature(java.lang.String, boolean)] 


The feature name is any fully-qualified URI. It is possible for a javax.xml.validation.Validator [ Class Validator] to 

recognize a feature name but temporarily be unable to return its value. Some feature values may be available only in 

specific contexts, such as before, during, or after a validation. 





Parameters 

name 

returns 



Exceptions 








this time. 


176




See Also 

javax.xml.validation.Validator.setProperty [Method setProperty(java.lang.String, java.lang.Object)] 


The property name is any fully-qualified URI. It is possible for a javax.xml.validation.Validator [ Class Validator] to 

recognize a property name but temporarily be unable to return its value. Some property values may be available only 

in specific contexts, such as before, during, or after a validation. 

javax.xml.validation.Validator [ Class Validator]s are not required to recognize any specific property names. 




See Also 


Gets the current org.w3c.dom.ls.LSResourceResolver set to this javax.xml.validation.Validator [ Class Validator]. 



Parameters 

errorHandler 


Sets the org.xml.sax.ErrorHandler to receive errors encountered during the validate method invocation. 

Error handler can be used to customize the error handling process during a validation. When an org.xml.sax.ErrorHandler 

is set, errors found during the validation will be first sent to the org.xml.sax.ErrorHandler. 

The error handler can abort further validation immediately by throwing org.xml.sax.SAXException from the handler. 

Or for example it can print an error to the screen and try to continue the validation by returning normally from the 

org.xml.sax.ErrorHandler 

If any java.lang.Throwable is thrown from an org.xml.sax.ErrorHandler, the caller of the validate method will be 

thrown the same java.lang.Throwable object. 

javax.xml.validation.Validator [ Class Validator] is not allowed to throw org.xml.sax.SAXException without first re 

porting it to org.xml.sax.ErrorHandler. 


is set: 






throw e; 

} 

177




} 




throw e; 

} 




// noop 

} 

When a new javax.xml.validation.Validator [ Class Validator] object is created, initially this field is set to null. 





Parameters 

name 

value 



Exceptions 







When the javax.xml.validation.Validator [ Class Validator] recognizes the feature name 

but cannot set the requested value. 


See Also 

javax.xml.validation.Validator.getFeature [Method getFeature(java.lang.String)] 


Feature can be used to control the way a javax.xml.validation.Validator [ Class Validator] parses schemas, although 

javax.xml.validation.Validator [ Class Validator]s are not required to recognize any specific property names. 

The feature name is any fully-qualified URI. It is possible for a javax.xml.validation.Validator [ Class Validator] to 

expose a feature value but to be unable to change the current value. Some feature values may be immutable or mutable 

only in specific contexts, such as before, during, or after a validation. 





178




Parameters 

name 

object 



Exceptions 







When the javax.xml.validation.Validator [ Class Validator] recognizes the property name 

but cannot set the requested value. 



The property name is any fully-qualified URI. It is possible for a javax.xml.validation.Validator [ Class Validator] to 

recognize a property name but to be unable to change the current value. Some property values may be immutable or 

mutable only in specific contexts, such as before, during, or after a validation. 

javax.xml.validation.Validator [ Class Validator]s are not required to recognize setting any specific property names. 



Parameters 



Sets the org.w3c.dom.ls.LSResourceResolver to customize resource resolution while in a validation episode. 

javax.xml.validation.Validator [ Class Validator] uses a org.w3c.dom.ls.LSResourceResolver when it needs to locate 

external resources while a validation, although exactly what constitutes "locating external resources" is up to each 

schema language. 



class DumbLSResourceResolver implements 


public 



} 

} 


179





then the javax.xml.validation.Validator [ Class Validator] will abort the parsing and the caller of the validate 

method will receive the same java.lang.RuntimeException. When a new javax.xml.validation.Validator [ Class Valid 

ator] object is created, initially this field is set to null. 

Method validate(Source) 

public void validate(javax.xml.transform.Source source) 


See Also 


Validates the specified input. 

This is just a convenience method of: 

validate(source,null); 

Method validate(Source, Result) 

public void abstract validate(javax.xml.transform.Source source, 

javax.xml.transform.Result result) 


Parameters 

source 

result 

XML to be validated. Must not be null. 

The javax.xml.transform.Result object that receives (possibly augmented) XML. This parameter can 

be null if the caller is not interested in it. Note that when a javax.xml.transform.dom.DOMResult is set 

and a validator does not modify the infoset, the input DOM tree still have to be copied by the validator. 

Exceptions 


SAXException 

IOException 


If the javax.xml.transform.Result type doesn't match the javax.xml.transform.Source 

type, or if the specified source is neither javax.xml.transform.sax.SAXSource nor 

javax.xml.transform.dom.DOMSource. 

If the org.xml.sax.ErrorHandler throws a org.xml.sax.SAXException or if a fatal error 

is found and the org.xml.sax.ErrorHandler returns normally. 

If the validator is processing a javax.xml.transform.sax.SAXSource and the underlying 

org.xml.sax.XMLReader throws an java.io.IOException. 

If the 

source 


180




See Also 

javax.xml.validation.Validator.validate [Method validate(javax.xml.transform.Source)] 

Validates the specified input and send the augmented validation result to the specified output. 

This method places the following restrictions on the types of the javax.xml.transform.Source/ javax.xml.transform.Result 

accepted. 

javax.xml.transform.Source/javax.xml.transform.Result accepted: 

null 

javax.xml.trans 

form.stream.StreamSource 

OK 


form.sax.SAXSource 

OK 


form.dom.DOMSource 

OK 


form.stream.StreamResult 

Err 

Err 

Err 


form.sax.SAXResult 

Err 

OK 

Err 


form.dom.DOMResult 

Err 

Err 

OK 

To process javax.xml.transform.stream.StreamSource or to validate one javax.xml.transform.Source into another kind 

of javax.xml.transform.Result, use the identity transformer (see javax.xml.transform.TransformerFactory.newTrans 

former) 

Errors found during the validation is sent to the specified org.xml.sax.ErrorHandler. 

If a document is valid, or if a document contains some errors but none of them were fatal and the org.xml.sax.ErrorHand 

ler didn't throw any exception, then the method returns normally. 

Class ValidatorHandler 

Streaming validator that works on SAX stream. 

A javax.xml.validation.ValidatorHandler [ Class ValidatorHandler] object is a thread-unsafe, non-reentrant object. In 

other words, it is applications' responsibility to make sure that one javax.xml.validation.ValidatorHandler [ Class 

ValidatorHandler] object is not used from more than one thread at any given time. 

javax.xml.validation.ValidatorHandler [ Class ValidatorHandler] checks if the SAX events follow the set of constraints 

described in the associated javax.xml.validation.Schema [ Class Schema], and additionally it may modifies the SAX 

events (for example by adding default values, etc.) 

javax.xml.validation.ValidatorHandler [ Class ValidatorHandler] extends from org.xml.sax.ContentHandler, but it 

refines the underlying org.xml.sax.ContentHandler in the following way: 

1. startElement/endElement events must receive non-null String for uri, localName, and qname, even though 

SAX allows some of them to be null. Similarly, the user-specified callback will receive non-null Strings for all 

three parameters. 

2. Applications must ensure that javax.xml.validation.ValidatorHandler [ Class ValidatorHandler]'s 

org.xml.sax.ContentHandler.startPrefixMapping and org.xml.sax.ContentHandler.endPrefixMapping are invoked 

properly. 

181




3. org.xml.sax.Attributes for the org.xml.sax.ContentHandler.startElement method may or may not include xmlns* 

attributes. 

A javax.xml.validation.ValidatorHandler [ Class ValidatorHandler] is automatically reset every time the startDocument 

method is invoked. 

Recognized Properties and Features 

This spec defines the following feature that must be recognized by all javax.xml.validation.ValidatorHandler [ Class 

ValidatorHandler] implementations. 

http://xml.org/sax/features/namespace-prefixes 

Synopsis 

This feature controls how a javax.xml.validation.ValidatorHandler [ Class ValidatorHandler] introduces namespace 

bindings that were not present in the original SAX event stream. When a new namespace binding is introduced by a 

javax.xml.validation.ValidatorHandler [ Class ValidatorHandler], it must invoke org.xml.sax.ContentHandler.startPre 

fixMapping and org.xml.sax.ContentHandler.endPrefixMapping methods of the org.xml.sax.ContentHandler specified 

by the user. Additionally, when this feature is set to true, it must also make sure that the user's org.xml.sax.ContentHand 

ler will see the corresponding xmlns* attribute in the org.xml.sax.Attributes object of the org.xml.sax.ContentHand 

ler.startElement callback. 

Note that this feature does NOT affect the way a javax.xml.validation.ValidatorHandler [ Class ValidatorHandler] receives 

SAX events. It merely changes the way it augments SAX events. 

This feature is set to false by default. 

public ValidatorHandlerimplements ContentHandler { 

protected ValidatorHandler(); 

public void abstract setContentHandler(org.xml.sax.ContentHandler receiver); 

public ContentHandler abstract getContentHandler(); 

public boolean abstract isValidSoFar(); 





public TypeInfoProvider abstract getTypeInfoProvider(); 






182









} 

Author 



Since 1.5 



| 

javax.xml.validation.ValidatorHandler 

Members 

Constructor ValidatorHandler() 

protected ValidatorHandler(); 



Derived classes should create javax.xml.validation.ValidatorHandler [ Class ValidatorHandler] objects that have 

null 

org.xml.sax.ErrorHandler and 

null 

org.w3c.dom.ls.LSResourceResolver. 

Method getContentHandler() 

public ContentHandler abstract getContentHandler(); 

See Also javax.xml.validation.ValidatorHandler.setContentHandler [Method setContentHand 

ler(org.xml.sax.ContentHandler)] 

Gets the org.xml.sax.ContentHandler which receives the augmented validation result. 

183






See Also 

javax.xml.validation.ValidatorHandler.setErrorHandler [Method setErrorHandler(org.xml.sax.Er 

rorHandler)] 

Gets the current org.xml.sax.ErrorHandler set to this javax.xml.validation.ValidatorHandler [ Class ValidatorHandler]. 




Parameters 

name 

returns 



Exceptions 







When the javax.xml.validation.ValidatorHandler [ Class ValidatorHandler] recognizes 

the feature name but cannot determine its value at this time. 


See Also 

javax.xml.validation.ValidatorHandler.setFeature [Method setFeature(java.lang.String, boolean)] 


The feature name is any fully-qualified URI. It is possible for a javax.xml.validation.ValidatorHandler [ Class Valid 

atorHandler] to recognize a feature name but temporarily be unable to return its value. Some feature values may be 

available only in specific contexts, such as before, during, or after a validation. 





Parameters 

name 

returns 



Exceptions 




184








this time. 


See Also javax.xml.validation.ValidatorHandler.setProperty [Method setProperty(java.lang.String, 

java.lang.Object)] 


The property name is any fully-qualified URI. It is possible for a javax.xml.validation.ValidatorHandler [ Class Valid 

atorHandler] to recognize a property name but temporarily be unable to return its value. Some property values may be 

available only in specific contexts, such as before, during, or after a validation. 

javax.xml.validation.ValidatorHandler [ Class ValidatorHandler]s are not required to recognize any specific property 

names. 




See Also 

javax.xml.validation.ValidatorHandler.setErrorHandler [Method setErrorHandler(org.xml.sax.Er 

rorHandler)] 

Gets the current org.w3c.dom.ls.LSResourceResolver set to this javax.xml.validation.ValidatorHandler [ Class Valid 

atorHandler]. 

Method getTypeInfoProvider() 

public TypeInfoProvider abstract getTypeInfoProvider(); 

Obtains the javax.xml.validation.TypeInfoProvider [ Class TypeInfoProvider] implementation of this javax.xml.valid 

ation.ValidatorHandler [ Class ValidatorHandler]. 

The obtained javax.xml.validation.TypeInfoProvider [ Class TypeInfoProvider] can be queried during a parse to access 

the type information determined by the validator. 

Some schema languages do not define the notion of type, for those languages, this method may not be supported. 

However, to be compliant with this specification, implementations for W3C XML Schema 1.0 and XML 1.0 DTD 

must support this operation. 

Method isValidSoFar() 

public boolean abstract isValidSoFar(); 

Returns true if the validator found no error up to this point. 

More precisely, this method returns true if and only if no error is found in the document since the last startDocument 

event was received. 

Method setContentHandler(ContentHandler) 

public void abstract setContentHandler(org.xml.sax.ContentHandler receiver); 

185




Parameters 

receiver 

A org.xml.sax.ContentHandler or a null value. 

Sets the org.xml.sax.ContentHandler which receives the augmented validation result. 

When a org.xml.sax.ContentHandler is specified, a javax.xml.validation.ValidatorHandler [ Class ValidatorHandler] 

will work as a filter and basically copy the incoming events to the specified org.xml.sax.ContentHandler. 

In doing so, a javax.xml.validation.ValidatorHandler [ Class ValidatorHandler] may modify the events, for example 

by adding defaulted attributes. 

A javax.xml.validation.ValidatorHandler [ Class ValidatorHandler] may buffer events to certain extent, but to allow 

javax.xml.validation.ValidatorHandler [ Class ValidatorHandler] to be used by a parser, the following requirement 

has to be met. 

1. When org.xml.sax.ContentHandler.startElement, org.xml.sax.ContentHandler.endElement, org.xml.sax.Con 

tentHandler.startDocument, or org.xml.sax.ContentHandler.endDocument are invoked on a javax.xml.valida 

tion.ValidatorHandler [ Class ValidatorHandler], the same method on the user-specified org.xml.sax.ContentHandler 

must be invoked for the same event before the callback returns. 

2. javax.xml.validation.ValidatorHandler [ Class ValidatorHandler] may not introduce new elements that were not 

present in the input. 

3. javax.xml.validation.ValidatorHandler [ Class ValidatorHandler] may not remove attributes that were present in 

the input. 

4. If javax.xml.validation.ValidatorHandler [ Class ValidatorHandler] determines that certain characters are "ignorable 

whitespace", it should invoke the org.xml.sax.ContentHandler.ignorableWhitespace callback instead of the 

org.xml.sax.ContentHandler.characters callback. This is necessary for a javax.xml.parsers.DocumentBuilder to 

properly implement org.w3c.dom.Text.isElementContentWhitespace. 

When a callback method on the specified org.xml.sax.ContentHandler throws an exception, the same exception object 

must be thrown from the javax.xml.validation.ValidatorHandler [ Class ValidatorHandler]. The org.xml.sax.ErrorHandler 

should not be notified of such an exception. 

This method can be called even during a middle of a validation. 



Parameters 

errorHandler 


Sets the org.xml.sax.ErrorHandler to receive errors encountered during the validation. 

Error handler can be used to customize the error handling process during a validation. When an org.xml.sax.ErrorHandler 

is set, errors found during the validation will be first sent to the org.xml.sax.ErrorHandler. 

The error handler can abort further validation immediately by throwing org.xml.sax.SAXException from the handler. 

Or for example it can print an error to the screen and try to continue the validation by returning normally from the 

org.xml.sax.ErrorHandler 

186




If any java.lang.Throwable is thrown from an org.xml.sax.ErrorHandler, the same java.lang.Throwable object will 

be thrown toward the root of the call stack. 

javax.xml.validation.ValidatorHandler [ Class ValidatorHandler] is not allowed to throw org.xml.sax.SAXException 

without first reporting it to org.xml.sax.ErrorHandler. 


is set: 






throw e; 

} 




throw e; 

} 




// noop 

} 

} 

When a new javax.xml.validation.ValidatorHandler [ Class ValidatorHandler] object is created, initially this field is 

set to null. 





Parameters 

name 

value 



Exceptions 







the feature name but cannot set the requested value. 

187






See Also 

javax.xml.validation.ValidatorHandler.getFeature [Method getFeature(java.lang.String)] 


Feature can be used to control the way a javax.xml.validation.ValidatorHandler [ Class ValidatorHandler] parses 

schemas, although javax.xml.validation.ValidatorHandler [ Class ValidatorHandler]s are not required to recognize any 

specific property names. 

The feature name is any fully-qualified URI. It is possible for a javax.xml.validation.ValidatorHandler [ Class Valid 

atorHandler] to expose a feature value but to be unable to change the current value. Some feature values may be im 

mutable or mutable only in specific contexts, such as before, during, or after a validation. 





Parameters 

name 

object 



Exceptions 








the property name but cannot set the requested value. 



The property name is any fully-qualified URI. It is possible for a javax.xml.validation.ValidatorHandler [ Class Valid 

atorHandler] to recognize a property name but to be unable to change the current value. Some property values may be 

immutable or mutable only in specific contexts, such as before, during, or after a validation. 

javax.xml.validation.ValidatorHandler [ Class ValidatorHandler]s are not required to recognize setting any specific 

property names. 



Parameters 



Sets the org.w3c.dom.ls.LSResourceResolver to customize resource resolution while in a validation episode. 

188




javax.xml.validation.ValidatorHandler [ Class ValidatorHandler] uses a org.w3c.dom.ls.LSResourceResolver when it 

needs to locate external resources while a validation, although exactly what constitutes "locating external resources" 

is up to each schema language. 



class DumbLSResourceResolver implements 


public 



} 

} 



then the javax.xml.validation.ValidatorHandler [ Class ValidatorHandler] will abort the parsing and the caller of the 

validate method will receive the same java.lang.RuntimeException. When a new javax.xml.validation.Validat 

orHandler [ Class ValidatorHandler] object is created, initially this field is set to null. 

189



Chapter 16. Package javax.xml.datatype 

Class Duration 

Immutable representation of a time span as defined in the W3C XML Schema 1.0 specification. 

A Duration object represents a period of Gregorian time, which consists of six fields (years, months, days, hours, 

minutes, and seconds) plus a sign (+/-) field. 

The first five fields have non-negative (>=0) integers or null (which represents that the field is not set), and the seconds 

field has a non-negative decimal or null. A negative sign indicates a negative duration. 

This class provides a number of methods that make it easy to use for the duration datatype of XML Schema 1.0 with 

the errata. 

Order relationship 

Duration objects only have partial order, where two values A and B maybe either: 

1. AB (A is longer than B) 

3. A==B (A and B are of the same duration) 

4. AB (Comparison between A and B is indeterminate) 

For example, 30 days cannot be meaningfully compared to one month. The javax.xml.datatype.Duration.compare [ 

Method compare(javax.xml.datatype.Duration, javax.xml.datatype.Duration)] method implements this relationship. 

See the javax.xml.datatype.Duration.isLongerThan [ Method isLongerThan(javax.xml.datatype.Duration)] method for 

details about the order relationship among javax.xml.datatype.Duration [ Class Duration] objects. 

Operations over Duration 

This class provides a set of basic arithmetic operations, such as addition, subtraction and multiplication. Because dur 

ations don't have total order, an operation could fail for some combinations of operations. For example, you cannot 

subtract 15 days from 1 month. See the javadoc of those methods for detailed conditions where this could happen. 

Also, division of a duration by a number is not provided because the javax.xml.datatype.Duration [ Class Duration] 

class can only deal with finite precision decimal numbers. For example, one cannot represent 1 sec divided by 3. 

However, you could substitute a division by 3 with multiplying by numbers such as 0.3 or 0.333. 

Range of allowed values 

Because some operations of javax.xml.datatype.Duration [ Class Duration] rely on java.util.Calendar even though 

javax.xml.datatype.Duration [ Class Duration] can hold very large or very small values, some of the methods may not 

work correctly on such javax.xml.datatype.Duration [ Class Duration]s. The impacted methods document their depend 

ency on java.util.Calendar. 

190


Package javax.xml.datatype 


Synopsis 

public Durationimplements Serializable { 

public Duration(boolean isPositive, 

java.math.BigInteger years, 

java.math.BigInteger months, 

java.math.BigInteger days, 

java.math.BigInteger hours, 

java.math.BigInteger minutes, 

java.math.BigDecimal seconds); 


int years, 

int months, 

int days, 

int hours, 

int minutes, 

int seconds); 

public Duration(long durationInMilliSeconds); 

public Duration(java.lang.String lexicalRepresentation) 


static int compare(javax.xml.datatype.Duration lhs, 

javax.xml.datatype.Duration rhs); 

final boolean isLongerThan(javax.xml.datatype.Duration rhs); 

final boolean isShorterThan(javax.xml.datatype.Duration rhs); 

final boolean equals(java.lang.Object rhs); 

public int hashCode(); 


public boolean isSet(javax.xml.datatype.Duration.Field field); 

public Number getField(javax.xml.datatype.Duration.Field field); 

public int getYears(); 

public int getMonths(); 

public int getDays(); 

public int getHours(); 

public int getMinutes(); 

public int getSeconds(); 

final long getTimeInMillis(java.util.Calendar startInstant); 

191




final long getTimeInMillis(java.util.Date startInstant); 

public Duration normalizeWith(java.util.Calendar startTimeInstant); 

public Duration multiply(int factor); 

final Duration multiply(java.math.BigDecimal factor); 

final Duration add(javax.xml.datatype.Duration rhs); 

final Duration subtract(javax.xml.datatype.Duration rhs); 

public Duration negate(); 

public int signum(); 

public void addTo(java.util.Calendar calendar); 

public void addTo(java.util.Date date); 

} 

Author Kohsuke Kawaguchi [mailto:Kohsuke.Kawaguchi@Sun.com], Joseph Fialli 

[mailto:Joseph.Fialli@Sun.com] 


Since 1.5 

See Also 


javax.xml.datatype.XMLGregorianCalendar.add [Method add(javax.xml.datatype.Duration)] 


| 

javax.xml.datatype.Duration 

Members 

Constructor Duration(boolean, BigInteger, BigInteger, BigInteger, BigInteger, 

BigInteger, BigDecimal) 


java.math.BigInteger years, 

java.math.BigInteger months, 

java.math.BigInteger days, 

java.math.BigInteger hours, 

java.math.BigInteger minutes, 

java.math.BigDecimal seconds); 

Parameters 

isPositive 

Set to false to create a negative duration. When the length of the duration is zero, this 

parameter will be ignored. 

192




years 

months 

days 

hours 

minutes 

seconds 

Exceptions 

of this Duration 







If years, months, days, hours, minutes and seconds parameters are all null. Or if any 

of those parameters are negative. 

Constructs a new Duration object by specifying each field individually. 

All the parameters are optional as long as at least one field is present. If specified, parameters have to be zero or positive. 

Constructor Duration(boolean, int, int, int, int, int, int) 


int years, 

int months, 

int days, 

int hours, 

int minutes, 

int seconds); 

See Also 

javax.xml.datatype.Duration [Constructor Duration(boolean, java.math.BigInteger, java.math.Bi 

gInteger, java.math.BigInteger, java.math.BigInteger, java.math.BigInteger, java.math.BigDecimal)] 

Constructs a new Duration object by specifying each field individually. 

This method is functionally equivalent to invoking another constructor by wrapping all non-zero parameters into 

java.math.BigInteger and java.math.BigDecimal. Zero value of int parameter is equivalent of null value of the corres 

ponding field. 

Constructor Duration(long) 

public Duration(long durationInMilliSeconds); 

Parameters 

durationInMilliSeconds 

The length of the duration in milliseconds. 

Constructs a new Duration object by specifying the duration in milliseconds. 

The DAYS, HOURS, MINUTES and SECONDS fields are used to represent the specifed duration in a reasonable 

way. That is, the constructed object x satisfies the following conditions: 

• x.getHours()




• x.getSeconds()




Field HOURS 

Partial order relation comparison result. 

static javax.xml.datatype.Duration.Field HOURS ; 

A constant that represents the hours field. 

Field INDETERMINATE 

Field LESSER 

static int INDETERMINATE ; 

See Also javax.xml.datatype.Duration.compare [Method compare(javax.xml.datatype.Duration, 

javax.xml.datatype.Duration)] 


static int LESSER ; 




Field MINUTES 

static javax.xml.datatype.Duration.Field MINUTES ; 

A constant that represents the minutes field. 

Field MONTHS 

static javax.xml.datatype.Duration.Field MONTHS ; 

A constant that represents the months field. 

Field SECONDS 

Field YEARS 

static javax.xml.datatype.Duration.Field SECONDS ; 

A constant that represents the seconds field. 

static javax.xml.datatype.Duration.Field YEARS ; 

A constant that represents the years field. 

Method add(Duration) 

final Duration add(javax.xml.datatype.Duration rhs); 

195




Parameters 

rhs 

returns 

Exceptions 

Duration to add to this Duration 

non-null valid Duration object. 



If the rhs parameter is null. 

If two durations cannot be meaningfully added. For example, adding negative one day 

to one month causes this exception. 

See Also 

javax.xml.datatype.Duration.subtract [Method subtract(javax.xml.datatype.Duration)] 

Computes a new duration whose value is this+rhs. 

For example, 

"1 day" + "-3 days" = "-2 days" 

"1 year" + "1 day" = "1 year and 1 day" 

"-(1 hour,50 minutes)" + "-20 minutes" = "-(1 hours,70 minutes)" 

"15 hours" + "-3 days" = "-(2 days,9 hours)" 

"1 year" + "-1 day" = IllegalStateException 

Since there's no way to meaningfully subtract 1 day from 1 month, there are cases where the operation fails in 

java.lang.IllegalStateException. Formally, the computation is defined as follows. Firstly, we can assume that two 

javax.xml.datatype.Duration [ Class Duration]s to be added are both positive without losing generality (i.e., (-X)+Y=Y- 

X, X+(-Y)=X-Y, (-X)+(-Y)=-(X+Y)) Addition of two positive javax.xml.datatype.Duration [ Class Duration]s 

are simply defined as field by field addition where missing fields are treated as 0. A field of the resulting 

javax.xml.datatype.Duration [ Class Duration] will be unset if and only if respective fields of two input 

javax.xml.datatype.Duration [ Class Duration]s are unset. Note that lhs.add(rhs) will be always successful if 

lhs.signum()*rhs.signum()!=-1 or both of them are normalized. 

Method addTo(Calendar) 

public void addTo(java.util.Calendar calendar); 

Parameters 

calendar 

A calendar object whose value will be modified. 

Exceptions 


if the calendar parameter is null. 

Adds this duration to a java.util.Calendar object. 

Calls java.util.Calendar.add in the order of YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS, and MIL 

LISECONDS if those fields are present. Because the java.util.Calendar class uses int to hold values, there are cases 

where this method won't work correctly (for example if values of fields exceed the range of int.) 

196




Also, since this duration class is a Gregorian duration, this method will not work correctly if the given java.util.Calendar 

object is based on some other calendar systems. 

Any fractional parts of this javax.xml.datatype.Duration [ Class Duration] object beyond milliseconds will be simply 

ignored. For example, if this duration is "P1.23456S", then 1 is added to SECONDS, 234 is added to MILLISECONDS, 

and the rest will be unused. 

Note that because java.util.Calendar.add is using 

int 

, javax.xml.datatype.Duration [ Class Duration] with values beyond the range of 

int 

in its fields will cause overflow/underflow to the given java.util.Calendar. javax.xml.datatype.XMLGregorianCalen 

dar.add [ Method add(javax.xml.datatype.Duration)] provides the same basic operation as this method while avoiding 

the overflow/underflow issues. 

Method addTo(Date) 

public void addTo(java.util.Date date); 

Parameters 

date 

A date object whose value will be modified. 

Exceptions 


if the date parameter is null. 

Adds this duration to a java.util.Date object. 

The given date is first converted into a java.util.GregorianCalendar, then the duration is added exactly like the 

javax.xml.datatype.Duration.addTo [ Method addTo(java.util.Calendar)] method. 

The updated time instant is then converted back into a java.util.Date object and used to update the given java.util.Date 

object. 

This somewhat redundant computation is necessary to unambiguously determine the duration of months and years. 

Method compare(Duration, Duration) 

static int compare(javax.xml.datatype.Duration lhs, 

javax.xml.datatype.Duration rhs); 

Parameters 

lhs 

rhs 

instance of Duration to compare 

instance of Duration to compare 

197




returns 

the relationship between lhs and rhs as javax.xml.datatype.Duration.LESSER [ Field LESSER], 

javax.xml.datatype.Duration.EQUAL [ Field EQUAL], javax.xml.datatype.Duration.GREATER [ 

Field GREATER] or javax.xml.datatype.Duration.INDETERMINATE [ Field INDETERMINATE]. 

Exceptions 


if lhs or rhs parameters are null. 

See Also 

javax.xml.datatype.Duration.isShorterThan [Method isShorterThan(javax.xml.datatype.Duration)], 

javax.xml.datatype.Duration.isLongerThan [Method isLongerThan(javax.xml.datatype.Duration)] 

Partial order relation comparison between two Duration instances. 

Comparison result must be in accordance with W3C XML Schema 1.0 Part 2, Section 3.2.7.6.2, Order relation on 

duration [http://www.w3.org/TR/xmlschema-2/#duration-order]. 


final boolean equals(java.lang.Object rhs); 

Parameters 

rhs 

returns 

A non-null valid javax.xml.datatype.Duration [ Class Duration] object. 

true if this duration is the same length as rhs. false if rhs is not a javax.xml.datatype.Duration 

[ Class Duration] object or its length is different from this duration. 

Exceptions 


if parameter is null. 



Checks if this duration object has the same duration as another javax.xml.datatype.Duration [ Class Duration] object. 

For example, "P1D" (1 day) is equal to "PT24H" (24 hours). 

Duration X is equal to Y if and only if time instant t+X and t+Y are the same for all the test time instants specified in 

the section 3.2.6.2 of the XML Schema 1.0 specification. 

Note that there are cases where two javax.xml.datatype.Duration [ Class Duration]s are "incomparable" to each other, 

like one month and 30 days. For example, 

!new Duration("P1M").isShorterThan(new Duration("P30D")) 

!new Duration("P1M").isLongerThan(new Duration("P30D")) 

!new Duration("P1M").equals(new Duration("P30D")) 

Method getDays() 

public int getDays(); 

198




Obtains the value of the DAYS field as an integer value, or 0 if not present. This method works just like 

javax.xml.datatype.Duration.getYears [ Method getYears()] except that this method works on the DAYS field. 

Method getField(Duration.Field) 

public Number getField(javax.xml.datatype.Duration.Field field); 

Parameters 

field 

returns 

one of the six Field constants (YEARS,MONTHS,DAYS,HOURS, MINUTES, or SECONDS.) 

If the specified field is present, this method returns a non-null non-negative java.lang.Number object 

that represents its value. If it is not present, return null. For YEARS, MONTHS, DAYS, HOURS, 

and MINUTES, this method returns a java.math.BigInteger object. For SECONDS, this method returns 

a java.math.BigDecimal. 

Exceptions 


If the field parameter is null. 

Gets the value of a field. Fields of a duration object may contain arbitrary large value. Therefore this method is designed 

to return a java.lang.Number object. In case of YEARS, MONTHS, DAYS, HOURS, and MINUTES, the returned 

number will be a non-negative integer. In case of seconds, the returned number may be a non-negative decimal value. 

Method getHours() 

public int getHours(); 

Obtains the value of the HOURS field as an integer value, or 0 if not present. This method works just like 

javax.xml.datatype.Duration.getYears [ Method getYears()] except that this method works on the HOURS field. 

Method getMinutes() 

public int getMinutes(); 

Obtains the value of the MINUTES field as an integer value, or 0 if not present. This method works just like 

javax.xml.datatype.Duration.getYears [ Method getYears()] except that this method works on the MINUTES field. 

Method getMonths() 

public int getMonths(); 

Obtains the value of the MONTHS field as an integer value, or 0 if not present. This method works just like 

javax.xml.datatype.Duration.getYears [ Method getYears()] except that this method works on the MONTHS field. 

Method getSeconds() 

public int getSeconds(); 

Obtains the value of the SECONDS field as an integer value, or 0 if not present. This method works just like 

javax.xml.datatype.Duration.getYears [ Method getYears()] except that this method works on the SECONDS field. 

199




Method getTimeInMillis(Calendar) 

final long getTimeInMillis(java.util.Calendar startInstant); 

Parameters 

startInstant 

returns 

The length of a month/year varies. The startInstant is used to disambiguate this 

variance. Specifically, this method returns the difference between startInstant and 

startInstant+duration 

milliseconds between startInstant and startInstant plus this Duration 

Exceptions 


if startInstant parameter is null. 

Returns the length of the duration in milli-seconds. 

If the seconds field carries more digits than milli-second order, those will be simply discarded (or in other words, 

rounded to zero.) For example, for any Calendar value x, 

new Duration("PT10.00099S").getTimeInMills(x) == 10000. 

new Duration("-PT10.00099S").getTimeInMills(x) == -10000. 

Note that this method uses the javax.xml.datatype.Duration.addTo [ Method addTo(java.util.Calendar)] method, which 

may work incorectly with javax.xml.datatype.Duration [ Class Duration] objects with very large values in its fields. 

See the javax.xml.datatype.Duration.addTo [ Method addTo(java.util.Calendar)] method for details. 

Method getTimeInMillis(Date) 

final long getTimeInMillis(java.util.Date startInstant); 

Parameters 

startInstant 

returns 

The length of a month/year varies. The startInstant is used to disambiguate this 

variance. Specifically, this method returns the difference between startInstant and 

startInstant+duration. 

milliseconds between startInstant and startInstant plus this Duration 

Exceptions 


If the startInstant parameter is null. 

See Also 

javax.xml.datatype.Duration.getTimeInMillis [Method getTimeInMillis(java.util.Calendar)] 

Returns the length of the duration in milli-seconds. 

200




If the seconds field carries more digits than milli-second order, those will be simply discarded (or in other words, 

rounded to zero.) For example, for any Date value x, 

new Duration("PT10.00099S").getTimeInMills(x) == 10000. 

new Duration("-PT10.00099S").getTimeInMills(x) == -10000. 

Note that this method uses the javax.xml.datatype.Duration.addTo [ Method addTo(java.util.Date)] method, which 

may work incorectly with javax.xml.datatype.Duration [ Class Duration] objects with very large values in its fields. 

See the javax.xml.datatype.Duration.addTo [ Method addTo(java.util.Date)] method for details. 

Method getYears() 

public int getYears(); 

Obtains the value of the YEARS field as an integer value, or 0 if not present. 

This method is a convenience method around the javax.xml.datatype.Duration.getField [ Method getField(javax.xml.data 

type.Duration.Field)] method. 

Note that since this method returns 

int 

, this method will return an incorrect value for javax.xml.datatype.Duration [ Class Duration]s with the year field that 

goes beyond the range of 

int 

. Use getField(YEARS) to avoid possible loss of precision. 



See Also 

java.lang.Object.hashCode 

Returns a hash code consistent with the definition of the equals method. 

Method isLongerThan(Duration) 

final boolean isLongerThan(javax.xml.datatype.Duration rhs); 

Parameters 

rhs 

A non-null valid Duration instance. 

201




returns 

true if the duration represented by this object is longer than the given duration. false otherwise. 

Exceptions 


if the rhs parameter is null. 

See Also 

javax.xml.datatype.Duration.isShorterThan [Method isShorterThan(javax.xml.datatype.Duration)], 

javax.xml.datatype.Duration.compare [Method compare(javax.xml.datatype.Duration, 


Checks if this duration object is strictly longer than another javax.xml.datatype.Duration [ Class Duration] object. 

Duration X is "longer" than Y if and only if X>Y as defined in the section 3.2.6.2 of the XML Schema 1.0 specification. 

For example, "P1D" (one day) > "PT12H" (12 hours) and "P2Y" (two years) > "P23M" (23 months). 

Method isSet(Duration.Field) 

public boolean isSet(javax.xml.datatype.Duration.Field field); 

Parameters 

field 

returns 

one of the six Field constants (YEARS,MONTHS,DAYS,HOURS, MINUTES, or SECONDS.) 

true if the field is present. false if not. 

Exceptions 


If the field parameter is null. 

Checks if a field is set. A field of a duration object may or may not be present. This method can be used to test if a 

field is present. 

Method isShorterThan(Duration) 

final boolean isShorterThan(javax.xml.datatype.Duration rhs); 

Parameters 

rhs 

returns 

Duration to test this Duration against. 

true if Duration parameter is shorter than this Duration, else false. 

Exceptions 


if parameter is null. 

See Also 

javax.xml.datatype.Duration.isLongerThan [Method isLongerThan(javax.xml.datatype.Duration)], 

javax.xml.datatype.Duration.compare [Method compare(javax.xml.datatype.Duration, 


Checks if this duration object is strictly shorter than another javax.xml.datatype.Duration [ Class Duration] object. 

This method is really just a convenience method of rhs.isLongerThan(this). 

202




Method multiply(BigDecimal) 

final Duration multiply(java.math.BigDecimal factor); 

Parameters 

factor 

returns 

to multiply by 

returns a non-null valid javax.xml.datatype.Duration [ Class Duration] object 

Exceptions 



if operation produces fraction in the months field. 

if the factor parameter is null. 

Computes a new duration whose value is factor times longer than the value of this duration. 

For example, 

"P1M" (1 month) * "12" = "P12M" (12 months) 

"PT1M" (1 min) * "0.3" = "PT18S" (18 seconds) 

"P1M" (1 month) * "1.5" = IllegalStateException 

Since the javax.xml.datatype.Duration [ Class Duration] class is immutable, this method doesn't change the value of 

this object. It simply computes a new Duration object and returns it. The operation will be performed field by field 

with the precision of java.math.BigDecimal. Since all the fields except seconds are restricted to hold integers, any 

fraction produced by the computation will be carried down toward the next lower unit. For example, if you multiply 

"P1D" (1 day) with "0.5", then it will be 0.5 day, which will be carried down to "PT12H" (12 hours). When fractions 

of month cannot be meaningfully carried down to days, or year to months, this will cause an java.lang.IllegalStateEx 

ception to be thrown. For example if you multiple one month by 0.5. To avoid java.lang.IllegalStateException, use 

the javax.xml.datatype.Duration.normalizeWith [ Method normalizeWith(java.util.Calendar)] method to remove the 

years and months fields. 

Method multiply(int) 

public Duration multiply(int factor); 

Parameters 

factor 

returns 

See Also 

Factor times longer of new Duration to create. 

New Duration that is factortimes longer than this Duration. 

javax.xml.datatype.Duration.multiply [Method multiply(java.math.BigDecimal)] 

Computes a new duration whose value is factor times longer than the value of this duration. 

This method is provided for the convenience. It is functionally equivalent to the following code: 

203




multiply(new BigDecimal(String.valueOf(factor))) 

Method negate() 

public Duration negate(); 

Returns a new javax.xml.datatype.Duration [ Class Duration] object whose value is -this. 

Since the javax.xml.datatype.Duration [ Class Duration] class is immutable, this method doesn't change the value of 

this object. It simply computes a new Duration object and returns it. 

Method normalizeWith(Calendar) 

public Duration normalizeWith(java.util.Calendar startTimeInstant); 

Parameters 

startTimeInstant 

returns 

Calendar reference point. 

Duration of years and months of this Duration as days. 

Exceptions 


If the startTimeInstant parameter is null. 

Converts the years and months fields into the days field by using a specific time instant as the reference point. 

For example, duration of one month normalizes to 31 days given the start time instance "July 8th 2003, 17:40:32". 

Formally, the computation is done as follows: 

1. The given Calendar object is cloned. 

2. The years, months and days fields will be added to the java.util.Calendar object by using the java.util.Calendar.add 

method. 

3. The difference between two Calendars are computed in terms of days. 

4. The computed days, along with the hours, minutes and seconds fields of this duration object is used to construct 

a new Duration object. 

Note that since the Calendar class uses int to hold the value of year and month, this method may produce an unexpected 

result if this duration object holds a very large value in the years or months fields. 

Method signum() 

public int signum(); 

Returns the sign of this duration in -1,0, or 1. 

204




Method subtract(Duration) 

final Duration subtract(javax.xml.datatype.Duration rhs); 

Parameters 

rhs 

returns 

Duration to substract from this Duration. 

New Duration created from subtracting rhs from this Duration. 

Exceptions 



If two durations cannot be meaningfully subtracted. For example, subtracting one day 

from one month causes this exception. 

If the rhs parameter is null. 

See Also 

javax.xml.datatype.Duration.add [Method add(javax.xml.datatype.Duration)] 

Computes a new duration whose value is this-rhs. 

For example: 

"1 day" - "-3 days" = "4 days" 

"1 year" - "1 day" = IllegalStateException 

"-(1 hour,50 minutes)" - "-20 minutes" = "-(1hours,30 minutes)" 

"15 hours" - "-3 days" = "3 days and 15 hours" 

"1 year" - "-1 day" = "1 year and 1 day" 

Since there's no way to meaningfully subtract 1 day from 1 month, there are cases where the operation fails in 

java.lang.IllegalStateException.Formally the computation is defined as follows. First, we can assume that two 

javax.xml.datatype.Duration [ Class Duration]s are both positive without losing generality. (i.e., (-X)-Y=-(X+Y), 

X-(-Y)=X+Y, (-X)-(-Y)=-(X-Y))Then two durations are subtracted field by field. If the sign of any non-zero 

field 

F 

is different from the sign of the most significant field, 1 (if 

F 

is negative) or -1 (otherwise) will be borrowed from the next bigger unit of 

F 

205




.This process is repeated until all the non-zero fields have the same sign.If a borrow occurs in the days field (in other 

words, if the computation needs to borrow 1 or -1 month to compensate days), then the computation fails by throwing 

an java.lang.IllegalStateException. 



Returns a string representation of this duration object. 

The result is formatter according to the XML Schema 1.0 spec and can be always parsed back later into the equivalent 

duration object by the javax.xml.datatype.Duration [ Constructor Duration(java.lang.String)] constructor. 

Formally, the following holds for any javax.xml.datatype.Duration [ Class Duration] object x. 

new Duration(x.toString()).equals(x) 

Class Duration.Field 

Synopsis 

Type-safe enum class that represents six fields of the javax.xml.datatype.Duration [ Class Duration] class. 

static Duration.Field { 


} 



| 

javax.xml.datatype.Duration.Field 

Members 



Returns a field name in English. This method is intended to be used for debugging/diagnosis and not for display to 

end-users. 

Class XMLGregorianCalendar 

Representation for W3C XML Schema 1.0 date/time datatypes. Specifically, these date/time datatypes are dateTime 

[#DATETIME], time [#TIME], date [#DATE], gYearMonth [#GYEARMONTH], gMonthDay 

206




[#GMONTHDAY], gYear [#GYEAR] gMonth [#GMONTH] and gDay [#GDAY] defined in the XML Namespace 

"http://www.w3.org/2001/XMLSchema". These datatypes are normatively defined in W3C XML Schema 

1.0 Part 2, Section 3.2.7-14 [http://www.w3.org/TR/xmlschema-2/#dateTime]. 

The table below defines the mapping between XML Schema 1.0 date/time datatype fields and this class' fields. It also 

summarizes the value constraints for the date and time fields defined in W3C XML Schema 1.0 Part 2, Appendix D, 

ISO 8601 Date and Time Formats [http://www.w3.org/TR/xmlschema-2/#isoformats]. 

Date/time datatype field mapping between XML Schema 1.0 and Java representation 

XML Schema 1.0 datatype 

field 

RelatedXMLGregorianCalen 

darAccessor(s) 

Value Range 

year 

month 

day 

hour 

javax.xml.datatype.XML getYear() is a value 

GregorianCalendar.getYear between -(10^9-1) to (10^9)- 

[Method getYear()] + 1 or javax.xml.datatype.XM 

javax.xml.datatype.XML LGregorianCalen 

GregorianCalendar.getEon dar.FIELD_UNDEFINED 

[Method getEon()] or [Field FIELD_UN 

javax.xml.datatype.XML DEFINED].javax.xml.data 

GregorianCalen type.XMLGregorianCalen 

dar.getEonAndYear [Method dar.getEon [Method 

getEonAndYear()] getEon()] is high order year 

value in billion of 

years.getEon() has values 

greater than or equal to 

(10^9) or less than or equal 

to -(10^9). A value of null 

indicates field is undefined. 

javax.xml.datatype.XML 

GregorianCalendar.getMonth 

[Method getMonth()] 


GregorianCalendar.getDay 

[Method getDay()] 


GregorianCalendar.getHour 

[Method getHour()] 

1 to 12 or javax.xml.data 

type.XMLGregorianCalen 

dar.FIELD_UNDEFINED 

[Field FIELD_UN 

DEFINED] 

Independent of month, max 

range is 1 to 31 or 


GregorianCalen 



DEFINED]. The normative 

value constraint stated relat 

ive to month field's value is 

in W3C XML Schema 1.0 

Part 2, Appendix D 

[htp:/www.w3.org/TR/xmlschema-2/#isoformats]. 





DEFINED] 

207




Date/time datatype field mapping between XML Schema 1.0 and Java representation 

minute 


GregorianCalendar.get 

Minute [Method get 

Minute()] 





DEFINED] 

second 





Second [Method get Second [Method get 

Second()] + javax.xml.data Second()] from 0 to 60 or 

type.XMLGregorianCalen javax.xml.datatype.XML 

dar.getMillisecond [Method GregorianCalen 

getMillisecond()]/1000 or dar.FIELD_UNDEFINED 

javax.xml.datatype.XML [Field FIELD_UN 

GregorianCalendar.get DEFINED].(Note: 60 only 

Second [Method get allowable for leap 

Second()] + javax.xml.data second.)javax.xml.data 

type.XMLGregorianCalen type.XMLGregorianCalen 

dar.getFractionalSecond dar.getMillisecond [Method 

[Method getFraction getMillisecond()] allows 

alSecond()] 

only for millisecond preci 

sion, is optional and has a 

value of javax.xml.data 




DEFINED] when it is un 

defined.javax.xml.data 


dar.getFractionalSecond 

[Method getFraction 

alSecond()] allows for infin 

ite precision over the range 

from 0.0 to 1.0.Fraction 

alSecond is optional and 

has a value of null when it 

is undefined. 

timezone 



Timezone [Method get 

Timezone()] 

Number of minutes or 





DEFINED]. Value range 

from -14 hours (-14 * 60 

minutes) to 14 hours (14 * 

60 minutes) exclusive. 

All maximum value space constraints listed for the fields in the table above are checked by factory methods, setter 

methods and parse methods of this class. IllegalArgumentException is thrown when parameter's value is 

outside the maximum value constraint for the field. Validation checks, for example, whether days in month should be 

208




Synopsis 

limited to 29, 30 or 31 days, that are dependent on the values of other fields are not checked by these methods. The 

following operations are defined for this class: 

• factory methods to create instances 

• accessors/mutators for independent date/time fields 

• conversion between this class and W3C XML Schema 1.0 lexical representation 

• conversion between this class and java.util.GregorianCalendar 

• partial order relation comparator method, javax.xml.datatype.XMLGregorianCalendar.compare [ Method com 

pare(javax.xml.datatype.XMLGregorianCalendar, javax.xml.datatype.XMLGregorianCalendar)] 

• javax.xml.datatype.XMLGregorianCalendar.equals [ Method equals(java.lang.Object)] defined relative to 

javax.xml.datatype.XMLGregorianCalendar.compare [ Method compare(javax.xml.datatype.XMLGregorianCal 

endar, javax.xml.datatype.XMLGregorianCalendar)]. 

• addition operation with javax.xml.datatype.Duration [ Class Duration]. instance as defined in W3C XML Schema 

1.0 Part 2, Appendix E, Adding durations to dateTimes 

[http://www.w3.org/TR/xmlschema-2/#adding-durations-to-dateTimes]. 

public XMLGregorianCalendarimplements Serializable, Cloneable { 

public XMLGregorianCalendar(); 

static XMLGregorianCalendar createDateTime(java.math.BigInteger year, 

int month, 

int day, 

int hours, 

int minutes, 

int seconds, 

java.math.BigDecimal fractionalSecond, 

int timezone); 

static XMLGregorianCalendar createDateTime(int year, 

int month, 

int day, 

int hour, 

int minute, 

int second); 


int month, 

int day, 

int hours, 

int minutes, 

int seconds, 

int milliseconds, 


static XMLGregorianCalendar createDate(int year, 

int month, 

209




int day, 


static XMLGregorianCalendar createTime(int hours, 

int minutes, 

int seconds, 



int minutes, 

int seconds, 




int minutes, 

int seconds, 



public BigInteger getEon(); 

public int getYear(); 

public BigInteger getEonAndYear(); 

public int getMonth(); 

public int getDay(); 

public int getTimezone(); 

public int getHour(); 

public int getMinute(); 

public int getSecond(); 

public int getMillisecond(); 

public BigDecimal getFractionalSecond(); 

public void setYear(java.math.BigInteger year); 

public void setYear(int year); 

public void setMonth(int month); 

public void setDay(int day); 

public void setTimezone(int offset); 

public void setTime(int hour, 

int minute, 

int second); 

210





int minute, 

int second, 

java.math.BigDecimal fractional); 


int minute, 

int second, 

int millisecond); 

static int compare(javax.xml.datatype.XMLGregorianCalendar lhs, 

javax.xml.datatype.XMLGregorianCalendar rhs); 

public boolean equals(java.lang.Object obj); 


static XMLGregorianCalendar parse(java.lang.String lexicalRepresentation); 

public String toXMLFormat(); 

public QName getXMLSchemaType(); 

public boolean isValid(); 

public void add(javax.xml.datatype.Duration duration); 

public GregorianCalendar toGregorianCalendar(); 

public GregorianCalendar toGregorianCalendar(java.util.TimeZone timezone, 

java.util.Locale aLocale, 

javax.xml.datatype.XMLGregorianCalendar defa 

static XMLGregorianCalendar fromGregorianCalendar(java.util.GregorianCalendar cal); 

public Object clone(); 

public void clear(); 

} 

Author Kohsuke Kawaguchi [mailto:Kohsuke.Kawaguchi@Sun.com], Joseph Fialli 

[mailto:Joseph.Fialli@Sun.com] 


Since 1.5 

See Also 


javax.xml.datatype.Duration [Class Duration] 


| 

javax.xml.datatype.XMLGregorianCalendar 

211




Members 

Constructor XMLGregorianCalendar() 

Field APRIL 

public XMLGregorianCalendar(); 

Create an instance with all date/time datatype fields set to javax.xml.datatype.XMLGregorianCalendar.FIELD_UN 

DEFINED [ Field FIELD_UNDEFINED] or null respectively. 

static int APRIL ; 

See Also 

javax.xml.datatype.XMLGregorianCalendar.getMonth [Method getMonth()], javax.xml.data 

type.XMLGregorianCalendar.setMonth [Method setMonth(int)] 

Value for fourth month of year. 

Field AUGUST 

static int AUGUST ; 

See Also 



Field DATE 

Value for eighth month of year. 

static javax.xml.namespace.QName DATE ; 

Fully qualified name for W3C XML Schema 1.0 datatype date. 

Field DATETIME 

static javax.xml.namespace.QName DATETIME ; 

Fully qualified name for W3C XML Schema 1.0 datatype dateTime. 

Field DECEMBER 

static int DECEMBER ; 

See Also 



Field EQUAL 

Value for twelve month of year. 

static int EQUAL ; 

See Also 

javax.xml.datatype.XMLGregorianCalendar.compare [Method compare(javax.xml.datatype.XM 

LGregorianCalendar, javax.xml.datatype.XMLGregorianCalendar)] 

212





Field FEBRUARY 

static int FEBRUARY ; 

See Also 



Value for second month of year. 

Field FIELD_UNDEFINED 

Field GDAY 

static int FIELD_UNDEFINED ; 

Designation that an "int" field is not set. 

static javax.xml.namespace.QName GDAY ; 

Fully qualified name for W3C XML Schema 1.0 datatype gDay. 

Field GMONTH 

static javax.xml.namespace.QName GMONTH ; 

Fully qualified name for W3C XML Schema 1.0 datatype gMonth. 

Field GMONTHDAY 

static javax.xml.namespace.QName GMONTHDAY ; 

Fully qualified name for W3C XML Schema 1.0 datatype gMonthDay. 

Field GREATER 

static int GREATER ; 

See Also 



Field GYEAR 


static javax.xml.namespace.QName GYEAR ; 

Fully qualified name for W3C XML Schema 1.0 datatype gYear. 

Field GYEARMONTH 

static javax.xml.namespace.QName GYEARMONTH ; 

213




Fully qualified name for W3C XML Schema 1.0 datatype gYearMonth. 

Field INDETERMINATE 

static int INDETERMINATE ; 

See Also 




Field JANUARY 

static int JANUARY ; 

See Also 



Field JULY 

Value for first month of year. 

static int JULY ; 

See Also 



Field JUNE 

Value for seventh month of year. 

static int JUNE ; 

See Also 



Value for sixth month of year. 

Field LEAP_YEAR_DEFAULT 

static javax.xml.datatype.XMLGregorianCalendar LEAP_YEAR_DEFAULT ; 

See Also 

javax.xml.datatype.XMLGregorianCalendar.toGregorianCalendar [Method toGregorianCalen 

dar(java.util.TimeZone, java.util.Locale, javax.xml.datatype.XMLGregorianCalendar)] 

Use as a template for default field values when converting to a java.util.GregorianCalendar, set to a leap 

year date of January 1, 0400 at midnight. 

Field LESSER 

static int LESSER ; 

See Also 



214




Field MARCH 


static int MARCH ; 

See Also 



Field MAY 

Value for third month of year. 

static int MAY ; 

See Also 



Value for fifth month of year. 

Field NOVEMBER 

static int NOVEMBER ; 

See Also 



Value for eleven month of year. 

Field OCTOBER 

static int OCTOBER ; 

See Also 



Value for tenth month of year. 

Field SEPTEMBER 

static int SEPTEMBER ; 

See Also 



Field TIME 

Value for ninth month of year. 

static javax.xml.namespace.QName TIME ; 

Fully qualified name for W3C XML Schema 1.0 datatype time. 

215




Method add(Duration) 

public void add(javax.xml.datatype.Duration duration); 

Parameters 

duration 

Duration to add to this XMLGregorianCalendar. 

Exceptions 


when duration parameter is null. 

Add duration to this instance. 

The computation is specified in XML Schema 1.0 Part 2, Appendix E, Adding durations to dateTimes> 

[http://www.w3.org/TR/xmlschema-2/#adding-durations-to-dateTimes]. date/time field mapping table 

[#datetimefieldsmapping] defines the mapping from XML Schema 1.0 dateTime fields to this class' representation 

of those fields. 

Method clear() 

public void clear(); 

Unset all fields to undefined. 

Set all int fields to javax.xml.datatype.XMLGregorianCalendar.FIELD_UNDEFINED [ Field FIELD_UNDEFINED] 

and reference fields to null. 

Method clone() 

public Object clone(); 

Creates and returns a copy of this object. 

Method compare(XMLGregorianCalendar, XMLGregorianCalendar) 

static int compare(javax.xml.datatype.XMLGregorianCalendar lhs, 

javax.xml.datatype.XMLGregorianCalendar rhs); 

Parameters 

lhs 

rhs 

instance of XMLGregorianCalendar to compare 

instance of XMLGregorianCalendar to compare 

returns the relationship between lhs and rhs as javax.xml.datatype.XMLGregorianCalendar.LESSER [ 

Field LESSER], javax.xml.datatype.XMLGregorianCalendar.EQUAL [ Field EQUAL], 

javax.xml.datatype.XMLGregorianCalendar.GREATER [ Field GREATER] or javax.xml.datatype.XM 

LGregorianCalendar.INDETERMINATE [ Field INDETERMINATE]. 

Exceptions 


if lhs or rhs parameters are null. 

216




Compare two instances of W3C XML Schema 1.0 date/time datatypes according to partial order relation defined in 

W3C XML Schema 1.0 Part 2, Section 3.2.7.3, Order relation on dateTime 

[http://www.w3.org/TR/xmlschema-2/#dateTime-order]. 

xsd:dateTime datatype field mapping to accessors of this class are defined in date/time field mapping table 

[#datetimefieldmapping]. 

Method createDate(int, int, int, int) 

static XMLGregorianCalendar createDate(int year, 

int month, 

int day, 


Parameters 

year 

month 

day 

timezone 

returns 

of XMLGregorianCalendar to be created. 



offset in minutes. javax.xml.datatype.XMLGregorianCalendar.FIELD_UNDEFINED [ Field 

FIELD_UNDEFINED] indicates optional field is not set. 

XMLGregorianCalendar created from parameter values. 

Exceptions 


if any parameter is outside value constraints for the field as specified in date/time field 

mapping table [#datetimefieldmapping]. 

See Also 

javax.xml.datatype.XMLGregorianCalendar.FIELD_UNDEFINED [Field FIELD_UNDEFINED] 

Create a Java representation of XML Schema builtin datatype date or g*. 

For example, an instance of gYear can be created invoking this factory with month and day parameters set to 

javax.xml.datatype.XMLGregorianCalendar.FIELD_UNDEFINED [ Field FIELD_UNDEFINED]. 

Method createDateTime(BigInteger, int, int, int, int, int, BigDecimal, int) 

static XMLGregorianCalendar createDateTime(java.math.BigInteger year, 

int month, 

int day, 

int hours, 

int minutes, 

int seconds, 



Parameters 

year 

month 

represents both high-order eons and low-order year. 

of dateTime 

217




day 

hours 

minutes 

seconds 

fractionalSecond 

of dateTime 

of dateTime 

of dateTime 

of dateTime 

value of null indicates optional field is absent. 

timezone offset in minutes. javax.xml.datatype.XMLGregorianCalendar.FIELD_UNDEFINED [ 

Field FIELD_UNDEFINED] indicates optional field is not set. 

returns 


Exceptions 




See Also 


Create a Java representation of XML Schema builtin datatype dateTime. All possible fields are specified for this 

factory method. 

Method createDateTime(int, int, int, int, int, int) 


int month, 

int day, 

int hour, 

int minute, 

int second); 

Parameters 

year 

month 

day 

hour 

minute 

second 

returns 

represents both high-order eons and low-order year. 

of dateTime 

of dateTime 

of dateTime 

of dateTime 

of dateTime 


Exceptions 




See Also 


218




Create a Java instance of XML Schema builtin datatype dateTime. 

Method createDateTime(int, int, int, int, int, int, int, int) 


int month, 

int day, 

int hours, 

int minutes, 

int seconds, 



Parameters 

year 

month 

day 

hours 

minutes 

seconds 

represents low-order year. 

of dateTime 

of dateTime 

of dateTime 

of dateTime 

of dateTime 

milliseconds of dateTime. javax.xml.datatype.XMLGregorianCalendar.FIELD_UNDEFINED [ 




returns 


Exceptions 




See Also 


Create a Java representation of XML Schema builtin datatype dateTime. All possible fields are specified for this 

factory method. 

Method createTime(int, int, int, BigDecimal, int) 


int minutes, 

int seconds, 



219




Parameters 

hours 

minutes 

seconds 

fractionalSecond 

number of hours 

number of minutes 

number of seconds 

value of null indicates that this optional field is not set. 



returns 


Exceptions 




See Also 


Create a Java instance of XML Schema builtin datatype time. 

Method createTime(int, int, int, int) 


int minutes, 

int seconds, 


Parameters 

hours 

minutes 

seconds 

timezone 

returns 




offset in minutes. javax.xml.datatype.XMLGregorianCalendar.FIELD_UNDEFINED [ Field 

FIELD_UNDEFINED] indicates optional field is not set. 


Exceptions 




See Also 



220




Method createTime(int, int, int, int, int) 


int minutes, 

int seconds, 



Parameters 

hours 

minutes 

seconds 

milliseconds 




number of milliseconds 



returns 


Exceptions 




See Also 




public boolean equals(java.lang.Object obj); 

Parameters 

obj 

returns 

to compare. 

true when compare(this,(XMLGregorianCalendar)obj) == EQUAL.. 

Indicates whether parameter obj is "equal to" this one. 

Method fromGregorianCalendar(GregorianCalendar) 

static XMLGregorianCalendar fromGregorianCalendar(java.util.GregorianCalendar cal); 

Parameters 

cal 

returns 

java.util.GregorianCalendar used to create XMLGregorianCalendar 

XMLGregorianCalendar created from java.util.GregorianCalendar 

Convert a java.util.GregorianCalendar to XML Schema 1.0 representation. 

221




Field by Field Conversion from java.util.GregorianCalendar to 

this class 


GregorianCalendar field 

javax.xml.datatype.XMLGregorianCal 

endar.setYear [Method setYear(int)] 


endar.setMonth [Method set 

Month(int)] 


endar.setDay [Method setDay(int)] 


endar.setTime [Method setTime(int, 

int, int, java.math.BigDecimal)] 


endar.setTimezone [Method set 

Timezone(int)]* 

java.util.GregorianCalen 

dar field 

ERA == GregorianCalen 

dar.BC ? -YEAR : YEAR 

MONTH + 1 

DAY_OF_MONTH 

HOUR_OF_DAY, MINUTE, 

SECOND, MILLISECOND 

(ZONE_OFFSET + DST_OFFSET) 

/ (60*1000)(in minutes) 

*conversion loss of information. It is not possible to represent a java.util.GregorianCalendar daylight 

savings timezone id in the XML Schema 1.0 date/time datatype representation. 

Method getDay() 

public int getDay(); 

See Also 

javax.xml.datatype.XMLGregorianCalendar.setDay [Method setDay(int)] 

Return day in month or javax.xml.datatype.XMLGregorianCalendar.FIELD_UNDEFINED [ Field FIELD_UN 

DEFINED]. 

Value constraints for this value are summarized in day field of date/time field mapping table [#datetimefield-day]. 

Method getEon() 

public BigInteger getEon(); 

See Also 

javax.xml.datatype.XMLGregorianCalendar.getYear [Method getYear()], javax.xml.datatype.XM 

LGregorianCalendar.getEonAndYear [Method getEonAndYear()] 

Get the eons of the year. null if this optional part of the year field is not defined. 

Value constraints for this value are summarized in year field of date/time field mapping table [#datetimefield-year]. 

Method getEonAndYear() 

public BigInteger getEonAndYear(); 

See Also 

javax.xml.datatype.XMLGregorianCalendar.getEon [Method getEon()], javax.xml.datatype.XM 

LGregorianCalendar.getYear [Method getYear()] 

Return XML Schema 1.0 dateTime datatype field for year. 

222





Method getFractionalSecond() 

public BigDecimal getFractionalSecond(); 

See Also 

javax.xml.datatype.XMLGregorianCalendar.getSecond [Method getSecond()], javax.xml.data 

type.XMLGregorianCalendar.setTime [Method setTime(int, int, int, java.math.BigDecimal)] 

Return fractional seconds. 

null is returned when this optional field is not defined. 

Value constraints are detailed in second field of date/time field mapping table [#datetimefield-second]. 

Method getHour() 

public int getHour(); 

See Also 

javax.xml.datatype.XMLGregorianCalendar.setTime [Method setTime(int, int, int)] 

Return hours or javax.xml.datatype.XMLGregorianCalendar.FIELD_UNDEFINED [ Field FIELD_UNDEFINED]. 

Returns javax.xml.datatype.XMLGregorianCalendar.FIELD_UNDEFINED [ Field FIELD_UNDEFINED] if this field 

is not defined. 

Value constraints for this value are summarized in hour field of date/time field mapping table [#datetimefield-hour]. 

Method getMillisecond() 

public int getMillisecond(); 

See Also 

javax.xml.datatype.XMLGregorianCalendar.getFractionalSecond [Method getFractionalSecond()], 


Return milliseconds or javax.xml.datatype.XMLGregorianCalendar.FIELD_UNDEFINED [ Field FIELD_UN 

DEFINED]. 



Value constraints for this value are summarized in second field of date/time field mapping table [#datetimefield-second]. 

Method getMinute() 

public int getMinute(); 

See Also 


Return minutes or javax.xml.datatype.XMLGregorianCalendar.FIELD_UNDEFINED [ Field FIELD_UN 

DEFINED]. Returns javax.xml.datatype.XMLGregorianCalendar.FIELD_UNDEFINED [ Field FIELD_UN 

DEFINED] if this field is not defined. 

Value constraints for this value are summarized in minute field of date/time field mapping table [#datetimefield-minute]. 

223




Method getMonth() 

public int getMonth(); 

Return number of month or javax.xml.datatype.XMLGregorianCalendar.FIELD_UNDEFINED [ Field FIELD_UN 

DEFINED]. 

Value constraints for this value are summarized in month field of date/time field mapping table [#datetimefield-month]. 

Method getSecond() 

public int getSecond(); 

See Also 

javax.xml.datatype.XMLGregorianCalendar.getFractionalSecond [Method getFractionalSecond()], 


Return seconds or javax.xml.datatype.XMLGregorianCalendar.FIELD_UNDEFINED [ Field FIELD_UN 

DEFINED]. 



Value constraints for this value are summarized in second field of date/time field mapping table [#datetimefield-second]. 

Method getTimezone() 

public int getTimezone(); 

See Also 

javax.xml.datatype.XMLGregorianCalendar.setTimezone [Method setTimezone(int)] 

Return timezone offset in minutes or javax.xml.datatype.XMLGregorianCalendar.FIELD_UNDEFINED [ Field 

FIELD_UNDEFINED] if this optional field is not defined. 

Value constraints for this value are summarized in timezone field of date/time field mapping table 

[#datetimefield-timezone]. 

Method getXMLSchemaType() 

public QName getXMLSchemaType(); 

Exceptions 

java.lang.IllegalStateEx 

ception 

if the combination of set fields does not match one of the eight defined XML Schema 

builtin date/time datatypes. 

Return the name of the XML Schema date/time type that this instance maps to. Type is computed based on fields that 

are set. 

Required fields for XML Schema 1.0 Date/Time Datatypes.(timezone is optional for all date/time datatypes) 

Datatype 

javax.xml.data 

type.XML 


dar.DATE 

year 

X 

month 

X 

day 

X 

hour 

X 

minute 

X 

second 

X 

224




TIME [Field 

DATETIME] 

Required fields for XML Schema 1.0 Date/Time Datatypes.(timezone is optional for all date/time datatypes) 




dar.DATE 

[Field DATE] 




dar.TIME 

[Field TIME] 




dar.GYEAR 

MONTH [Field 

GYEAR 

MONTH] 




dar.GMONTHDAY 

[ F i e l d 

GMONTHDAY] 




dar.GYEAR 

[Field GYEAR] 




dar.GMONTH 

[ F i e l d 

GMONTH] 




dar.GDAY 

[Field GDAY] 

Method getYear() 

X 

X 

X 

public int getYear(); 

X 

X 

X 

X 

X 

X 

X 

X 

X 

X 

See Also 

javax.xml.datatype.XMLGregorianCalendar.getEon [Method getEon()], javax.xml.datatype.XM 

LGregorianCalendar.getEonAndYear [Method getEonAndYear()] 

225




Return low order component XML Schema 1.0 dataTime datatype field for year or javax.xml.datatype.XMLGregori 

anCalendar.FIELD_UNDEFINED [ Field FIELD_UNDEFINED]. 




Returns a hash code consistent with the definition of the equals method. 

Method isValid() 

public boolean isValid(); 

Validate instance by getXMLSchemaType() constraints. 

Method parse(String) 

static XMLGregorianCalendar parse(java.lang.String lexicalRepresentation); 

Parameters 

lexicalRepresentation 

returns 

Lexical representation of one the 8 XML Schema calendar datatypes. 

XMLGregorianCalendar created from parsing lexicalRepresentation 

parameter. 

Exceptions 



If the given string does not conform to the aforementioned specification. 

If the given string is null. 

Constructs a new XMLGregorianCalendar object by parsing its lexical string representation as defined in XML Schema 

1.0 Part 2, Section 3.2.[7-14].1, Lexical Representation. [http://www.w3.org/TR/xmlschema-2/#dateTime-order] 

The string representation may not have any leading and trailing whitespaces. 

The parsing is done field by field so that the following holds for any lexically correct string x: 

new XMLGregorianCalendar(x).toXMLFormat().equals(x) 

Returns a non-null valid XMLGregorianCalendar object that holds the value indicated by the lexicalRepresentation 

parameter. 

Method setDay(int) 

public void setDay(int day); 

226




Parameters 

day 

value constraints summarized in day field of date/time field mapping table [#datetimefield-day]. 

Exceptions 


if day parameter is outside value constraints for the field as specified in date/time field 


Set days in month. 

Unset this field by invoking the setter with a parameter value of javax.xml.datatype.XMLGregorianCalendar.FIELD_UN 

DEFINED [ Field FIELD_UNDEFINED]. 

Method setMonth(int) 

public void setMonth(int month); 

Parameters 

month 

value constraints summarized in month field of date/time field mapping table [#datetimefield-month]. 

Exceptions 


if month parameter is outside value constraints for the field as specified in date/time 

field mapping table [#datetimefieldmapping]. 

Set month. 



Method setTime(int, int, int) 


int minute, 

int second); 

Parameters 

hour 

minute 

second 

value constraints are summarized in hour field of date/time field mapping table [#datetimefield-hour]. 

value constraints are summarized in minute field of date/time field mapping table [#datetimefield-minute]. 

value constraints are summarized in second field of date/time field mapping table [#datetimefield-second]. 

Exceptions 




See Also javax.xml.datatype.XMLGregorianCalendar.setTime [Method setTime(int, int, int, 

java.math.BigDecimal)] 

227




Set time as one unit. 

Method setTime(int, int, int, BigDecimal) 


int minute, 

int second, 

java.math.BigDecimal fractional); 

Parameters 

hour 

minute 

second 

fractional 

value constraints are summarized in hour field of date/time field mapping table 

[#datetimefield-hour]. 

value constraints are summarized in minute field of date/time field mapping table 

[#datetimefield-minute]. 

value constraints are summarized in second field of date/time field mapping table 

[#datetimefield-second]. 

value of null indicates this optional field is not set. 

Exceptions 




Set time as one unit, including the optional infinite precison fractional seconds. 

Method setTime(int, int, int, int) 


int minute, 

int second, 

int millisecond); 

Parameters 

hour 

minute 

second 

millisecond 

value constraints are summarized in hour field of date/time field mapping table 

[#datetimefield-hour]. 

value constraints are summarized in minute field of date/time field mapping table 

[#datetimefield-minute]. 

value constraints are summarized in second field of date/time field mapping table 

[#datetimefield-second]. 

value of javax.xml.datatype.XMLGregorianCalendar.FIELD_UNDEFINED [ Field 

FIELD_UNDEFINED] indicates this optional field is not set. 

Exceptions 




228




Set time as one unit, including optional milliseconds. 

Method setTimezone(int) 

public void setTimezone(int offset); 

Parameters 

offset value constraints summarized in timezone field of date/time field mapping table 

[#datetimefield-timezone]. 

Exceptions 


if offset parameter is outside value constraints for the field as specified in date/time 

field mapping table [#datetimefieldmapping]. 

Set the number of minutes in the timezone offset. 



Method setYear(BigInteger) 

public void setYear(java.math.BigInteger year); 

Parameters 

year 

value constraints summarized in year field of date/time field mapping table [#datetimefield-year]. 

Exceptions 


if year parameter is outside value constraints for the field as specified in date/time field 


Set low and high order component of XSD dateTime year field. 

Unset this field by invoking the setter with a parameter value of null. 

Method setYear(int) 

public void setYear(int year); 

Parameters 

year 

value constraints are summarized in year field of date/time field mapping table [#datetimefield-year]. If year 

is javax.xml.datatype.XMLGregorianCalendar.FIELD_UNDEFINED [ Field FIELD_UNDEFINED], then 

eon is set to null. 

Set year of XSD dateTime year field. 



229




Method toGregorianCalendar() 

public GregorianCalendar toGregorianCalendar(); 

See Also 

javax.xml.datatype.XMLGregorianCalendar.toGregorianCalendar [Method toGregorianCalen 

dar(java.util.TimeZone, java.util.Locale, javax.xml.datatype.XMLGregorianCalendar)] 

Convert this to java.util.GregorianCalendar. 

When this instance has an undefined field, this conversion relies on the java.util.GregorianCalendar 

default for its corresponding field. A notable difference between XML Schema 1.0 date/time datatypes and 

java.util.GregorianCalendar is that Timezone value is optional for date/time datatypes and it is a required 

field for java.util.GregorianCalendar. See javadoc for java.util.TimeZone.getDefault() on 

how the default is determined. To explicitly specify the TimeZone instance, see javax.xml.datatype.XMLGregorian 

Calendar.toGregorianCalendar [ Method toGregorianCalendar(java.util.TimeZone, java.util.Locale, javax.xml.data 

type.XMLGregorianCalendar)]. 

Field by Field Conversion from this class to java.util.GregorianCal 

endar 

java.util.GregorianCalen 

dar field 

ERA 

YEAR 

MONTH 

DAY_OF_MONTH 

AM_PM 

HOUR_OF_DAY 

MINUTE 

SECOND 

MILLISECOND 


GregorianCalendar field 


endar.getEonAndYear [Method 

getEonAndYear()].signum() < 0 

? GregorianCalendar.BC : 

GregorianCalendar.AD 


endar.getEonAndYear [Method 

getEonAndYear()].abs().int 

Value()* 


endar.getMonth [Method getMonth()] 

- 1 


endar.getDay [Method getDay()] 


endar.getHour [Method getHour()]< 

12 : Calendar.AM : Calendar.PM 


endar.getHour [Method getHour()] 


endar.getMinute [Method getMinute()] 


endar.getSecond [Method getSecond()] 

get millisecond order from 


endar.getFractionalSecond [Method 

getFractionalSecond()]* 

230




Field by Field Conversion from this class to java.util.GregorianCal 

endar 

GregorianCalendar.set 

TimeZone(TimeZone) 


endar.getTimezone [Method get 

Timezone()] formatted into Custom 

timezone id 

* designates possible loss of precision during the conversion due to source datatype having higer precison than target 

datatype. 

Method toGregorianCalendar(TimeZone, Locale, XMLGregorianCalendar) 

public GregorianCalendar toGregorianCalendar(java.util.TimeZone timezone, 

java.util.Locale aLocale, 

javax.xml.datatype.XMLGregorianCalendar defa 

Parameters 

timezone 

aLocale 

defaults 

returns 

provide Timezone. null is a legal value. 

provide explicit Locale. Use default GregorianCalendar locale if value is null. 

provide default field values to use when corresponding field for this instance is FIELD_UN 

DEFINED or null. If defaultsis null or a field within the specified defaults is undefined, 

just use java.util.GregorianCalendar defaults. 

a java.util.GregorianCalendar conversion of this instance. 

See Also javax.xml.datatype.XMLGregorianCalendar.LEAP_YEAR_DEFAULT [Field 

LEAP_YEAR_DEFAULT] 

Convert this along with provided parameters to java.util.GregorianCalendar instance. 

Since XML Schema 1.0 date/time datetypes has no concept of timezone ids or daylight savings timezone ids, this 

conversion operation allows the user to explicitly specify one with timezone parameter. 

To compute the return value's TimeZone field, 

• when parameter timeZone is non-null, it is the timezone field. 

• else when this.getTimezone() != FIELD_UNDECLARED, create a java.util.TimeZone with a 

custom timezone id using the this.getTimezone(). 

• else when defaults.getTimezone() != FIELD_UNDECLARED, create a java.util.TimeZone with 

a custom timezone id using defaults.getTimezone(). 

• else use the GregorianCalendar default timezone value for the host is definedas specified by 

java.util.TimeZone.getDefault(). 

Method toXMLFormat() 

public String toXMLFormat(); 

231




Exceptions 

java.lang.IllegalStateEx 

ception 

if the combination of set fields does not match one of the eight defined XML Schema 

builtin date/time datatypes. 

Return the lexical representation of this instance. The format is specified in XML Schema 1.0 Part 2, Section 3.2.[7- 

14].1, Lexical Representation". [http://www.w3.org/TR/xmlschema-2/#dateTime-order] 

Specific target lexical representation format is determined by javax.xml.datatype.XMLGregorianCalendar.getXMLS 

chemaType [ Method getXMLSchemaType()]. 

232



Chapter 17. Package javax.xml 

Defines core XML constants and functionality from the XML specifications. 

The following core XML standards apply: 

• Extensible Markup Language (XML) 1.1 [http://www.w3.org/TR/xml11/] 

• Extensible Markup Language (XML) 1.0 (Second Edition) [http://www.w3.org/TR/REC-xml] 

• XML 1.0 Second Edition Specification Errata [http://www.w3.org/XML/xml-V10-2e-errata] 

• Namespaces in XML 1.1 [http://www.w3.org/TR/xml-names11/] 

• Namespaces in XML [http://www.w3.org/TR/REC-xml-names/#ns-qualnames] 

• Namespaces in XML Errata [http://www.w3.org/XML/xml-names-19990114-errata] 

Class AbstractVersion 

Synopsis 

AbstractVersion provides version information about the Java API for XML Processing implementation. 

public AbstractVersion { 

public AbstractVersion(); 

public String abstract getImplementationTitle(); 

public String abstract getImplementationVersion(); 

public String abstract getImplementationVendor(); 

public String abstract getImplementationVendorID(); 

public String abstract getImplementationURL(); 

} 

Author 



Since 1.5 

See Also 


javax.xml.Version [Class Version] 


| 

javax.xml.AbstractVersion 

233


Package javax.xml 


Members 

Method getImplementationTitle() 

public String abstract getImplementationTitle(); 

Get implementation title. Returns null if not available/applicable. 

Method getImplementationURL() 

public String abstract getImplementationURL(); 

Get implementation URL. 

e.g. URL with implementation details. Returns null if not available/applicable. 

Method getImplementationVendor() 

public String abstract getImplementationVendor(); 

Get implementation vendor. Returns null if not available/applicable. 

Method getImplementationVendorID() 

public String abstract getImplementationVendorID(); 

Get implementation vendor ID. e.g. com.sun Returns null if not available/applicable. 

Method getImplementationVersion() 

public String abstract getImplementationVersion(); 

Get implementation version. Returns null if not available/applicable. 

Class SecureProcessing 

Synopsis 

SecureProcessing is a final class that is used by XML processors, both parser and transformer Factories, to 

allow for secure processing of XML. 

Exploits are related to the XML processessing model and are not implementation specfic. Preventing known exploits 

include: 

• setting the maximum entity expansion limit 

• setting the maximum occurances for an Element in a W3C XML Schema declarations 

• setting the regexp limits for W3C XML Schema declarations 

• preventing the execution of arbitrary functions in a transformation 

final SecureProcessing { 

234




public SecureProcessing(); 

public SecureProcessing(int entityExpansionLimit, 

int maxOccurNodeLimit); 

public void setEntityExpansionLimit(int limit); 

public int getEntityExpansionLimit(); 

public void setMaxOccurNodeLimit(int limit); 

public int getMaxOccurNodeLimit(); 

} 

Author 

Jeff Suttor [mailto:Jeff.Suttor@Sun.com], Rajiv Mordani [mailto:Rajiv.Mordani@Sun.com] 


Since 1.5 



| 

javax.xml.SecureProcessing 

Members 

Constructor SecureProcessing() 

public SecureProcessing(); 

Default constructor that sets reasonable maximum processing values using javax.xml.SecureProcessing.DEAFULT_EN 

TITY_EXPANSION_LIMIT [ Field DEAFULT_ENTITY_EXPANSION_LIMIT] and javax.xml.SecurePro 

cessing.DEAFULT_MAXOCCUR_NODE_LIMIT [ Field DEAFULT_MAXOCCUR_NODE_LIMIT]. 

Constructor SecureProcessing(int, int) 

public SecureProcessing(int entityExpansionLimit, 

int maxOccurNodeLimit); 

Parameters 

entityExpansionLimit 

maxOccurNodeLimit 

Maximum extity expansion limit. 

Maximum W3C XML Schema declaration occurance node limit, maxOccur. 

Constructor that explicitly sets maximum processing values. 

Field DEAFULT_ENTITY_EXPANSION_LIMIT 

static int DEAFULT_ENTITY_EXPANSION_LIMIT ; 

235




Default maximum entity expansion limit is 100. 

Field DEAFULT_MAXOCCUR_NODE_LIMIT 

static int DEAFULT_MAXOCCUR_NODE_LIMIT ; 

Default maximum W3C XML Schema declaration occurance node limit, maxOccur, is 100. 

Method getEntityExpansionLimit() 

public int getEntityExpansionLimit(); 

Get the maximum entity expansion limit. 

Method getMaxOccurNodeLimit() 

public int getMaxOccurNodeLimit(); 

Get the maximum W3C XML Schema declaration occurance node limit, maxOccur. 

Method setEntityExpansionLimit(int) 

public void setEntityExpansionLimit(int limit); 

Parameters 

limit 

Maximum entity expansion limit. 

Set the maximum entity expansion limit. 

An IllegalArgumentException will be thrown if the limit is < 1. 

Method setMaxOccurNodeLimit(int) 

public void setMaxOccurNodeLimit(int limit); 

Parameters 

limit 

Maximum W3C XML Schema declaration occurance node limit, maxOccur. 

Set the maximum W3C XML Schema declaration occurance node limit, maxOccur. 

An IllegalArgumentException will be thrown if the limit is < 1. 

Class Version 

Provides version information about the Java API for XML Processing specification and implementation. 

Specification version information is defined by the Java API for XML Processing specification. 

Implementation version information is defined by querying the service provider as defined in META-INF/ser 

vices/javax.xml.AbstractVersion. The service provider must extend javax.xml.AbstractVersion. 

236




Synopsis 

final Version { 

public Version(); 

static String getSpecificationTitle(); 

static String getSpecificationVersion(); 

static String getSpecificationVendor(); 

static String getExtensionName(); 

final String getImplementationTitle(); 

final String getImplementationVersion(); 

final String getImplementationVendor(); 

final String getImplementationVendorID(); 

final String getImplementationURL(); 


} 

Author 



Since 1.5 

See Also 


javax.xml.AbstractVersion [Class AbstractVersion] 


| 

javax.xml.Version 

Members 

Constructor Version() 

public Version(); 

Constructor uses implementation version information service provider to get version information. 

Method getExtensionName() 

static String getExtensionName(); 

237




Get extension name. e.g. "javax.xml.datatype, javax.xml.namespace, javax.xml.parsers, javax.xml.transform, 

javax.xml.validation, javax.xml.xpath" 

Returned extension name is a unique identifier for the extension in the Jar file. By convention, the Java API for XML 

Processing uses a comma separated list of available packages. 


final String getImplementationTitle(); 

Get implementation title. 

Returns null if not available/applicable. 


final String getImplementationURL(); 

Get implementation URL. e.g. URL with implementation details. 



final String getImplementationVendor(); 

Get implementation vendor. 



final String getImplementationVendorID(); 

Get implementation vendor ID. e.g. com.sun 



final String getImplementationVersion(); 

Get implementation version. 


Method getSpecificationTitle() 

static String getSpecificationTitle(); 

Get specification title. 

Method getSpecificationVendor() 

static String getSpecificationVendor(); 

238




Get specification vendor. 

Method getSpecificationVersion() 

static String getSpecificationVersion(); 

Get specification version. 



Return all version information as a human readable String. Version information includes: 

• specification title 

• specification version 

• specification vendor 

• extension name 

• implementation title 

• implementation version 

• implementation vendor 

• implementation vendor ID 

• implementation URL 


Class VersionImpl 

Synopsis 

Provides version information about the Java API for XML Processing implementation. 

public VersionImpl extends AbstractVersion { 

public VersionImpl(); 

public String getImplementationTitle(); 

public String getImplementationVersion(); 

public String getImplementationVendor(); 

public String getImplementationVendorID(); 

public String getImplementationURL(); 

} 

239




Author 



Since 1.5 



| 

javax.xml.AbstractVersion 

| 

javax.xml.VersionImpl 

Members 


public String getImplementationTitle(); 

Get implementation title. 



public String getImplementationURL(); 

Get implementation URL. e.g. URL with implementation details. 



public String getImplementationVendor(); 

Get implementation vendor. 



public String getImplementationVendorID(); 

Get implementation vendor ID. e.g. com.sun 



public String getImplementationVersion(); 

Get implementation version. 

240





Class XMLConstants 

Synopsis 

Utility class to contain basic XML values as constants. 

final XMLConstants { 

public XMLConstants(); 


} 

Author 



Since 1.5 

See Also 


Extensible Markup Language (XML) 1.1 [http://www.w3.org/TR/xml11/], Extensible Markup 

Language (XML) 1.0 (Second Edition) [http://www.w3.org/TR/REC-xml], XML 1.0 Second 

Edition Specification Errata [http://www.w3.org/XML/xml-V10-2e-errata], Namespaces in XML 

1.1 [http://www.w3.org/TR/xml-names11/], Namespaces in XML 

[http://www.w3.org/TR/REC-xml-names], Namespaces in XML Errata 

[http://www.w3.org/XML/xml-names-19990114-errata], XML Schema Part 1: Structures 

[http://www.w3.org/TR/xmlschema-1/] 


| 

javax.xml.XMLConstants 

Members 

Constructor XMLConstants() 

public XMLConstants(); 

XMLConstants is final and only includes static final values. A constructor is needed to allow 

javax.xml.XMLConstants.toString [ Method toString()] to be invoked. 

Field DEFAULT_NS_PREFIX 

static java.lang.String DEFAULT_NS_PREFIX ; 

See Also 

Namespaces in XML, 3. Qualified Names [http://www.w3.org/TR/REC-xml-names/#ns-qualnames] 

Prefix to use to represent the default XML Namespace. 

241




Defined by the XML specification to be "". 

Field NULL_NS_URI 

static java.lang.String NULL_NS_URI ; 

See Also Namespaces in XML, 5.2 Namespace Defaulting 

[http://www.w3.org/TR/REC-xml-names/#defaulting] 

Namespace URI to use to represent that there is no Namespace. 

Defined by the Namespace specification to be "". 

Field W3C_XML_SCHEMA_INSTANCE_NS_URI 

static java.lang.String W3C_XML_SCHEMA_INSTANCE_NS_URI ; 

See Also 

XML Schema Part 1: Structures, 2.6 Schema-Related Markup in Documents Being Validated 

[http://www.w3.org/TR/xmlschema-1/#Instance_Document_Constructions] 

W3C XML Schema Instance Namespace URI. 

Defined to be " http://www.w3.org/2001/XMLSchema-instance". 

Field W3C_XML_SCHEMA_NS_URI 

static java.lang.String W3C_XML_SCHEMA_NS_URI ; 

See Also 

XML Schema Part 1: Structures, 2.6 Schema-Related Markup in Documents Being Validated 

[http://www.w3.org/TR/xmlschema-1/#Instance_Document_Constructions] 

W3C XML Schema Namespace URI. 

Defined to be " http://www.w3.org/2001/XMLSchema". 

Field XML_DTD_NS_URI 

static java.lang.String XML_DTD_NS_URI ; 

XML Document Type Declaration Namespace URI as an arbitrary value. 

Since not formally defined by any existing standard, arbitrarily define to be " http://www.w3.org/TR/RECxml". 

Field XML_NS_PREFIX 

static java.lang.String XML_NS_PREFIX ; 

See Also 

Namespaces in XML, 3. Qualified Names< [http://www.w3.org/TR/REC-xml-names/#ns-qualnames] 

The official XML Namespace prefix. 

Defined by the XML specification to be " xml". 

242




Field XML_NS_URI 

static java.lang.String XML_NS_URI ; 

See Also 


The official XML Namespace name URI. 

Defined by the XML specification to be " http://www.w3.org/XML/1998/namespace". 

Field XMLNS_ATTRIBUTE 

static java.lang.String XMLNS_ATTRIBUTE ; 

See Also 


The official XML attribute used for specifying XML Namespace declarations. 

It is NOT valid to use as a prefix. Defined by the XML specification to be " xmlns". 

Field XMLNS_ATTRIBUTE_NS_URI 

static java.lang.String XMLNS_ATTRIBUTE_NS_URI ; 

See Also 

Namespaces in XML, 3. Qualified Names [http://www.w3.org/TR/REC-xml-names/#ns-qualnames], 

Namespaces in XML Errata [http://www.w3.org/XML/xml-names-19990114-errata/] 

The official XML attribute used for specifying XML Namespace declarations, XMLConstants.XMLNS_ATTRIBUTE 

[ Field XMLNS_ATTRIBUTE], Namespace name URI. 

Defined by the XML specification to be " http://www.w3.org/2000/xmlns/". 



Human readable String of all XMLConstants public fields. 


Class XMLUtils 

Synopsis 

XMLUtils provides core XML utilities. 

} 

final XMLUtils { 

static boolean isValidNCName(java.lang.String ncName); 

static boolean isValidNCName(java.lang.String ncName, 

java.lang.String xmlVersion); 

243




Author Jeff Suttor [mailto:Jeff.Suttor@Sun.com], Kohsuke Kawaguchi 

[mailto:kohsuke.kawaguchi@Sun.com] 


Since 1.5 

See Also 


Extensible Markup Language (XML) 1.1 [http://www.w3.org/TR/xml11/], Extensible Markup 

Language (XML) 1.0 (Second Edition) [http://www.w3.org/TR/REC-xml], XML 1.0 Second 

Edition Specification Errata [http://www.w3.org/XML/xml-V10-2e-errata], Namespaces in XML 

1.1, NCName [http://www.w3.org/TR/xml-names11/#NT-NCName], Namespaces in XML, NC 

Name [http://www.w3.org/TR/REC-xml-names/#NT-NCName], Namespaces in XML Errata, 6 

December 2002 [http://www.w3.org/XML/xml-names-19990114-errata] 


| 

javax.xml.XMLUtils 

Members 

Method isValidNCName(String) 

static boolean isValidNCName(java.lang.String ncName); 

Parameters 

ncName 

returns 

NCName to validate 

true if NCName is valid, otherwise false 

Exceptions 

java.lang.NullPointerEx 

ception 

if the String being passed in as the parameter is null. 

See Also 

Namespaces in XML 1.1, NCName [http://www.w3.org/TR/xml-names11/#NT-NCName] 

Test NCName for validity using XML 1.1 validity rules. 

An NCName of null is invalid and a NullPointerException will be thrown. An NCName of "" is invalid and 

false will be returned. 

Method isValidNCName(String, String) 

static boolean isValidNCName(java.lang.String ncName, 

java.lang.String xmlVersion); 

Parameters 

ncName 

xmlVersion 

NCName to validate 

to validate NCName against 

244




returns 

true if NCName is valid, otherwise false 

See Also 

Namespaces in XML 1.1, NCName [http://www.w3.org/TR/xml-names11/#NT-NCName], 

Namespaces in XML, NCName [http://www.w3.org/TR/REC-xml-names/#NT-NCName], 

Namespaces in XML Errata, 6 December 2002 

[http://www.w3.org/XML/xml-names-19990114-errata] 

Test NCName for validity using specified version of XML validity rules. 

An NCName of null is invalid and a NullPointerException will be thrown. An NCName of "" is invalid and 

false will be returned. 

XML versions of "1.0" and "1.1" are supported. An XML version of null is invalid and a NullPointerException 

will be thrown. Specifying any other value for XML version will cause an IllegalArgumentException to be 

thrown. 

245



Chapter 18. Change History 

This section lists the changes that have occurred over the development of this specification. 

From 1.1 final release to 1.2 final release 

Introduced properties to enable validation against xml schemas. 

From 1.1 Proposed Final Draft to 1.1 Final Release 

Made getLexicalHandler and setLexicalHandler in javax.xml.transform.sax.SAXResult public methods. 

Explicitly spelled out the location of the jaxp.properties to be in the jre/lib directory. 

From 1.1 Public Review 2 to Proposed Final Draft 

Added getDOMImplementation method to DocumentBuilder. 

Added SourceLocator to TransformerConfigurationException. 

Added extends DTDHandler to javax.xml.transform.sax.TransformerHandler 

Changed return type of getException in TransformerException to return Throwable. 

Renamed TFactoryConfigurationError to TransformerFactoryConfigurationError. 

From 1.1 Public Review 1 to 1.1 Public Review 2 

Modified javax.xml.transform to include a new set of APIs for transformation. 

Changed endorsed specifications section to include the second edition of the XML 1.0 recommendation, the DOM 

Level2 core recommendation and the final version of SAX2-extensions. 

From 1.0 Final Release to 1.1 Public Review 

Added parameter systemId to all the parse and transform methods which take Streams as parameters. This was done 

to provide a base to resolve relative URIs. 

Added setIgnoreWhitespace, setExpandEntityReference, setIgnoringComments, setAttributes and the corresponding 

getters to DocumentBuilderFactory. 

Added get/setAttribute to TransformFactory. 

Added setEntityResolver, setErrorHandler and get/setXSLParam to Transform. 

Added get/setFeature to SAXParserFactory. 

Added get/setProperty to SAXParser. 

Added SAX2 extensions. 

246


Change History 


Added Transformations 

Added more mechanisms to look up an implementation of the various factories. 

Removed conformance requirements from the specification and just refer to the conformance requirements as required 

by the specifications included by reference. 

From 1.0 Public Release to 1.0 Final Release 

The reservation of the java and javax namespace prefixes was removed. The XML Namespace specification is clear 

that a namespace is a collection of names that is identified by a URI reference. The prefix is a local identifier for the 

URI reference, therefore the reservation of the java and javax namespaces was in error. 

From 1.0 Public Review to 1.0 Public Release 

From the Public Review draft of this specification to the Public Release version, the specification was reordered and 

rewritten to address general feedback from the user community. This feedback indicated that the specification was too 

detailed in describing the endorsed specifications and not detailed enough in describing the plugability layer. 

The newParser method of the SAXParserFactory abstract class was removed. Feedback showed that it was 

confusing to be able to obtain both the SAXParser wrapper and the underlying implementation from the factory. 

Removing this method allows the API to be more understandable while preserving the ability to access the underlying 

parser via the getParser method of the SAXParser abstract class. 

The getLocale and setLocale methods of the various classes were removed. Instead it was felt that parser im 

plementation authors should report errors in the configured default locale of the execution environment. 

A new exception named ParserConfigurationException was added so that a parser factory can signal to an 

application that it can’t provide a parser with the desired configuration. The checkXXX methods aren’t sufficient for 

this purpose as a situation may arise where there is a mutually exclusive setting of various parser properties. At this 

time, this problem is potentially minor as there are only two settable properties on each of the parser types, but in the 

future as the number of settable properties increases, the problem would get harder to solve without an exception that 

could be thrown at parser creation time. As part of this change, the setXXX property methods of the factories no 

longer throw an IllegalArgumentException if they are set to a property which cannot be supported. 

The FactoryException class was renamed to FactoryConfigurationError. This rename was undertaken 

to emphasize that such an error condition is a fatal condition that an application should not be reasonable expected to 

handle. 

247



Appendix A. Change Log 

Change Log: Community Draft released 

: version 0.1 released to the Java Community for Community Review 

: 2003-08-15 00:00 PDT, Jeff Suttor 

Change Log: javax.xml.parsers.FactoryFinder class restored, changes to javax.xml.parsers.DocumentBuilderFactory, 

javax.xml.parsers.SAXParserFactory, javax.xml.transform.TransformerFactory, javax.xml.transform.FactoryFinder 

classes to use FactoryFinder 

: javax.xml source code was originally seeded from a repository that did not contain FactoryFinder 

: 2003-08-21 14:00 PDT, Jeff Suttor via Reference Implementation team 

Change Log: new methods javax.xml.parsers.DocumentBuilderFactory.setXIncludeAware(boolean state) , 

javax.xml.parsers.DocumentBuilderFactory.isXIncludeAware() , javax.xml.parsers.DocumentBuilder.isXIncludeAware() 

, javax.xml.parsers.SAXParserFactory.setXIncludeAware(boolean state) , javax.xml.parsers.SAXParserFactory.isXIn 

cludeAware() , javax.xml.parsers.SAXParser.isXIncludeAware() 

: need to be able to enable/disable/query XInclude processing state 

: 2003-08-28 22:15 PDT, Jeff Suttor via Reference Implementation team 

Change Log: new method javax.xml.transform.setParameters(Properties params), new method javax.xml.transform.get 

Parameters() 

: ability to set multiple parameters, get all parameters 

: 2003-09-08 00:40 PDT, Jeff Suttor via Ilene Seelemann 

Change Log: Community Draft released 

: version 0.2 released to the Java Community for Community Review balloting 


Change Log: bug: TransformerException.printStackTrace(PrintStream) doesn’t print anything 

: PrintStream is now .flush()’d 


Change Log: editorial: javax.xml.transformer.ErrorListener specification of behavior when application doesn’t register 

its own ErrorListener 

: javax.xml.transform package Javadoc and javax.xml.transform.ErrorListener class Javadoc updated to clarify beha 

vior of default ErrorListener 


Change Log: editorial: SAX Plugability in specification and SAXParserFactory.newInstance() Javadoc, DOM 

Plugability in specification and DocumentBuilderFactory.newInstance() Javadoc, XSLT Plugability in specification 

and TransformerFactory.newInstance() Javadoc reading of jaxp.properties clarified 

: specification prose and Javadoc updated to include: The jaxp.properties file is read only once by the JSR 206 Java 

API for XML Processing (JAXP) 1.3 implementation and it’s values are then cached for future use. If the file does not 

exist when the first attempt is made to read from it, no further attempts are made to check for its existence. It is not 

possible to change the value of any property in jaxp.properties after it has been read for the first time. 


Change Log: functional: Version in specification and class javax.xml.Version and class javax.xml.AbstractVersion 

created 

: a way to get JSR 206 Java API for XML Processing (JAXP) 1.3 specification and implementation version inform 

ation is now provided 


Change Log: documentation: updated Javadoc in javax.xml.transform.Transformer.transform(Source, Result) , 

javax.xml.transform.sax.SAXSource.SAXSource() , javax.xml.transform.dom.DOMSource.DOMSource() , 

javax.xml.transform.stream.StreamSource.StreamSource() 

: clarified that an empty Source is always transformed into an empty Result 


248



Chapter 19. Colophon 

Talk the Talk, Walk the Walk 

JSR 206 Java API for XML Processing (JAXP) 1.3 was authored in XML using the DocBook [http://docbook.org/] 

DTD. 

The XML was transformed into XHTML, HTML and XSL Formatting Objects using the DocBook style sheets. The 

XSL Formatting Objects were then transformed into PDF. 

Table 19.1. XML Usage Conventions 

 

 

"external-spec" is the type of all ulinks that refer to external 

specifications 

"organization" is the type of all ulinks that refer to organ 

izations 

249

JSR 206 Java API for XML Processing (JAXP) 1.3 - Oracle Software ...

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?