Find JSRs
Submit this Search

Ad Banner

JSRs: Java Specification Requests
JSR 102: JDOM 1.0

This JSR has been Withdrawn
Reason: Withdrawn at the request of the Specification Lead.

Original Java Specification Request (JSR)

Identification | Request | Contributions | Additional Information

Submitting Member: Jason Hunter

Name of Contact Person: Jason Hunter

E-Mail Address:

Telephone Number: (650) 938-2824

Fax Number: (650) 938-2824

Specification Lead: Jason Hunter

E-Mail Address:

Telephone Number: (650) 938-2824

Fax Number: (650) 938-2824

Initial Expert Group Membership:

People and organizations who have agreed to join before the CAFE:

  • Brett McLaughlin (individual, from Lutris)
  • Jools Enticknap (individual, software consultant)
  • James Davidson (individual, from Sun Microsystems and an Apache member)
  • Joe Bowbeer (individual, from
  • Philip Nelson (individual, from Omni Resources)
  • Sun Microsystems (Rajiv Mordani)

Section 2: Request

2.1 Please describe the proposed Specification:

JDOM 1.0 will define an API for easy and efficient reading, manipulation, and writing of XML documents and XML data. JDOM is already a popular open source product in beta release at, and with this JSR we hope to define its final 1.0 form. Among the goals for the JDOM JSR:

  • JDOM should be optimized for Java. It should use the full power of the Java 2 Platform (collections, reflection, and method overloading) so that JDOM feels natural and straightforward to Java programmers.
  • JDOM should hide the complexities of XML wherever possible. Developers should not need to be XML experts.
  • JDOM should integrate well with DOM and SAX. In addition to reading and writing to/from files, JDOM documents should be buildable from both DOM and SAX sources, and should be outputtable to both DOM and SAX consumers.
  • JDOM should have a run-time pluggable parser architecture so any DOM or SAX implementation may be used. JAXP should also be supported, but should not be required.
  • JDOM should ensure that documents in memory are always well-formed. Element names, text content, parentage hierarchies, and so on should be checked on build so documents are never allowed to violate the well-formedness constraints of the XML specification.
  • JDOM should be designed to allow a comparatively lightweight and fast implementation.
  • JDOM should stay current and interact with the latest XML standards: DOM Level 2, SAX 2.0, XML Schema.
  • JDOM need not to solve every possible problem. Some problems might be better solved by SAX or by DOM, and that's fine. A rule of thumb is that JDOM should solve 80% of Java programmer problems with 20% of the standard effort. This idea is similar to that followed by the Java language.
  • JDOM should not attempt to be an "XML parser" or "XML processor"; rather it should use XML parsers and processors to enable convenient input and output.

Nearly all these goals are satisfied in the latest JDOM snapshot. What remains to be done is clarifying how entities are to work, checking for overlooked requirements, polishing rough areas in the API, and getting additional industry buy-in.

2.2 What is the target Java platform? (i.e., desktop, server, personal, embedded, card, etc.)

This facility is targeted for use by the Java 2 Standard Edition and Java 2 Enterprise Edition platforms.

2.3 What need of the Java community will be addressed by the proposed specification?

This will create a model for interacting with XML data that is optimized for the Java environment. The "Quotes" page at shows how the beta releases has addressed the Java community's needs.

2.4 Why isn't this need met by existing specifications?

The most similar existing specification is the DOM. Compared to the DOM, JDOM is easier to use, on many tasks requires less memory and performs faster, has more natural handling of namespaces, and at runtime fully ensures documents are well formed. JDOM can read and write DOM to support applications depending on DOM.

Another similar specification is SAX. Compared to SAX, JDOM allows random access to XML data as well as manipulation and output of the XML data. JDOM can read and write SAX events to support applications depending on SAX.

2.5 Please give a short description of the underlying technology or technologies:

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. It is expected that this specification will endorse version 1.0 of the XML Recommendation.

XML Namespaces define the syntax and semantics for XML structures required to be distinct from other XML markup. In particular it defines a mechanism whereby a set of XML markup may have a distinguishing
"namespace" associated with it. It is expected that this specification will endorse version 1.0 of the XML Namespaces Recommendation.

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 (sometimes referred to as a callback-style) interface to the process of parsing an XML document. It is anticipated that this specification will endorse version 2.0 of the API.

The Document Object Model (DOM) describes facilities for a programmatic representation of a parsed XML document. The DOM specification defines these interfaces using Interface Definition Language (IDL) in a language independent fashion and also includes a Java Language Binding. It is anticipated that this specification will endorse Level 2 of the specification.

The Java API for XML Parsing (JAXP) defines a set of implementation independent portable APIs to support XML processing. It is anticipated that this specification will endorse version 1.1 of the API.

2.6 Is there a proposed package name for the API Specification? (i.e., javapi.something, org.something, etc.)

Currently the packages are defined in org.jdom. A proposed javax namespace package name would be javax.xml.tree.

2.7 Does the proposed specification have any dependencies on specific operating systems, CPUs, or I/O devices that you know of?


2.8 Are there any security issues that cannot be addressed by the current security model?


2.9 Are there any internationalization or localization issues?

XML itself was designed from the ground up to address such issues. A requirement of the proposed specification is that it preserve the inherent internationalizability of XML and related technologies.

2.10 Are there any existing specifications that might be rendered obsolete, deprecated, or in need of revision as a result of this work?


2.11 Please describe the anticipated schedule for the development of this specification.

Initiation: Februrary 2001
Community Review: April 2001
Public Review: June 2001
Final Draft Proposal: August 2001

Further schedule will depend on the review process.

Section 3: Contributions

3.1 Please list any existing documents, specifications, or implementations that describe the technology. Please include links to the documents if they are publicly available.

The JDOM website ( contains a pre-release implementation, API Javadocs, a technical FAQ, as well as links to JavaWorld articles and conference slides describing the technology.

3.2 Explanation of how these items might be used as a starting point for the work.

The existing JDOM library will be the starting point for this JSR.

Section 4: Additional Information (Optional)

4.1 This section contains any additional information that the submitting Member wishes to include in the JSR.

Although I'm the Apache Executive Committee representative, I submit this JSR as an individual because JDOM is not an Apache project. In making this proposal I do have the support of my employer (CollabNet), as well as the co-creator of JDOM (Brett McLaughlin) and the 950 developers on the jdom-interest mailing list at