jsr 280: xml api for java me - version 1 - oracle · 2014-04-29 · jsr 280: xml api for java tm me...

JSR 280: XML API for JavaTM ME

Final Release

Version 1.0 - June 19th, 2007

Sun Microsystems, Inc.4050 Network CircleSanta Clara, CA 95054Phone: 1-800-555-9SUNSend comments about this document to: [email protected]

Specification: JSR-280 XML API for JavaTM ME ("Specification")

Version: 1.0Status: Final ReleaseRelease: 19 June 2007

Copyright 2007 SUN MICROSYSTEMS, INC.4150 Network Circle, Santa Clara, California 95054, U.S.AAll rights reserved.

LIMITED LICENSE GRANTS

1. License for Evaluation Purposes. Sun hereby grants you a fully-paid, non-exclusive, non-transferable, worldwide, limited license (without the rightto sublicense), under Sun’s applicable intellectual property rights to view, download, use and reproduce the Specification only for the purpose ofinternal evaluation. This includes (i) developing applications intended to run on an implementation of the Specification, provided that suchapplications do not themselves implement any portion(s) of the Specification, and (ii) discussing the Specification with any third party; and (iii)excerpting brief portions of the Specification in oral or written communications which discuss the Specification provided that such excerpts do not inthe aggregate constitute a significant portion of the Specification.

2. License for the Distribution of Compliant Implementations. Sun also grants you a perpetual, non-exclusive, non-transferable, worldwide, fullypaid-up, royalty free, limited license (without the right to sublicense) under any applicable copyrights or, subject to the provisions of subsection 4below, patent rights it may have covering the Specification to create and/or distribute an Independent Implementation of the Specification that: (a)fully implements the Specification including all its required interfaces and functionality; (b) does not modify, subset, superset or otherwise extend theLicensor Name Space, or include any public or protected packages, classes, Java interfaces, fields or methods within the Licensor Name Space otherthan those required/authorized by the Specification or Specifications being implemented; and (c) passes the Technology Compatibility Kit (includingsatisfying the requirements of the applicable TCK Users Guide) for such Specification ("Compliant Implementation"). In addition, the foregoinglicense is expressly conditioned on your not acting outside its scope. No license is granted hereunder for any other purpose (including, for example,modifying the Specification, other than to the extent of your fair use rights, or distributing the Specification to third parties). Also, no right, title, orinterest in or to any trademarks, service marks, or trade names of Sun or Sun’s licensors is granted hereunder. Java, and Java-related logos, marks andnames are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

3. Pass-through Conditions. You need not include limitations (a)-(c) from the previous paragraph or any other particular "pass through" requirementsin any license You grant concerning the use of your Independent Implementation or products derived from it. However, except with respect toIndependent Implementations (and products derived from them) that satisfy limitations (a)-(c) from the previous paragraph, You may neither: (a)grant or otherwise pass through to your licensees any licenses under Sun’s applicable intellectual property rights; nor (b) authorize your licensees tomake any claims concerning their implementation’s compliance with the Specification in question.

4. Reciprocity Concerning Patent Licenses.

a. With respect to any patent claims covered by the license granted under subparagraph 2 above that would be infringed by all technically feasibleimplementations of the Specification, such license is conditioned upon your offering on fair, reasonable and non-discriminatory terms, to any partyseeking it from You, a perpetual, non-exclusive, non-transferable, worldwide license under Your patent rights which are or would be infringed by alltechnically feasible implementations of the Specification to develop, distribute and use a Compliant Implementation.

b With respect to any patent claims owned by Sun and covered by the license granted under subparagraph 2, whether or not their infringement can beavoided in a technically feasible manner when implementing the Specification, such license shall terminate with respect to such claims if You initiate aclaim against Sun that it has, in the course of performing its responsibilities as the Specification Lead, induced any other entity to infringe Your patentrights.

c Also with respect to any patent claims owned by Sun and covered by the license granted under subparagraph 2 above, where the infringement ofsuch claims can be avoided in a technically feasible manner when implementing the Specification such license, with respect to such claims, shallterminate if You initiate a claim against Sun that its making, having made, using, offering to sell, selling or importing a Compliant Implementationinfringes Your patent rights.

5. Definitions. For the purposes of this Agreement: "Independent Implementation" shall mean an implementation of the Specification that neitherderives from any of Sun’s source code or binary code materials nor, except with an appropriate and separate license from Sun, includes any of Sun’ssource code or binary code materials; "Licensor Name Space" shall mean the public class or interface declarations whose names begin with "java","javax", "com.sun" or their equivalents in any subsequent naming convention adopted by Sun through the Java Community Process, or anyrecognized successors or replacements thereof; and "Technology Compatibility Kit" or "TCK" shall mean the test suite and accompanying TCK User’sGuide provided by Sun which corresponds to the Specification and that was available either (i) from Sun’s 120 days before the first release of YourIndependent Implementation that allows its use for commercial purposes, or (ii) more recently than 120 days from such release but against which Youelect to test Your implementation of the Specification.

This Agreement will terminate immediately without notice from Sun if you breach the Agreement or act outside the scope of the licenses grantedabove.

DISCLAIMER OF WARRANTIES

THE SPECIFICATION IS PROVIDED "AS IS". SUN MAKES NO REPRESENTATIONS OR WARRANTIES, EITHER EXPRESS OR IMPLIED,INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT(INCLUDING AS A CONSEQUENCE OF ANY PRACTICE OR IMPLEMENTATION OF THE SPECIFICATION), OR THAT THE CONTENTS OF THESPECIFICATION ARE SUITABLE FOR ANY PURPOSE. This document does not represent any commitment to release or implement any portion ofthe Specification in any product. In addition, the Specification could include technical inaccuracies or typographical errors.

LIMITATION OF LIABILITY

TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY DAMAGES, INCLUDINGWITHOUT LIMITATION, LOST REVENUE, PROFITS OR DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVEDAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF OR RELATED IN ANY WAY TO YOURHAVING, IMPELEMENTING OR OTHERWISE USING USING THE SPECIFICATION, EVEN IF SUN AND/OR ITS LICENSORS HAVE BEENADVISED OF THE POSSIBILITY OF SUCH DAMAGES.You will indemnify, hold harmless, and defend Sun and its licensors from any claims arising or resulting from: (i) your use of the Specification; (ii) theuse or distribution of your Java application, applet and/or implementation; and/or (iii) any claims that later versions or releases of any Specificationfurnished to you are incompatible with the Specification provided to you under this license.

RESTRICTED RIGHTS LEGEND

U.S. Government: If this Specification is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime contractor orsubcontractor (at any tier), then the Government’s rights in the Software and accompanying documentation shall be only as set forth in this license; thisis 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 (fornon-DoD acquisitions).

REPORT

If you provide Sun with any comments or suggestions concerning the Specification ("Feedback"), you hereby: (i) agree that such Feedback is providedon a non-proprietary and non-confidential basis, and (ii) grant Sun a perpetual, non-exclusive, worldwide, fully paid-up, irrevocable license, with theright to sublicense through multiple levels of sublicensees, to incorporate, disclose, and use without limitation the Feedback for any purpose.

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 InternationalSale 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 complystrictly with all such laws and regulations and acknowledges that it has the responsibility to obtain such licenses to export, re-export or import as maybe required after delivery to Licensee.

This Agreement is the parties’ entire agreement relating to its subject matter. It supersedes all prior or contemporaneous oral or writtencommunications, 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 thisAgreement will be binding, unless in writing and signed by an authorized representative of each party.

Rev. April, 2006

Contents

1. Goals 1

1.1 Overall Goal 1

1.2 Main Goals and Deliverables 1

1.2.1 Core Package 2

1.2.2 Events Package 2

1.3 Platform Requirements 3

1.4 Use Cases 3

1.5 Requirements 5

2. JAXP Subset 7

2.1 Introduction 7

2.2 JAXP Subset Details 7

2.2.1 Extensions to JSR 172 JAXP API 7

2.2.2 Requirements 7

2.2.3 Package javax.xml.parsers 8

2.3 Validating Parser Support 8

2.4 Non-validating Parser Support 9

2.5 Conformance Requirements 9

3. SAX Subset 11

3.1 Introduction 11

3.2 SAX Subset Details 11

3.2.1 Extensions to JSR 172 SAX Subset 12

3.2.2 Package org.xml.sax 12

3.2.3 Package org.xml.sax.ext 13

3.2.4 Package org.xml.sax.helpers 13

XML API for Java ME v

4. StAX Subset Overview 15

4.1 Introduction 15

4.2 StAX Subset Details 15

4.2.1 Package javax.xml.stream 16

4.3 Differences from JSR 173 API 17

4.3.1 JSR 173 Proposed Java ME Subset 17

4.3.2 XMLStreamReader Methods 17

4.3.3 XMLStreamWriter Methods 18

4.3.4 XMLInputFactory Properties 18

4.3.5 Other Modifications 18

4.4 Extensions to JSR 173 19

5. DOM Core Subset 21

5.1 Introduction 21

5.2 DOM Core 21

6. DOM Events Optional Package 25

6.1 DOM Events 25

6.1.1 DOM Events Core Interfaces 26

6.1.2 DOM UIEvents and Views 27

A. References 31

XML API for Java ME vi

Preface

Preface

This document specifies the XML API for the JavaTM Micro Edition (JavaTM ME) Platform.The specification has been developed under the Java Community Process (JCP) version 2.6as Java Specification Request 280 (JSR 280), XML API for JavaTM ME. Further details on thisspecification in relation to the JCP can be found at http://jcp.org/en/jsr/detail?id=280.

Expert Group■ Jean-Yves Bitterlich, Sun Microsystems, Inc. (specification lead)

■ Pia Niemela, Nokia Corporation (specification lead)

■ Aleem Baig, Nokia Corporation

■ Vivek Chopra

■ Michael Krivoruchko, Sun Microsystems, Inc.

■ Changshin Lee, Tmax Soft, Inc.

■ Hideyuki Otokawa, Sharp Corporation

■ Michael Shenfield, Research In Motion, LTD (RIM)

■ Ellen Siegel (specification lead until March 2007)

■ Aleksander Slominski

■ Norman Walsh, Sun Microsystems, Inc.

FeedbackPlease send comments and feedback on this specification to [email protected].

XML API for Java ME vii

Preface

XML API for Java ME viii

Goals Overall Goal

1

Goals

1.1 Overall GoalThis JSR is designed to provide a general purpose XML API for the next generation of mobiledevices. XML has become the data format of choice for many different applications, from webservices data encoding to data serialization. Although a few XML API subsets have beenincluded in existing JSRs, these have tended to be domain specific and fragmented. This JSRdefines a comprehensive core subset relevant across application domains, enabling domainspecific JSRs to define only domain-specific extensions on an as-needed basis.

The JSR 280 XML APIs include JavaTM Platform Micro Edition (Java TM ME) subsets of:

■ Simple API for XML (SAX) event handler-based parsing

■ JavaTM API for XML Processing (JAXP)

■ Streaming API for XML (StAX)

■ Document Object Model (DOM) Core

■ DOM Events, UI Events and Views (provided in a separate optional package)

The intention behind the 280 API is to support applications as varied as web services, XMLmessaging, and Web browsers on mobile devices. In addition, this JSR is being developed inclose alignment with JSR 279, Service Connection API for Java ME.

Target devices will have substantially more memory and processing power than many currentMIDP devices, but will still be limited compared with most desktop or notebook computers.

The proposed XML API is derived by taking strict subsets of existing API specifications. It alsomaintains backwards compatibility with key existing Java ME subsets in order to enable asmooth transition for existing applications.

