Java API for XML

8/8/2019 Java API for XML

1/148

Java API for XML ProcessingVersion 1.2 Final Release

Comments to: [email protected]

Rajiv Mordani

Scott Boag (Lotus)

Sun Microsystems, Inc.

901 San Antonio Road

Palo Alto CA 94303 USA

650 960-1300

September 6, 2002


2/148

JavaTM API for XML Processing (JAXP) Specification ("Specification")

Version: 1.2Status: FCSRelease: August 23, 2002

Copyright 2002 Sun Microsystems, Inc.

4150 Network Circle, Santa Clara, California 95054, U.S.AAll rights reserved.NOTICE; LIMITED LICENSE GRANTS

Sun Microsystems, Inc. ("Sun") hereby grants you a fully-paid, non-exclusive, non-transferable,worldwide, limited license (without the right to sublicense), under the Suns applicable intellectualproperty rights to view, download, use and reproduce the Specification only for the purpose ofinternal evaluation, which shall be understood to include developing applications intended to run onan implementation of the Specification provided that such applications do not themselvesimplement any portion(s) of the Specification.

Sun also grants you a perpetual, non-exclusive, worldwide, fully paid-up, royalty free, limitedlicense (without the right to sublicense) under any applicable copyrights or patent rights it mayhave in the Specification to create and/or distribute an Independent Implementation of theSpecification that: (i) fully implements the Spec(s) including all its required interfaces andfunctionality; (ii) does not modify, subset, superset or otherwise extend the Licensor Name Space,or include any public or protected packages, classes, Java interfaces, fields or methods within theLicensor Name Space other than those required/authorized by the Specification or Specificationsbeing implemented; and (iii) passes the TCK (including satisfying the requirements of theapplicable TCK Users Guide) for such Specification. The foregoing license is expresslyconditioned on your not acting outside its scope. No license is granted hereunder for any otherpurpose.

You need not include limitations (i)-(iii) from the previous paragraph or any other particular "passthrough" requirements in any license You grant concerning the use of your IndependentImplementation or products derived from it. However, except with respect to implementations ofthe Specification (and products derived from them) that satisfy limitations (i)-(iii) from the previousparagraph, You may neither: (a) grant or otherwise pass through to your licensees any licensesunder Suns applicable intellectual property rights; nor (b) authorize your licensees to make anyclaims concerning their implementations compliance with the Spec in question.

For the purposes of this Agreement: "Independent Implementation" shall mean an implementationof the Specification that neither derives from any of Suns source code or binary code materials nor,except with an appropriate and separate license from Sun, includes any of Suns source code orbinary code materials; and "Licensor Name Space" shall mean the public class or interface

declarations whose names begin with "java", "javax", "com.sun" or their equivalents in anysubsequent naming convention adopted by Sun through the Java Community Process, or anyrecognized successors or replacements thereof.


3/148

This Agreement will terminate immediately without notice from Sun if you fail to comply with anymaterial provision ofor act outside the scope of the licenses granted above.

TRADEMARKS

No right, title, or interest in or to any trademarks, service marks, or trade names of Sun or Sunslicensors is granted hereunder. Sun, Sun Microsystems, the Sun Microsystems logo, Java, and theJava Coffee Cup logo are trademarks or registered trademarks of the Sun Microsystems, Inc. in theU.S. and other countries.

DISCLAIMER OF WARRANTIES

THE SPECIFICATION IS PROVIDED "AS IS". SUN MAKES NO REPRESENTATIONS ORWARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO,WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, ORNON-INFRINGEMENT, THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLEFOR ANY PURPOSE OR THAT ANY PRACTICE OR IMPLEMENTATION OF SUCHCONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS,TRADE SECRETS OR OTHER RIGHTS. This document does not represent any commitment torelease or implement any portion of the Specification in any product.

THE SPECIFICATION COULD INCLUDE TECHNICAL INACCURACIES ORTYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THEINFORMATION THEREIN; THESE CHANGES WILL BE INCORPORATED INTO NEWVERSIONS OF THE SPECIFICATION, IF ANY. SUN MAY MAKE IMPROVEMENTS AND/OR CHANGES TO THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THESPECIFICATION AT ANY TIME. Any use of such changes in the Specification will begoverned by the then-current license for the applicable version of the Specification.

LIMITATION OF LIABILITY

TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL SUN OR ITSLICENSORS BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION,LOST REVENUE, PROFITS OR DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL,INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OFTHE 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 indemnify, hold harmless, and defend Sun and its licensors from any claims arising orresulting from: (i) your use of the Specification; (ii) the use or distribution of your Java application,applet and/or clean room implementation; and/or (iii) any claims that later versions or releases of

any Specification furnished to you are incompatible with the Specification provided to you underthis license.


4/148

RESTRICTED RIGHTS LEGEND

U.S. Government: If this Specification is being acquired by or on behalf of the U.S. Government orby a U.S. Government prime contractor or subcontractor (at any tier), then the Governments rightsin the Software 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 inconnection with your use of the Specification ("Feedback"). To the extent that you provide Sunwith any Feedback, you hereby: (i) agree that such Feedback is provided on a non-proprietary andnon-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, toincorporate, disclose, and use without limitation the Feedback for any purpose related to theSpecification and future versions, implementations, and test suites thereof.