1.2 Main Goals and DeliverablesThe main deliverables of the JSR 280 specification are two Java ME Optional Packages whichtogether provide a general purpose XML API for Java ME.

XML API for Java ME 1

Main Goals and Deliverables Goals

Core Package

1.2.1 Core PackageThe Core Package adds enhanced general purpose XML parsing support to the Java MEplatform, and must be fully implemented by all compliant JSR 280 implementations. It containsthe following components

1. System properties javax.microedition.xmlapi.version andjavax.microedition.xmlapi.events.version

The system property javax.microedition.xmlapi.version defines the version ofthe Core Package. The value of this property for the initial version of this specification is"1.0". This property MUST be present and set to "1.0" in compliant JSR 280implementations.

The system property javax.microediton.xmlapi.events.version defines theversion of the Events Package. The value of this property for the initial version of thespecification is "1.0". This property MUST be present and set to "1.0" if the Events Packageis implemented; if the Events Package is not implemented, the property MUST beundefined.

2. Java API for XML Processing (JAXP)

This specification includes a subset of the JSR 63 JAXP 1.2[15] APIs that is backwardscompatible with that in the XML Parsing optional package of JSR 172 (J2ME Web ServicesSpecification)[12]. The JSR 280 subset adds some SAX 2.0 extensions as well as the JAXPAPIs for DOM bootstrapping and parsing.

3. Simple API for XML (SAX) 2.0 Parsing

The SAX 2.0 Parsing API is a strict subset of the SAX 2.0 specification[18]. It is backwardscompatible with the SAX API of the XML Parsing optional package of JSR 172[12], withsome enhancements.

4. Streaming API for XML (StAX)

This specification includes a Java ME subset of the JSR 173 Streaming API for XML (StAX)[23]. The subset defined in this JSR differs from the Java ME subset proposed in the JSR173 specification, although it remains a strict subset.

5. Document Object Model (DOM) Core

This specification includes support for DOM Level 2 Core[3] and XML modules with someextensions from DOM Level 3 Core[8].

In combination with the DOM Events support described in the next section, the JSR 280DOM subset is backwards compatible with the Scalable 2D Vector Graphics API for J2ME(JSR 226)[19] and should support the Scalable 2D Vector Graphics API 2.0 for Java ME(JSR 287)[20] and the JavaTM Language & XML User Interface Markup Integration (JSR290)[14].

1.2.2 Events PackageThe JSR 280 Events Package defines a Java ME subset of DOM Events and Views. CompliantJSR 280 implementations MUST implement either all or none of the Events Package. If thepackage is implemented, compliant implementations MUST include the system propertyjavax.microediton.xmlapi.events.version (see below).


Goals Platform Requirements

Events Package

The Events Package contains the following components:

1. System Property javax.microedition.xmlapi.events.version

As defined in the Core Package, the system propertyjavax.microediton.xmlapi.events.version defines the version of the EventsPackage when it is implemented. The value of this property for the initial version of thespecification is "1.0". This property MUST be present and set to "1.0" if the EventsPackage is implemented; if the Events Package is not implemented, the property MUST beundefined.

2. Document Object Model (DOM) Events

This specification includes full support for DOM Level 2 Events[5], with extensions fromDOM Level 3 Events[10] sufficient to support JSRs 287[20] and 290[14].

3. Document Object Model (DOM) Views

This specification includes full support for DOM Level 2 Views.

1.3 Platform RequirementsIn order to provide implementations that are useful on the widest possible range ofconfigurations and profiles, this specification is treating the Connected Limited DeviceConfiguration (CLDC) 1.1[2] as the lowest common denominator platform1. The target size fora complete implementation of the JSR 280 Core Package is 175 kB.

Size is defined as being the sum of the uncompressed Java classfiles required for both theinterface definitions and their implementations.

1.4 Use CasesThe XML API for Java ME is intended to be a general purpose XML API, supporting a rangeof applications. The use cases thus cover a range of application types.

1. Mobile Web Services Client

A mobile Web services client application interacts with a Web service (using SOAP, HTTPparameters, REST, etc.) to retrieve either a SOAP response or other XML encoded data-forexample, stock quotes or other search results.

1.The StAX API depends on java.lang.IllegalStateException, which is not in CLDC but is in MIDP. JSR 280 implementationsfor CLDC 1.1 platforms without MIDP must therefore implement this exception class. This exception exists in the CDC plat-form.


Use Cases Goals

Events Package

2. Support for Streaming XML or “pull parsing”

Many application developers find the streaming, or “pull parsing” application modelattractive. In order to provide a comprehensive XML parsing API for Java ME, thisspecification includes a Java ME subset of the JSR 173[23] API. For example, a userrequesting an Amazon.com search should be able to stop parsing the response XMLdocument once a desired result is reached.

3. Parsing specific XML grammars

The JSR 280 API should not preclude parsing documents using specific XML grammars,such as a Really Simple Syndication (RSS) or Atom syndication format compliant XMLdocument from a news aggregator or blog. For example, a blog reader or news readerapplication should be able to use the JSR 280 API to parse RSS or Atom formatted blogentries.

4. Parsing SOAP envelopes including e.g. digital signatures

Applications using digital signatures or other constructs requiring cryptography and/orcanonicalization can use the JSR 280 APIs in combination with APIs of other relevant JSRs(e.g. JSR 177 Security and Trust Services API for J2ME[21]). For example, a securepurchasing transaction might terminate with a signed transaction confirmation sent to thepurchaser in XML format. After the digital signature is checked, the client should be able touse JSR 280 APIs to parse the enclosed XML data.

5. Applications using XML with related technologies

e.g.