(LFI#117811/Form ID#011801)


5/148

SECTION 1 Overview 7

What is XML? 7

XML and the Java Platform 8

About this Specification 8

Who Should Read this Document 8

Development of this Specification 9

Report and Contact 9

Acknowledgements 10

SECTION 2 Endorsed Specifications 11

W3C XML 1.0 Recommendation (Second edition) 11

W3C XML Namespaces 1.0 Recommendation 12

Simple API for XML Parsing (SAX) 2.0 12Document Object Model (DOM) Level 2 13

XSLT 1.0 13

W3C XML Schema 13

SECTION 3 Plugability Layer 15

SAX Plugability 15

DOM Plugability 17

XSLT Plugability 19

Thread Safety 26

Properties for enabling schema validation 27

Recommended implementation of properties 31


6/148

SECTION 4 Packages javax.xml.parsers andjavax.xml.transform 33

SECTION 5 Conformance Requirements 141

SECTION 6 Change History 143

From 1.1 final release to 1.2 final release 143

From 1.1 Proposed Final Draft to 1.1 Final Release 143

From 1.1 Public Review 2 to Proposed Final Draft 143

From 1.1 Public Review 1 to 1.1 Public Review 2 144

From 1.0 Final Release to 1.1 Public Review 144

From 1.0 Public Release to 1.0 Final Release 145

From 1.0 Public Review to 1.0 Public Release 145

SECTION 7 Future Directions 147

Updated SAX and DOM Support 147

Update XSL Plugability Support 147

Plugability Mechanism Enhancements 148


7/148

Java API for XML Processing Version 1.2 7

SECTION 1 Overview

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

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

early 1980s 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, business-

to-business communication, and enterprise application messaging.


8/148

Overview

8 September 6, 2002

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

1.3 About this Specification

This document describes the Java API for XML Processing, Version 1.2. 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.0 (JCP 2.0).

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

newDocumentBuilder(44)

1.4 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

understanding of the API.

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

and specifications on the part of the reader is assumed.


9/148


Development of this Specification

1.5 Development of this Specification

This specification was developed in accordance with the Java Community Process 2.0. It was developed under the

authorization of Java Specification Request 63. More information about the Java Community Process can be found at:

http://www.jcp.org

The specific information contained in Java Specification Request 63 can be found at:

http://jcp.org/jsr/detail/63.jsp

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

individuals are:

Rajiv Mordani (Spec lead), Sun Microsystems

James Duncan Davidson

Scott Boag, Lotus.

Neil Graham, IBM

Jeff Mischinkinsky, Persistence

Chris Fry, BEA

Tom Reilly, Allaire

Tom Bates, Informix

Miles Sabin, CromwellMedia

Wolfram Kaiser, POET

Philip Boutros, Inso

Pier Fumagalli, Apache Software Foundation

Stefano Mazzocchi, Apache Software Foundation

Takuki Kamiya, Fujitsu Ltd

Brett McLaughlin, Lutris Technologies

Jason Hunter

1.6 Report and Contact

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

oped under the auspices of the Java Community Process would not serve your needs as well. To comment on this speci-

fication, please send email to:


10/148

Overview

10 September 6, 2002

[email protected]

You can stay current with Suns Java Platform related activities, as well as information on our xml-interest and

xml-announce mailing lists, at our website located at:

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

1.7 Acknowledgements

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 author of this specification would like to thank (in no particular order):

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

Mikael Staldal, Michael Kay, and the contributors to the original TrAX mailing list.

The W3C DOM Working Group chaired by Lauren Wood

The JSR-63 Expert Group listed above

Graham Hamilton, Mark Hapner, Eduardo Pelegri-Lopart, Connie Weiss, Jim Driscoll, Edwin Goei, TomKincaid, Bill Shannon, Vivek Nagar, Janet Breuer, Carla Carlson, Jeff Jackson Karen Shipe and Brian Ogata all

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


11/148


SECTION 2 Endorsed Specifications

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

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

2.1 W3C XML 1.0 Recommendation (Second edition)

The W3C XML 1.0 Recommendation specifies the core XML syntax by subsetting the existing, widely used interna-

tional SGML1 text processing standard. It is a product of the W3C XML Activity, details of which can be found at:

http://www.w3.org/XML/

The XML 1.0 Recommendation (second edition) can be located at:

http://www.w3.org/TR/2000/REC-xml-20001006

This specification includes by reference the XML 1.0 Recommendation (second edition) in its entirety for the purposes

of defining the XML language manipulated by the APIs defined herein.

1. Standard Generalized Markup Language, ISO 8879:1986(E) as amended and corrected.


12/148

Endorsed Specifications


2.2 W3C XML Namespaces 1.0 Recommendation

The W3C XML Namespaces Recommendation defines the syntax and semantics for XML structures required to be dis-

tinct from other XML markup. In particular, it defines a mechanism whereby a set of XML markup may have a distin-

guishing "namespace" associated with it, and the responsibility of XML parser in handling and exposing such

namespace information.

The XML Namespaces 1.0 Recommendation is located at:

http://www.w3.org/TR/1999/REC-xml-names-19990114/

This specification includes by reference the XML Namespaces 1.0 Recommendation in its entirety.

2.3 Simple API for XML Parsing (SAX) 2.0

The Simple API for XML (SAX) is a public domain API developed cooperatively by the members of the XML-DEV

mailing list. It provides an event-driven interface to the process of parsing an XML document.

An event driven interface provides a mechanism for a "callback" notifications to applications code as the underlying

parser recognizes XML syntactic constructions in the document.

The SAX 2.0 API is located at:

http://www.megginson.com/SAX/index.html

The SAX 2 extensions is located at:

http://www.megginson.com/Software/sax2-ext-1.0.zip

The details of the XML-DEV mailing list can be found at

http://xml.org/xml-dev/index.shtml

This specification includes by reference the SAX 2.0 API and the SAX2 extensions in its entirety.

The API packages included by reference are:

org.xml.sax

org.xml.sax.helpers

org.xml.sax.ext


13/148


Document Object Model (DOM) Level 2

2.4 Document Object Model (DOM) Level 2

The Document Object Model (DOM) is a set of interfaces defined by the W3C DOM Working Group. It describes facil-

ities for a programmatic representation of a parsed XML (or HTML) document. The DOM Level 2 specification defines

these interfaces using Interface Definition Language (IDL) in a language independent fashion and also includes a Java

Language binding.

The DOM Level 2 Core Recommendation is located at:

http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/

This specification includes by reference both the abstract semantics described for the DOM Level 2 Core Recommenda-

tion interfaces and the associated Java Language binding. It does not include the optional extensions defined by the

DOM working group. The API package included by this specification is:

org.w3c.dom

2.5 XSLT 1.0

The XSL Transformations (XSLT) describes a language for transforming XML documents into other XML documents

or other text output. It was defined by the W3C XSL Working group.

The XSLT 1.0 Recommendation is located at:

http://www.w3.org/TR/1999/REC-xslt-19991116

This specification includes by reference the XSLT 1.0 specification in its entirety.

2.6 W3C XML Schema

The W3C xml schema language defines syntactic, structural and value constraints applicable to instances of documents.

It was defined by the W3C XML schema working group.

The XML Schema Recommendation is split into 2 parts

XML Schema Part 1: Structures is located at http://www.w3.org/TR/2001/REC-xmlschema-1-20010502


14/148

Endorsed Specifications


XML Schema Part 2: Datatypes is located at http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/

datatypes.html

This specification includes by reference both parts of the W3C XML schema specification listed above in its entirety.


15/148


SECTION 3 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.

3.1 SAX Plugability

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

org.xml.sax.DefaultHandlerAPI to a SAXParser implementation and parse XML documents. As the parserprocesses 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 SAXParserFac-

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

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


16/148

Plugability Layer


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.

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

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

ParserFactory in jars available to the runtime.

Platform default SAXParserFactory instance.

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

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

resolve it.

The instance ofSAXParserFactory 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 set-

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

3.1.1 Examples

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

SAXParser parser;

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

// handle error} catch (ParserConfigurationException pce) {

// handle error

}

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


17/148


DOM Plugability

try {

parser = factory.newSAXParser();

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


// handle error


// handle error

} catch (ParserConfigurationException pce) {

// handle error

}

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

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

user.parserApp.

3.2 DOM Plugability

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

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

BuilderFactory. The DocumentBuilderFactory instance is obtained via the static newInstance method of the

DocumentBuilderFactory class.

This method uses the following ordered lookup procedure to determine theDocumentBuilderFactory implemen-

tation 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 thekey being the system property defined above.


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

mentBuilderFactory in jars available to the runtime.

Platform default DocumentBuilderFactory instance.

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

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

user can resolve it.


18/148

Plugability Layer


The instance ofDocumentBuilderFactory 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 imple-

mentation instance from the factory. If the factory cannot provide a parser configured as set by the application program-

mer, then a ParserConfigurationException is thrown.

3.2.1 Reliance on SAX API

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

lying DOM implementation must use a SAX parser to parse the XML content, only that the implementation communi-

cate with the application using these existing and defined APIs.

3.2.2 Examples

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


// handle error


// handle error


// handle error

}

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

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

try {

builder = factory.newDocumentBuilder();

Document document = builder.parse(location);



19/148


XSLT Plugability

// handle error


// handle error


// handle error

}


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

FactoryImpl user.parserApp.

3.3 XSLT Plugability

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

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


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

key being the system property defined above.


vices API will look for the classname in the file META-INF/services/javax.xml.trans-

form.TransformerFactory in jars available to the runtime.

Platform default TransformFactory instance.

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

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

and how the user can resolve it.

3.3.1 Examples

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


20/148

Plugability Layer


Transformer transformer;

TransformerFactory factory = TransformerFactory.newInstance();

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

// handle error

}

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


Exceptions and Error Reporting

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

tion whose input is totally DOM based.


21/148


XSLT Plugability


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