■ ECMAscript for XML (E4X, http://www.ecma-international.org/publications/standards/Ecma-357.htm),

■ AJAX (Asynchronous JavaScript and XML, http://en.wikipedia.org/wiki/AJAX)

6. XML Parsing Requirements of other JSRs

The XML API for Java must contain sufficient functionality to support a compliantimplementation of JSR 279 (Service Connection API for Java ME)[22], the Scalable 2DVector Graphics API for J2ME (JSR 226)[19], the Web Services package of JSR 172[12],the Scalable 2D Vector Graphics API 2.0 for Java ME[20], or the Java Language & XMLUser Interface Markup Integration[14].

7. Applications using JSR 279

The XML API for Java should contain sufficient functionality to support a typicalapplication using the JSR 279[22] API to access XML data.


Goals Requirements

Events Package

1.5 RequirementsThe specification of JSR 280 is composed jointly of this document and the associated APIdocumentation.


Requirements Goals

Events Package

Requirement Description

JSR280-1 The JSR 280 API MUST be implementable on CLDC 1.1[2]].[Note: the StAX API depends onjava.lang.IllegalStateException, which is not in CLDC butis in MIDP[17]. JSR 280 implementations for CLDC 1.1platforms without MIDP must therefore implement thisexception class.]

JSR280-2 The JSR 280 API MUST be implementable on CDC 1.1 [1]

JSR280-3 JSR 280 API resource requirements (memory, processingspeed) MUST be compatible with CLDC 1.1 devicecapabilities

JSR280-3.1 The JSR 280 Core package MUST be implementable in 175kROM.

JSR280-4 The JSR 280 API MUST be backwards compatible with theXML parsing package of JSR 172 [12].

JSR280-5 The JSR 280 API MUST include a proper subset of the DOM2 API [3] suitable for DOM processing on devices, withselected DOM 3 [8] extensions.

JSR280-5.1 This subset MUST be a superset of the subset in JSR 226[19]].

JSR280-5.2 The specification MUST include support for xml:id.XML:id[27] is used by Liberty[16].

JSR280-5.3 The specification MUST provide a DOM Events subset sufficientto support JSRs 287[20] and 290[14]. The Events[5][10] andViews[7] are provided as an Events optional package.

JSR280-6 The JSR 280 API must be sufficient to support the XMLrequirements of a compliant JSRs 279[22], 287[20], or 290[14]implementation.

JSR280-7 The implementation SHOULD fail gracefully if devicememory is exceeded by large XML documents

JSR280-8 Implementations MUST provide the system propertyjavax.microedition.xmlapi.version to define the version of theJSR 280 Core Package. The value of this property MUST be"1.0" for the initial version of the JSR 280 specification..

JSR 280-9 Implementations including the JSR 280 Events Package MUSTprovide the system propertyjavax.microedition.xmlapi.events.version todefine the version. The value of this property MUST be "1.0"for the initial version of the JSR 280 specification. If theEvents Package is not implemented, thejavax.microedition.xmlapi.events.versionproperty MUST be undefined.


JAXP Subset Introduction

Extensions to JSR 172 JAXP API

2

JAXP Subset

2.1 IntroductionThe JAXP API defined in this specification is a strict subset of the JAXP 1.2[15] specification,and extends the JAXP subset defined in JSR 172[12] by adding some additional SAX 2.0[18]interfaces and by adding interfaces to support the Document Object Model (DOM)[3][8].

The full JSR 280 JAXP API is detailed in the associated api documentation. This chapterhighlights key aspects only.

2.2 JAXP Subset Details

2.2.1 Extensions to JSR 172 JAXP API■ SAX 2.0 Interfaces

JSR 280 adds the following SAX 2.0[18] interfaces: XMLReader, ContentHandler,DTDHandler, EntityResolver, ErrorHandler, XMLFilter, and Attributes2.

Except for the addition of new functionality, this specification inherits the constraintsimposed by the JAXP subset defined in JSR 172[12] unless explicitly noted otherwise.

■ DOM Interfaces

JSR 280 provides DOM Level 2[3] support for Java ME, and therefore also extends the JSR-172 JAXP subset with support for DOM bootstrapping and parsing. There are two interfacesin this part of the JAXP API: DocumentBuilderFactory and DocumentBuilder.

2.2.2 RequirementsThe JSR 280 Core optional package defines a strict subset of the JAXP 1.2[15] specification.The following requirements define the functionality subset:


Validating Parser Support JAXP Subset

Package javax.xml.parsers

■ an implementation MUST NOT provide any support for the Simple API for XMLParsing (SAX) 1.0 interfaces

■ SAX 1.0 has been superseded by SAX 2.0 which is included.■ an implementation MUST NOT provide any support for Document Object Model

(DOM) Level 1.0.

■ DOM 1.0 has been superseded by DOM Level 2 and DOM Level 3, which are included■ an implementation MUST NOT provide any support for XSLT■ an implementation MUST support the SAX 2.0 subset defined in Chapter 3 of this

specification■ an implementation MUST support the DOM subset (Level 2 with specified Level 3

extensions) defined in Chapter 5 of this specification■ an implementation MUST provide support for XML namespaces [29]■ a parser implementation MUST provide support for both UTF-8 and UTF-16 encodings

2.2.3 Package javax.xml.parsersThe javax.xml.parsers package contains the Java API for XML Processing (JAXP)subset defined by JSR 280. It contains the following components:

2.2.3.1 Classes■ DocumentBuilder

■ DocumentBuilderFactory

■ SAXParser

■ SAXParserFactory

2.2.3.2 Exceptions■ ParserConfigurationException

2.2.3.3 Errors■ ParserConfigurationError

2.3 Validating Parser SupportAn implementation MAY support validation of XML documents against a DTD. XMLvalidation is an expensive process in terms of processing power and memory usage andmay not be supported on many Java ME devices. However, if the platform has the ability tosupport it, it MAY provide a validating parser either instead of or in addition to the default(non-validating) parser.