{

DocumentBuilderFactory dfactory =

DocumentBuilderFactory.newInstance();

dfactory.setNamespaceAware(true); // Always, required for XSLTDocumentBuilder 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/inc2.xsl))

? new DOMSource(xslInc2) : null;

}});

// The TransformerFactory will call the anonymous URI

// resolver set above when it encounters

//

Templates templates

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

// Get a transformer from the templates.

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


}


22/148

Plugability Layer


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

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

}

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


23/148


XSLT Plugability


// 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 an reader for reading.

XMLReader reader = XMLReaderFactory.createXMLReader();

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

new SAXResult(new ExampleContentHandler()));

}

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.

XMLReader reader = XMLReaderFactory.createXMLReader();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.


24/148

Plugability Layer





{

// If so, we can safely cast.

SAXTransformerFactory stfactory = ((SAXTransformerFactory) tfactory);

// 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.XMLReader#parse on the final reader in the chain.


25/148


XSLT Plugability




{

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,

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

}


26/148

Plugability Layer


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

toryImpl user.parserApp.

3.4 Thread Safety

Implementations of the SAXParser, DocumentBuilder and Transformer abstract classes 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, DocumentBuilder or Transformer 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 or Transformer instance.

Configuration of a SAXParserFactory, DocumentBuilderFactory or TransformerFactory is also not

expected to be thread safe. This means that an application programmer should not allow a SAXParserFactory or

DocumentBuilderFactory to have its setNamespaceAware or setValidating methods from more than one

thread.

It is expected that the newSAXParser method of a SAXParserFactory implementation, the newDocumentBuilder

method of a DocumentBuilderFactory and the newTransformer method of a TransformerFactorywill

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.


27/148


Properties for enabling schema validation

3.5 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 supportthe W3C XML schema specification at this URI: http://www.w3.org/2001/XMLSchema.

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

guage 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 / noNamespaceSchemaLo-

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

ified using this property matches the target namespace of a schema occuring in schemaLocation attribute, the schema

specified by the user using this property will be used and the instance documents schemaLocation attribute will be

effectively ignored. However if the target namespace of any schema specified using this property doesnt match the

target namespace of a schema occuring 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


28/148

Plugability Layer


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

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

DocumentBuilderFactory.setAttribute method.

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

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


29/148


Properties for enabling schema validation

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

has been called.

TABLE 1.

DocumenthasDOCTYPE?

schemalanguagepropertysettoXMLSchemas?

schemasourceproperty set?

any schemalocationattributepresent indocument?

Document Validatedagainst

Schemafileused

no no no no error as per JAXP 1.1 spec.

Must have a DOCTYPE

declaration when validation

is turned on.

N/A

no no no yes Error. Schema language

must be set .

N/A

no no yes yes / no Error schema language

must be set

N/A

yes / no yes no yes xml schemas schema files referredto using the schema

locationattributes

present in the

instance document

yes / no yes yes no xml schemas schema file referred

to in the schema-

source property

yes / no yes yes yes xml schemas schema file referred

to in the schema

source property, if the

target namespace

matches. The schema

file referred to in theschema location

attribute is ignored

only if the target

namespace matches

yes no no yes / no DTD DTD referred to in

the DOCTYPE

yes no yes yes / no Error. Schema source cannot

be set without setting the

schema language.

N/A


30/148

Plugability Layer


3.5.1 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) {

de.printStackTrace();

}


31/148


Recommended implementation of properties

3.6 Recommended implementation of properties

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

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


32/148

Plugability Layer



33/148


SECTION 4 Packages javax.xml.parsers and

javax.xml.transform

This section defines the API of the javax.xml.parsers, javax.xml.transform, javax.xml.transform.dom

javax.xml.transform.sax and javax.xml.transform.stream packages.


34/148

Packages javax.xml.parsers and javax.xml.transform



35/148

35

Package

javax.xml.parsers

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

SAX (Simple API for XML)

DOM (Document Object Model)

Class Summary

Classes

DocumentBuilder36 Defines the API to obtain DOM Document instances from an XML document.

DocumentBuilderFactor

y41

Defines a factory API that enables applications to obtain a parser that produces DOM

object trees from XML documents.

SAXParser52 Defines the API that wraps an org.xml.sax.XMLReader implementation class.

SAXParserFactory60 Defines a factory API that enables applications to configure and obtain a SAX based

parser to parse XML documents.

Exceptions

ParserConfigurationEx

ception50

Indicates a serious configuration error.

Errors

FactoryConfigurationE

rror47

Thrown when a problem with configuration with the Parser Factories exists.


36/148

DocumentBuilder javax.xml.parsers

36

javax.xml.parsers

DocumentBuilder

Syntaxpublic abstract class DocumentBuilder

java.lang.Object

|

+--javax.xml.parsers.DocumentBuilder

Description

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

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

An instance of this class can be obtained from the newDocumentBuilder()44 method. Once an instance

of this class is obtained, XML can be parsed from a variety of input sources. These input sources are Input-

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

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

An implementation ofDocumentBuilder isNOTguaranteed to behave as per the specification if it is used

concurrently by two or more threads. It is recommended to have one instance of the DocumentBuilder per

thread or it is upto the application to make sure about the use ofDocumentBuilder from more than one

thread.

Since: JAXP 1.0

Member Summary

Constructors

protected DocumentBuilder()37

Methods

public abstract DOMIm-

plementation

getDOMImplementation()37Obtain an instance of a org.w3c.dom.DOMImplementation object.

public abstract bool-

ean

isNamespaceAware()37Indicates whether or not this parser is configured to understand namespaces.


ean

isValidating()38Indicates whether or not this parser is configured to validate XML documents.

public abstract Docu-ment

newDocument()38Obtain a new instance of a DOM org.w3c.dom.Document object to build a

DOM tree with.

public Document parse(File)38Parse the content of the given file as an XML document and return a new DOM

org.w3c.dom.Document object.

public abstract Docu-

ment

parse(InputSource)38Parse the content of the given input source as an XML document and return a new

DOM org.w3c.dom.Document object.


37/148

javax.xml.parsers DocumentBuilder

DocumentBuilder()

37

Constructors

DocumentBuilder()

protected DocumentBuilder()

Methods

getDOMImplementation()

public abstract org.w3c.dom.DOMImplementation getDOMImplementation()

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

Returns: A new instance of a DOMImplementation .

isNamespaceAware()

public abstract boolean isNamespaceAware()

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

public Document parse(InputStream)39Parse the content of thegiven InputStream as an XML document and return a new

DOM org.w3c.dom.Document object.

public Document parse(InputStream, String)39Parse the content of thegiven InputStream as an XML document and return a new

DOM org.w3c.dom.Document object.public Document parse(String)39

Parse the content of the given URI as an XML document and return a new DOM


public abstract void setEntityResolver(EntityResolver)40Specify the org.xml.sax.EntityResolver to be used to resolve entities

present in the XML document to be parsed.

public abstract void setErrorHandler(ErrorHandler)40Specify the org.xml.sax.ErrorHandler to be used to report errors present in

the XML document to be parsed.

Inherited Member Summary

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait,

wait

Member Summary


38/148


isValidating()

38

Returns: true if this parser is configured to understand namespaces; false otherwise.

isValidating()

public abstract boolean isValidating()

Indicates whether or not this parser is configured to validate XML documents.Returns: true if this parser is configured to validate XML documents; false otherwise.

newDocument()

public abstract org.w3c.dom.Document newDocument()

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

Returns: A new instance of a DOM Document object.

parse(File)

public org.w3c.dom.Document parse(java.io.File f)

throws IOException, SAXException, IllegalArgumentException

Parse the content of the given file as an XML document and return a new DOM


Parameters:

f - The file containing the XML to parse.

Returns: A new DOM Document object.

Throws:

IOException - If any IO errors occur.

SAXException - If any parse errors occur.IllegalArgumentException - If the file is null.

See Also: org.xml.sax.DocumentHandler

parse(InputSource)

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


Parse the content of the given input source as an XML document and return a new DOM


Parameters:

is - InputSource containing the content to be parsed.


Throws:


SAXException - If any parse errors occur.

IllegalArgumentException - If the InputSource is null.


39/148

javax.xml.parsers DocumentBuilder

parse(InputStream)

39


parse(InputStream)

public org.w3c.dom.Document parse(java.io.InputStream is)


Parse the content of the given InputStream as an XML document and return a new DOM


Parameters:

is - InputStream containing the content to be parsed.

Throws:



IllegalArgumentException - If the InputStream is null


parse(InputStream, String)

public org.w3c.dom.Document parse(java.io.InputStream is, java.lang.String systemId)


Parse the content of the given InputStream as an XML document and return a new DOM


Parameters:

is - InputStream containing the content to be parsed.

systemId - Provide a base for resolving relative URIs.

Returns: A new DOM Document object.Throws:



IllegalArgumentException - If the InputStream is null.


parse(String)

public org.w3c.dom.Document parse(java.lang.String uri)


Parse the content of the given URI as an XML document and return a new DOM


Parameters:

uri - The location of the content to be parsed.



40/148


setEntityResolver(EntityResolver)

40

Throws:



IllegalArgumentException - If the URI is null.


setEntityResolver(EntityResolver)

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

Specify the org.xml.sax.EntityResolver to be used to resolve entities present in the XML docu-

ment to be parsed. Setting this to null will result in the underlying implementation using its own default

implementation and behavior.

Parameters:

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

setErrorHandler(ErrorHandler)

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

Specify the org.xml.sax.ErrorHandler to be used to report errors present in the XML document

to be parsed. Setting this tonull will result in the underlying implementation using its own default imple-

mentation and behavior.

Parameters:

eh - The ErrorHandler to be used to report errors present in the XML document to be parsed.


41/148

javax.xml.parsers DocumentBuilderFactory

setErrorHandler(ErrorHandler)

41

javax.xml.parsers

DocumentBuilderFactory

Syntaxpublic abstract class DocumentBuilderFactory

java.lang.Object

|

+--javax.xml.parsers.DocumentBuilderFactory

Description

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

documents. An implementation of the DocumentBuilderFactory class isNOTguaranteed to be thread

safe. It is up to the user application to make sure about the use of the DocumentBuilderFactory from

more than one thread. Alternatively the application can have one instance of the DocumentBuilder-