If an implementation provides a validating XML parser, that parser MUST conform to therequirements for Validating Parsers in section 5.1 of the XML 1.0 Specification [26].


JAXP Subset Non-validating Parser Support


2.4 Non-validating Parser SupportMost Java ME platforms will likely provide a non-validating XML parser.

If an implementation provides a non-validating XML parser, it MUST conform to Section5.1 of the XML 1.0 Specification [26], which only requires implementations parse theinternal DTD subset:

“[non-validating parsers] are required to process all the declarations they read in theinternal DTD subset and in any parameter entity that they read, up to the first reference toa parameter entity that they do not read; that is to say, they must use the information inthose declarations to normalize attribute values, include the replacement text of internalentities, and supply default attribute values. Except when standalone=”yes“, they must notprocess entity declarations or attribute-list declarations encountered after a reference to aparameter entity that is not read, since the entity may have contained overridingdeclarations.”

Although there is no requirement to parse external entities, the parser MUST notify theapplication of unparsed entities via the DefaultHandler method skippedEntity.

2.5 Conformance RequirementsIn order to achieve a predictable environment for applications, implementations of thisspecification must meet certain conformance requirements.

Implementations of this specification MUST be conformant to Section 5.1 of the XML 1.0specification[26]. In addition, implementations MUST be conformant to Section 6 of theXML Namespaces recommendation[29] as well as to the SAX 2.0[18] and JAXP 1.2[15]interfaces included in the JSR 280 API.


Conformance Requirements JAXP Subset



SAX Subset Introduction

3

SAX Subset

3.1 IntroductionJSR 280 provides a strict subset of the Simple API for XML (SAX) 2.0[18] API. The JSR 280SAX 2.0 subset is a backwards compatible extension of the SAX 2.0 API subset defined inJSR 172[12].

The full JSR 280 SAX API is detailed in the associated API documentation. This chapterhighlights key aspects only.

3.2 SAX Subset Details

FIGURE 3-1 Graphical Representation of JSR 280 SAX Subset

org.xml.sax.helpers

SAX 2.0

JSR 280 SAX API

org.xml.sax.ext

org.xml.sax


SAX Subset Details SAX Subset

Extensions to JSR 172 SAX Subset

3.2.1 Extensions to JSR 172 SAX Subset■ The JSR 280 SAX API adds the following interfaces to the SAX subset defined in JSR 172:

■ ContentHandler,

■ EntityResolver,

■ DTDHandler,

■ ErrorHandler,

■ XMLReader,

■ XMLFilter,

■ Attributes2.

■ The org.xml.sax.helpers.DefaultHandler has been updated to implementContentHandler, EntityResolver, DTDHandler, and ErrorHandler interfaces.

■ Since the parser now implements the XMLReader interface, the method getXMLReaderis added to javax.xml.parsers.SAXParser.

■ In order to support a subset of the standard JAXP SAXParserFactory bootstrapfunctionality on CDC, this specification adds support for thejavax.xml.parsers.SAXParserFactory system property.

3.2.2 Package org.xml.saxThe JSR 280 subset of the org.xml.sax package includes the following components.

3.2.2.1 Interfaces■ Attributes

■ ContentHandler

■ DTDHandler

■ EntityResolver

■ ErrorHandler

■ Locator

■ XMLFilter

■ XMLReader

3.2.2.2 Classes■ InputSource

3.2.2.3 Exceptions■ SAXException

■ SAXNotRecognizedException

■ SAXNotSupportedException

■ SAXParseException


SAX Subset SAX Subset Details

Package org.xml.sax.ext

3.2.3 Package org.xml.sax.extThe JSR 280 subset of the org.xml.sax.ext package includes the following components.

3.2.3.1 Interfaces■ Attributes2

3.2.4 Package org.xml.sax.helpersThe JSR 280 subset of the org.xml.sax.helpers package includes the following components.

3.2.4.1 Classes■ DefaultHandler


SAX Subset Details SAX Subset

Package org.xml.sax.helpers


StAX Subset Overview Introduction

4

StAX Subset Overview

4.1 IntroductionThe Streaming API for XML (StAX)[23] introduced by JSR 173 provides a popularprogramming model for sequential XML processing. This specification extends the JavaME[2] XML processing API to include a Java ME subset of the StAX API.

The StAX subset defined by this specification is similar to the subset proposed in JSR 173,but is not identical: parts of the API requiring functionality not currently provided by theJava ME[2] platform as well as some redundant functionalities have been removed. Inaddition, some extensions from JSR 173 Maintenance Release 1 have been added, inparticular those that make the StAX Cursor API more fully compliant with the XML 1.0specification[26]. Although the resulting subset differs from the subset proposed in the JSR173 specification, it is still a compatible subset of the full JSR 173 StAX API with theextensions contained in JSR 173 MR 1.

4.2 StAX Subset DetailsThe JSR 280 StAX API subset is implemented in package javax.xml.stream, and consists ofthe components described in the following subsections. A graphical representation of theJSR 280 StAX subset can be found below in Figure 4-1.


StAX Subset Details StAX Subset Overview

Package javax.xml.stream

FIGURE 4-1 Graphical Representation of JSR 280 StAX API

4.2.1 Package javax.xml.stream

4.2.1.1 Interfaces■ Location

■ StreamFilter

■ XMLResolver

■ XMLStreamConstants

■ XMLStreamReader

■ XMLStreamWriter

4.2.1.2 Classes■ XMLInputFactory

■ XMLOutputFactory

4.2.1.3 Exceptions■ XMLStreamException

JSR 173 StAX API

EventIterator API

Cursor API

JSR 280 StAX API

javax.xml.stream

javax.xml.stream.events


StAX Subset Overview Differences from JSR 173 API

JSR 173 Proposed Java ME Subset

4.2.1.4 Errors■ FactoryConfigurationError

4.3 Differences from JSR 173 API