Factory per thread. An application can use the same instance of the factory to obtain one or more instances of

the DocumentBuilder provided the instance of the factory isnt being used in more than one thread at atime.

Since: JAXP 1.0

Member Summary

Constructors

protected DocumentBuilderFactory()42

Methods

public abstract Object getAttribute(String)42Allows the user to retrieve specific attributes on the underlying implementation.

public boolean isCoalescing()43Indicates 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.

public boolean isExpandEntityReferences()43Indicates whether or not the factory is configured to produce parsers which expand

entity reference nodes.

public boolean isIgnoringComments()43Indicates whether or not the factory is configured to produce parsers which ignores

comments.

public boolean isIgnoringElementContentWhitespace()43Indicates whether or not the factory is configured to produce parsers which ignore

ignorable whitespace in element content.

public boolean isNamespaceAware()43Indicates whether or not the factory is configured to produce parsers which are

namespace aware.

public boolean isValidating()44Indicates whether or not the factory is configured to produce parsers which validate

the XML content during parse.

public abstract Docu-

mentBuilder

newDocumentBuilder()44Creates a new instance of a DocumentBuilder36 using the currently configured

parameters.


42/148

DocumentBuilderFactory javax.xml.parsers

DocumentBuilderFactory()

42

Constructors

DocumentBuilderFactory()

protected DocumentBuilderFactory()

Methods

getAttribute(String)

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

throws IllegalArgumentException

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

public static Docu-

mentBuilderFactory

newInstance()44Obtain a new instance of a DocumentBuilderFactory.

public abstract void setAttribute(String, Object)44Allows the user to set specific attributes on the underlying implementation.

public void setCoalescing(boolean)45

Specifies that the parser produced by this code will convert CDATA nodes to Textnodes and append it to the adjacent (if any) text node.

public void setExpandEntityReferences(boolean)45Specifies that the parser produced by this code will expand entity reference nodes.

public void setIgnoringComments(boolean)45Specifies that the parser produced by this code will ignore comments.

public void setIgnoringElementContentWhitespace(boolean)45Specifies 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).

public void setNamespaceAware(boolean)45Specifies that the parser produced by this code will provide support for XML

namespaces.

public void setValidating(boolean)46Specifies that the parser produced by this code will validate documents as they are

parsed.




wait

Member Summary


43/148


isCoalescing()

43

Parameters:

name - The name of the attribute.

Returns: value The value of the attribute.

Throws:

IllegalArgumentException - thrown if the underlying implementation doesnt recognize the

attribute.

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.

Returns: true if the factory is configured to produce parsers which converts CDATA nodes to Text nodes

and appends it to the adjacent (if any) Text node; false otherwise.

isExpandEntityReferences()

public boolean isExpandEntityReferences()

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

Returns: true if the factory is configured to produce parsers which expand entity reference nodes; false

otherwise.

isIgnoringComments()

public boolean isIgnoringComments()

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

Returns: true if the factory is configured to produce parsers which ignores comments; false otherwise.

isIgnoringElementContentWhitespace()

public boolean isIgnoringElementContentWhitespace()

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

element content.

Returns: true if the factory is configured to produce parsers which ignore ignorable whitespace in element

content; false otherwise.

isNamespaceAware()

public boolean isNamespaceAware()

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

Returns: true if the factory is configured to produce parsers which are namespace aware; false otherwise.


44/148


isValidating()

44

isValidating()

public boolean isValidating()

Indicates whether or not the factory is configured to produce parsers which validate the XML content dur-

ing parse.

Returns: true if the factory is configured to produce parsers which validate the XML content during parse;false otherwise.

newDocumentBuilder()

public abstract DocumentBuilder36 newDocumentBuilder()

throws ParserConfigurationException

Creates a new instance of a DocumentBuilder36 using the currently configured parameters.

Returns: A new instance of a DocumentBuilder.

Throws:

ParserConfigurationException50 - if a DocumentBuilder cannot be created which satisfies

the configuration requested.

newInstance()

public static DocumentBuilderFactory41 newInstance()

throws FactoryConfigurationError

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

BuilderFactory implementation class to load:

Use the javax.xml.parsers.DocumentBuilderFactory 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.

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

The Services API will look for a classname in the file META-INF/services/

javax.xml.parsers.DocumentBuilderFactory 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.

Throws:

FactoryConfigurationError47- if the implementation is not available or cannot be

instantiated.

setAttribute(String, Object)

public abstract void setAttribute(java.lang.String name, java.lang.Object value)

throws IllegalArgumentException

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


45/148


setCoalescing(boolean)

45

Parameters:

name - The name of the attribute.

value - The value of the attribute.

Throws:

IllegalArgumentException - thrown if the underlying implementation doesnt recognize the

attribute.

setCoalescing(boolean)

public void setCoalescing(boolean coalescing)

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

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.

setExpandEntityReferences(boolean)

public void setExpandEntityReferences(boolean expandEntityRef)

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

this is set to true

Parameters:

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

setIgnoringComments(boolean)

public void setIgnoringComments(boolean ignoreComments)

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

false

setIgnoringElementContentWhitespace(boolean)

public void setIgnoringElementContentWhitespace(boolean whitespace)

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.Parameters:

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

parsing XML documents; false otherwise.

setNamespaceAware(boolean)

public void setNamespaceAware(boolean awareness)


46/148


setValidating(boolean)

46

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

value of this is set to false

Parameters:

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


public void setValidating(boolean validating)

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.

Parameters:

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


47/148

javax.xml.parsers FactoryConfigurationError


47

javax.xml.parsers

FactoryConfigurationError

Syntaxpublic class FactoryConfigurationError extends java.lang.Error

java.lang.Object

|

+--java.lang.Throwable

|

+--java.lang.Error

|

+--javax.xml.parsers.FactoryConfigurationError

All Implemented Interfaces: java.io.Serializable

Description

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.

Since: JAXP 1.0

Member Summary

Constructors

public FactoryConfigurationError()48Create a new FactoryConfigurationErrorwith no detail mesage.

publicFactoryConfigurationError(Exception)

48Create a new FactoryConfigurationErrorwith a given Exception base

cause of the error.

public FactoryConfigurationError(Exception, String)48Create a new FactoryConfigurationErrorwith the given Exception base

cause and detail message.

public FactoryConfigurationError(String)48Createa new FactoryConfigurationErrorwith theString specified as an

error message.

Methods

public Exception getException()49Return the actual exception (if any) that caused this exception to be raised.

public String getMessage()49Return the message (if any) for this error .


Methods inherited from class java.lang.Throwable


48/148

FactoryConfigurationError javax.xml.parsers

FactoryConfigurationError()

48

Constructors

FactoryConfigurationError()

public FactoryConfigurationError()

Create a new FactoryConfigurationError with no detail mesage.

FactoryConfigurationError(Exception)

public FactoryConfigurationError(java.lang.Exception e)

Create a new FactoryConfigurationError with a given Exception base cause of the error.

Parameters:

e - The exception to be encapsulated in a FactoryConfigurationError.

FactoryConfigurationError(Exception, String)

public FactoryConfigurationError(java.lang.Exception e, java.lang.String msg)

Create a new FactoryConfigurationError with the given Exception base cause and detail mes-

sage.

Parameters:

e - The exception to be encapsulated in a FactoryConfigurationError

msg - The detail message.

e - The exception to be wrapped in a FactoryConfigurationError

FactoryConfigurationError(String)

public FactoryConfigurationError(java.lang.String msg)

Create a new FactoryConfigurationError with the String specified as an error message.

Parameters:

msg - The error message for the exception.

fillInStackTrace, getLocalizedMessage, printStackTrace, printStackTrace, printStack-

Trace, toString


clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait



49/148

javax.xml.parsers FactoryConfigurationError

getException()

49

Methods

getException()

public java.lang.Exception getException()

Return the actual exception (if any) that caused this exception to be raised.

Returns: The encapsulated exception, or null if there is none.

getMessage()

public java.lang.String getMessage()

Return the message (if any) for this error . If there is no message for the exception and there is an encapsu-

lated exception then the message of that exception, if it exists will be returned. Else the name of the encap-

sulated exception will be returned.

Overrides: java.lang.Throwable.getMessage() in class java.lang.Throwable

Returns: The error message.


50/148

ParserConfigurationException javax.xml.parsers

getMessage()

50

javax.xml.parsers

ParserConfigurationException

Syntaxpublic class ParserConfigurationException extends java.lang.Exception

java.lang.Object

|

+--java.lang.Throwable

|

+--java.lang.Exception

|

+--javax.xml.parsers.ParserConfigurationException

All Implemented Interfaces: java.io.Serializable

Description

Indicates a serious configuration error.

Since: JAXP 1.0

Member Summary

Constructors

public ParserConfigurationException()51Create a new ParserConfigurationExceptionwith no detail mesage.

public ParserConfigurationException(String)51Create a new ParserConfigurationExceptionwith the String specified

as an error message.


Methods inherited from class java.lang.Throwable

fillInStackTrace, getLocalizedMessage, getMessage, printStackTrace, printStackTrace,

printStackTrace, toString


clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait


51/148

javax.xml.parsers ParserConfigurationException

ParserConfigurationException()

51

Constructors

ParserConfigurationException()

public ParserConfigurationException()

Create a new ParserConfigurationException with no detail mesage.

ParserConfigurationException(String)

public ParserConfigurationException(java.lang.String msg)

Create a new ParserConfigurationException with the String specified as an error message.

Parameters:

msg - The error message for the exception.


52/148

SAXParser javax.xml.parsers


52

javax.xml.parsers

SAXParser

Syntaxpublic abstract class SAXParser

java.lang.Object

|

+--javax.xml.parsers.SAXParser

Description

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

face as well as supporting new methods. An instance of this class can be obtained from the

newSAXParser()62 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.SAXParserFactory . 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.

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 underlying implementation can consider using the

org.xml.sax.helpers.ParserAdapter class to initially adapt their SAX1 impelemntation to work

under this revised class.

An implementation ofSAXParser isNOTguaranteed to behave as per the specification if it is used concur-