4.3.1 JSR 173 Proposed Java ME SubsetJSR 173 proposes a subset of the StAX API for Java ME, but does not specify it in detail. Theclasses suggested in the JSR 173 specification are:

■ javax.xml.stream.XMLStreamReader

■ javax.xml.stream.XMLStreamWriter

■ javax.xml.stream.XMLStreamException

■ javax.xml.stream.Location

■ javax.xml.stream.XMLStreamConstants

By reference the following would also be required:

■ javax.xml.namespace.QName

■ javax.xml.namespace.NamespaceContext

■ javax.xml.XMLConstants

This specification adapts the StAX subset proposed by JSR 173 to align more closely withthe limitations of the Java ME platform. As with the Java ME subset proposed in the JSR173 specification, the Java ME StAX API in JSR 280 subsets only the StAX Cursor API: nopart of the StAX Event Iterator API is included in the Java ME StAX API.

Methods that require datatypes not provided by the Java ME platform have been removed,and methods and properties referencing functionality not available for Java ME have alsobeen removed. Removal of these methods and properties enable the specification tomaintain a strict subset relationship with the full StAX API: inclusion would requiremodifications to the API which would break the strict subset requirement, and whichwould therefore break backwards compatibility.

In the interest of streamlining, this specification also removes some methods which provideduplicate functionality.

In order to more closely parallel the JAXP API, this specification adds the XMLInputFactoryand XMLOutputFactory to the subset proposed in JSR 173.

4.3.2 XMLStreamReader MethodsThe following methods have been removed from XMLStreamReader

boolean hasName()

boolean hasText()

boolean isCharacters()

boolean isEndElement()


Differences from JSR 173 API StAX Subset Overview

XMLStreamWriter Methods

boolean isStartElement()

int getTextCharacters(int sourceStart, char[] target,

int targetStart, int length)

QName getAttributeName (int index)

QName getName ()

NamespaceContext getNamespaceContext ()

All of these methods with the exception of getNamespaceContext provide functionalitythat remains available via other existing methods.

Removing the ability to access a NamespaceContext means that it is no longerstraightforward to access Namespace prefixes for the entire stack via the getPrefixesmethod on the NamespaceContext object. The getPrefixes method returns an object oftype java.util.Iterator, and the Java ME platform does not support that type. In theinterest of maintaining a strict subset of the JSR 173 StAX API, it was decided to removeNamespaceContext entirely from the JSR 280 StAX subset rather than break compatibility:this way, the functionality can be added at a later date should it be deemed necessary.

4.3.3 XMLStreamWriter MethodsThe following methods have been removed from XMLStreamWriter:

NamespaceContext getNamespaceContext ()

void setNamespaceContext (NamespaceContext)

These methods have been removed to maintain consistency with the modifications toXMLStreamReader described in the previous subsection.

4.3.4 XMLInputFactory PropertiesThe following properties have been removed from XMLInputFactory:

javax.xml.stream.reporter

javax.xml.stream.allocator

The first property, reporter, is removed because XMLReporter is not supported in theJSR 280 StAX API. The final property, allocator, is removed because it is related to theEvent API which is also not included in this specification.

4.3.5 Other ModificationsAs per the reasoning in Section 4.3.2 “XMLStreamReader Methods” on page 17, the QNameand NamespaceContext interfaces have also been removed from the Java ME StAX subsetproposed by the JSR 173 specification.


StAX Subset Overview Extensions to JSR 173

Other Modifications

4.4 Extensions to JSR 173Although the EventIterator part of the StAX API[23] is XML compliant, the Cursor part ofthe API is not. Since the 280 StAX subset includes only the Cursor API, JSR 280 requiresextensions and clarifications to the JSR 173 Cursor API that would make it more fully XMLcompliant. These extensions and clarifications are published as part of JSR 173 MaintenanceRelease 1[23], and are incorporated into the JSR 280 StAX API.

These new extensions are provided in the form of a DTDStreamReader object and a fewextensions and clarifications to the XMLStreamReader. The DTDStreamReader objectenables forward, read-only access to general internal and external parsed and unparsedentity declarations, notation declarations, processing instructions and comments containedin a DTD. A DTDStreamReader object is instantiated using theXMLStreamReader.getProperty method with the string"javax.xml.stream.DTDStreamReader".

More detailed information on these extensions can be found in the JSR 280 APIdocumentation in the javax.xml.stream.DTDStreamReader andjavax.xml.stream.XMLStreamReader interface specifications, or in the change log forJSR 173 MR 1.


Extensions to JSR 173 StAX Subset Overview

Other Modifications


DOM Core Subset Introduction

5

DOM Core Subset

5.1 IntroductionThis specification defines a subset of the Document Object Model (DOM) specification thatis appropriate for the Java ME platform. The JSR 280 core DOM subset includes the DOM 2Core[3] interfaces, and adds selected DOM 3[8] extensions.

A subset of DOM 2 Events[5] (with selected DOM 3 Events[10] extensions) and Views APIsare added as an optional Events package.

5.2 DOM CoreThe org.w3c.dom package provides the Java ME DOM API defined by JSR 280. The API isderived from the W3 DOM 2 API1 Java bindings source[4], and the DOM 3 API2 Javabindings source[9]. The initial version of the JSR 280 modifications was published on 5 May2006.

JSR 280 includes all of the DOM 2 Core interfaces. It also integrates a small number of DOM3 extensions to the Core API.

If a parser expands entities, the information contained in the original Entity node becomesredundant. In the interest of footprint and performance, JSR 280 allows implementations toexclude Entity nodes corresponding to expanded entities from the DOM tree once theyhave been fully expanded by the parser.