rently by two or more threads. It is recommended to have one instance of the SAXParser per thread or it is

upto the application to make sure about the use ofSAXParser from more than one thread.

Since: JAXP 1.0

Member Summary

Constructors

protected SAXParser()54

Methods

public abstract Parser getParser()54Returns the SAX parser that is encapsultated by the implementation of this class.

public abstract Object getProperty(String)54Returns the particular property requested for in the underlying implementation of

org.xml.sax.XMLReader .


53/148

javax.xml.parsers SAXParser


53

public abstract XML-

Reader

getXMLReader()54Returns the org.xml.sax.XMLReader that is encapsulated by the implementa-

tion of this class.


ean

isNamespaceAware()55Indicates whether or not this parser is configured to understand namespaces.

public abstract bool-ean

isValidating()55Indicates whether or not this parser is configured to validate XML documents.

public void parse(File, DefaultHandler)55Parse the content of the file specified as XML using the specified

org.xml.sax.helpers.DefaultHandler .

public void parse(File, HandlerBase)55Parse the content of the file specified as XML using the specified

org.xml.sax.HandlerBase .

public void parse(InputSource, DefaultHandler)56Parse the content given org.xml.sax.InputSource as XML using the speci-

fied org.xml.sax.helpers.DefaultHandler .

public void parse(InputSource, HandlerBase)56Parse the content given org.xml.sax.InputSource as XML using the speci-

fied org.xml.sax.HandlerBase .

public void parse(InputStream, DefaultHandler)56Parse the content of the given java.io.InputStream instance as XML using

the specified org.xml.sax.helpers.DefaultHandler .

public void parse(InputStream, DefaultHandler, String)57Parse the content of the given java.io.InputStream instance as XML using

the specified org.xml.sax.helpers.DefaultHandler .

public void parse(InputStream, HandlerBase)57Parse the content of the given java.io.InputStream instance as XML using

the specified org.xml.sax.HandlerBase .

public void parse(InputStream, HandlerBase, String)57Parse the content of the given java.io.InputStream instance as XML using

the specified org.xml.sax.HandlerBase .

public void parse(String, DefaultHandler)58Parse the content described by the giving Uniform Resource Identifier (URI) as XML

using the specified org.xml.sax.helpers.DefaultHandler .

public void parse(String, HandlerBase)58Parse the content described by the giving Uniform Resource Identifier (URI) as XML

using the specified org.xml.sax.HandlerBase .

public abstract void setProperty(String, Object)59Sets the particular property in the underlying implementation of





wait

Member Summary


54/148


SAXParser()

54

Constructors

SAXParser()

protected SAXParser()

Methods

getParser()

public abstract org.xml.sax.Parser getParser()

Returns the SAX parser that is encapsultated by the implementation of this class.

Returns: The SAX parser that is encapsultated by the implementation of this class.

Throws:SAXException

getProperty(String)

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

throws SAXNotRecognizedException, SAXNotSupportedException

Returns the particular property requested for in the underlying implementation of


Parameters:

name - The name of the property to be retrieved.

Returns: Value of the requested property.

Throws:

SAXNotRecognizedException - When the underlying XMLReader does not recognize the

property name.

SAXNotSupportedException - When the underlying XMLReader recognizes the property name

but doesnt support the property.

See Also: org.xml.sax.XMLReader.getProperty(String)

getXMLReader()

public abstract org.xml.sax.XMLReader getXMLReader()

Returns the org.xml.sax.XMLReader that is encapsulated by the implementation of this class.

Returns: The XMLReader that is encapsulated by the implementation of this class.

Throws:

SAXException


55/148

javax.xml.parsers SAXParser

isNamespaceAware()

55

isNamespaceAware()

public abstract boolean isNamespaceAware()

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

Returns: true if this parser is configured to understand namespaces; false otherwise.

isValidating()

public abstract boolean isValidating()

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

Returns: true if this parser is configured to validate XML documents; false otherwise.

parse(File, DefaultHandler)

public void parse(java.io.File f, org.xml.sax.helpers.DefaultHandler dh)

throws IOException, IllegalArgumentException

Parse the content of the file specified as XML using the specified


Parameters:

f - The file containing the XML to parse

dh - The SAX DefaultHandler to use.

Throws:


IllegalArgumentException - If the File object is null.

SAXException


parse(File, HandlerBase)

public void parse(java.io.File f, org.xml.sax.HandlerBase hb)


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

cated in SAX 2.0

Parameters:

f - The file containing the XML to parse

hb - The SAX HandlerBase to use.

Throws:


IllegalArgumentException - If the File object is null.

SAXException



56/148


parse(InputSource, DefaultHandler)

56

parse(InputSource, DefaultHandler)

public void parse(org.xml.sax.InputSource is, org.xml.sax.helpers.DefaultHandler dh)


Parse the content given org.xml.sax.InputSource as XML using the specified


Parameters:

is - The InputSource containing the content to be parsed.

dh - The SAX DefaultHandler to use.

Throws:


IllegalArgumentException - If the InputSource is null.

SAXException


parse(InputSource, HandlerBase)

public void parse(org.xml.sax.InputSource is, org.xml.sax.Han

Documents

Java API for XML