1.W3C DOM Level 2 Java bindings are copyright © 2000 W3C®; (Massachusetts Institute of Technology,Institut National de Recherche en Informatique et en Automatique, Keio University), All Rights Reserved.This work is distributed under the W3C’s Software Intellectual Property License (http://www.w3.org/Con-sortium/Legal/) in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the im-plied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.2.W3C DOM Level 3 Java bindings are copyright © 2004 World Wide Web Consortium, (Massachusetts In-stitute of Technology, European Research Consortium for Informatics and Mathematics, Keio University).All Rights Reserved. This work is distributed under the W3C®; Software License [1] in the hope that it willbe useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILI-TY or FITNESS FOR A PARTICULAR PURPOSE. [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231


DOM Core DOM Core Subset

The DOM 3 Core extensions are summarized in Table 5-1; a graphical representation can befound in Figure 5-1.

FIGURE 5-1 Graphical Representation of JSR 280 DOM Core API

Interface DOM 3 Methods Added

Attr (DOM 2)

isID

Document (DOM 2)

adoptNode

DOMImplementation (DOM 2)

getFeature

Element (DOM 2)

setIdAttribute

setIdAttributeNS

setIdAttributeNode

Node (DOM 2)

getFeature

getUserData

setUserData

textContent

DOM 3 Core

JSR 280 Core Pkg

DOM 2 Core


DOM Core Subset DOM Core

TABLE 5-1 JSR 280 DOM 3 Core Extensions

Note – Note that ElementTraversal, although derived from the SVG Tiny 1.2 MicroDOM (uDOM) W3C specification, is newly included in the W3C DOM 3 draft specificationand has not yet gone through the W3C public review.The W3C specification is therefore tobe considered as work in progress. There may be some modifications to that specification thatwill be aligned in the JSR 280 Maintenance Release. The alignment is ruled by theagreement found at http://www.w3.org/Consortium/Legal/2007/03-license-JSR-final.html .

UserDataHandler (DOM 3)

handle

ElementTraversal (DOM 3)

getFirstElementChild

getLastElementChild

getNextElementSibling

getPreviousElementSibling

getChildElementCount

Interface DOM 3 Methods Added


DOM Core DOM Core Subset


DOM Events Optional Package DOM Events

6

DOM Events Optional Package

6.1 DOM EventsAlthough Events go slightly beyond core XML processing functionality, they are a keycomponent of certain types of processing. Since a key goal of this specification is to avoidduplication of XML components, it was decided to include DOM Events in the JSR 280Specification.

The org.w3c.dom.events package provides the Java ME DOM Events API defined by JSR280. The API is derived from the W3 DOM 2 Events API Java bindings1 source[6], and theDOM 3 Events API Java bindings2 source[11]. The initial version of the JSR 280modifications was published in October 2006.

The JSR 280 Events optional package fully supports the DOM Level 2 Events[5] andViews[7] APIs; selected DOM Level 3 Events[10] extensions are added in order to supportJSRs 287 and 290.

A graphical representation of the JSR 280 DOM Events and Views API can be found inTable 6-1.

1.W3C DOM Level 2 Events Java bindings are copyright © 2000 W3C®; (Massachusetts Institute of Tech-nology, Institut National de Recherche en Informatique et en Automatique, Keio University), All Rights Re-served. This work is distributed under the W3C’s Software Intellectual Property License (http://www.w3.org/Consortium/Legal/) in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even theimplied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

2.W3C DOM Level 3 Events Java bindings are copyright © 2004 World Wide Web Consortium, (Massachu-setts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio Univer-sity). All Rights Reserved. This work is distributed under the W3C®; Software License [1] in the hope thatit will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANT-ABILITY or FITNESS FOR A PARTICULAR PURPOSE. [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231


DOM Events DOM Events Optional Package

DOM Events Core Interfaces

FIGURE 6-1 Graphical Representation of JSR 280 Events API

6.1.1 DOM Events Core InterfacesTable 6-1 summarizes the core part of the DOM Events API in the JSR 280 Events optionalpackage, with the DOM 3 extensions highlighted. Note that the table is based on the IDLdefinition, where the presence of an attributes implies the presence of a corresponding getmethod in the Java binding.

DOM Event Core API Type in DOM 2 in DOM 3

Event Exception exception yes yes

DocumentEvent interface yes yes

createEvent method yes yes

canDispatch boolean no yes

EventTarget interface yes yes

addEventListener method yes yes

addEventListenerNS method no yes

removeEventListener method yes yes

removeEventListenerNS method no yes

dispatchEvent method yes yes

EventListenter interface yes yes

handleEvent method yes yes

Event interface yes yes

DOM 3 Events

JSR 280 EventsOptional Pkg

DOM 2 Events

DOM 2 Views



DOM UIEvents and Views

TABLE 6-1 JSR 280 DOM Event Core API

6.1.2 DOM UIEvents and ViewsDOM UIEvents are part of the org.w3c.dom.events package, but since they are logicallyseparate we discuss them in a separate subsection from the core events.

The org.w3c.dom.views package provides the Java ME DOM Views API defined by JSR 280.The API is derived from the W3 DOM 2 Views1 API[7]. The initial version of the JSR 280modifications was published in October 2006.

type attribute yes yes

target attribute yes yes

currentTarget attribute yes yes

namespaceURI attribute no yes

eventPhase attribute yes yes

bubbles attribute yes yes

cancelable attribute yes yes

defaultPrevented attribute no yes

timeStamp attribute yes yes

stopPropagation method yes yes

preventDefault method yes yes

initEvent method yes yes

initEventNS method no yes

Mutation Event interface yes yes

relatedNode attribute yes yes

prevValue attribute yes yes

newValue attribute yes yes

attrName attribute yes yes

attrChange attribute yes yes

initMutationEvent method yes yes

initMutationEventNS method no yes

CustomEvent interface no yes

detail attribute no yes

initCustomEventNS method no yes

DOM Event Core API Type in DOM 2 in DOM 3




The DOM UIEvents are a specific user interface related category of Event interfaces foundin the DOM Events package.

Table 6-2 summarizes the parts of the DOM UIEvents and Views API in the JSR 280 Eventsoptional package, with DOM 3 extensions highlighted.

Note – Note that MouseWheelEvent and ProgressEvent are newly included in theW3C DOM 3 draft specification and have not yet gone through the W3C public review.These W3C specifications are therefore to be considered as work in progress. There may besome modifications to these event types in the JSR 280 Maintenance Release to ensurealignment with the DOM 3 Event types. This alignment is ruled by the agreement found athttp://www.w3.org/Consortium/Legal/2007/03-license-JSR-final.html .

1. W3C DOM Level 2 Views Java bindings are copyright © 2000 W3C (Massachusetts Institute of Technol-ogy, Institut National de Recherche en Informatique et en Automatique, Keio University), All RightsReserved. This work is distributed under the W3C’s Software Intellectual Property License (http://www.w3.org/Consortium/Legal/) in the hope that it will be useful, but WITHOUT ANY WARRANTY;without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR-POSE.

DOM UIEvent and View API Type in DOM2 in DOM3

UIEvent interface yes yes

view attribute yes yes

detail attribute yes yes

initUIEvent method yes yes

initUIEventNS method no yes

MouseEvent interface yes yes

screenX attribute yes yes

screenY attribute yes yes

clientX attribute yes yes

clientY attribute yes yes

ctrlKey attribute yes yes

shiftKey attribute yes yes

altKey attribute yes yes

metaKey attribute yes yes

button attribute yes yes

relatedTarget attribute yes yes

initMouseEvent method yes yes

initMouseEventNS method no yes




TABLE 6-2 JSR 280 UIEvent and View API

TextEvent interface no yes

data attribute no yes

initTextEvent method no yes

initTextEventNS method no yes

KeyboardEvent interface no yes

keyIdentifier attribute no yes

keyLocation attribute no yes

ctrlKey attribute no yes

shiftKey attribute no yes

altKey attribute no yes

metaKey attribute no yes

initKeyboardEvent method no yes

initKeyboardEventNS method no yes

ProgressEvent interface no <yes>

lengthComputable attribute no <yes>

loaded attribute no <yes>

total attribute no <yes>

initProgressEvent method no <yes>

initProgressEventNS method no <yes>

MouseWheelEvent interface no <yes>

wheelDelta attribute no <yes>

initWheelEventNS method no <yes>

AbstractView interface yes yes

document attribute yes yes

DocumentView interface yes yes

defaultView attribute yes yes

DOM UIEvent and View API Type in DOM2 in DOM3


References

A

References

[1] CDC Connected Device Configuration (CDC)1.1: http://jcp.org/jsr/detail?id=218

[2] CLDC Connected, Limited Device Configuration 1.1: http://jcp.org/jsr/detail?id=139Java 2Micro Edition Platform: http://jcp.org/jsr/detail?id=68 and http://java.sun.com/j2me

[3] DOM 2 Core: http://www.w3.org/TR/DOM-Level-2-Core

[4] DOM 2 Core Java Bindings: http://www.w3.org/TR/DOM-Level-2-Core/java-binding.zip

[5] DOM 2 Events: http://www.w3.org/TR/DOM-Level-2-Events/

[6] DOM 2 Events Java Bindings: http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/java-binding.zip

[7] DOM 2 Views: http://www.w3.org/TR/DOM-Level-2-Views/

[8] DOM 3 Core: http://www.w3.org/TR/DOM-Level-3-Core

[9] DOM 3 Core Java Bindings: http://www.w3.org/TR/DOM-Level-3-Core/java-binding.zip

[10]DOM 3 Events: http://www.w3.org/TR/DOM-Level-3-Events/

[11]DOM 3 Events Java Bindings: http://www.w3.org/TR/2006/WD-DOM-Level-3-Events-20060413/java-binding.zip

[12]J2ME Web Services Specification: http://jcp.org/en/jsr/detail?id=172

[13]Java Language Specification: http://java.sun.com/docs/books/jls/

[14]Java Language & XML User Interface Markup Integration: http://jcp.org/en/jsr/detail?id=290

[15]JAXP 1.2 Java APIs for XML Processing: http://jcp.org/jsr/detail?id=63 and http://java.sun.com/xml/downloads/jaxp.html

[16]Liberty ID-WSF: https://www.projectliberty.org/liberty/content/download/893/6255/file/liberty-idwsf-security-mechanisms-core-v2.0.pdf

[17]Mobile Information Device Profile (MIDP) 2.0: http://jcp.org/jsr/detail?id=118

[18]SAX Simple API for XML: http://www.saxproject.org/

[19]Scalable 2D Vector Graphics API for J2ME: http://jcp.org/en/jsr/detail?id=226

[20]Scalable 2D Vector Graphics API 2.0 for Java ME: http://jcp.org/en/jsr/detail?id=287

[21]Security and Trust Services API for J2ME: http://jcp.org/en/jsr/detail?id=177


References

[22]Service Connection API for Java ME: http://jcp.org/en/jsr/detail?id=279

[23]Streaming API for XML (StAX): http://jcp.org/en/jsr/detail?id=173

[24]W3C Recommendation XML Schema Part 1: Structures: http://www.w3.org/TR/ xmlschema-1/

[25]W3C Recommendation XML Schema Part 2: Datatypes: http://www.w3.org/TR/ xmlschema-2/

[26]XML (eXtensible Markup Language): http://www.w3.org/TR/2000/REC-xml-20001006

[27]XML:id: http://www.w3.org/TR/2005/REC-xml-id-20050909/

[28]XML Information Set: http://www.w3.org/TR/2001/REC-xml-infoset-20011024/

[29]XML Namespaces 1.0 Recommendation: http://www.w3.org/TR/1999/REC-xml-names-19990114


jsr 280: xml api for java me - version 1 - oracle · 2014-04-29 · jsr 280: xml api for java tm me...

Documents