JDOM Java XML API

The jdom-contrib project contains extensions and auxiliary tools that increase the value of JDOM but are not part of the core distribution. Contributed code is organized under the org.jdom.contrib package hierarchy.

Key functional areas include:

• org.jdom.contrib.beans: Contains JDOMBean and related bean-related work.
• org.jdom.contrib.helpers: Contains various helper functions.
• org.jdom.contrib.ids: Demonstrates how to use JDOM's attribute type support to create documents that allow looking up elements via their ID attribute value.
• org.jdom.contrib.input: Contains builders for creating JDOM objects.
• org.jdom.contrib.output: Contains outputters for JDOM objects.
• org.jdom.contrib.schema: Provides code for in-memory schema validation.

JDOM provides attribute type support that allows you to look up elements using the value of their ID attribute.

Requirements: For an attribute to be recognized as an ID, the XML document must be associated with a DTD (Document Type Definition) that explicitly defines the type of those attributes.

Core Components:

• IdFactory: Used to build an IdDocument.
• IdDocument: A specialized document type that enables ID-based lookups.

To implement this, you must ensure your XML file is associated with a DTD (e.g., testIds.dtd) that defines which attributes are IDs.

If you use the Eclipse IDE, you can automatically configure your project with the correct source folders and referenced libraries by running the eclipse Ant target. After running the command, refresh your Eclipse project to resolve errors or warnings.

ant eclipse

The JDOM build system uses Apache Ant. To prepare your environment, ensure the JAVA_HOME environment variable is set to the top-level directory of your Java Development Kit (JDK).

# Windows
set JAVA_HOME=C:\jdk1.6

# Mac (csh)
setenv JAVA_HOME /System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home

# Mac (ksh, bash)
JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home; export JAVA_HOME

# Unix (csh)
setenv JAVA_HOME /usr/local/java

# Unix (ksh, bash)
JAVA_HOME=/usr/java; export JAVA_HOME

To use the ElementScanner package, you must include JDOM in your project along with the following dependencies in your application's classpath:

• Jakarta Regexp: version 1.1 or higher
• Jaxen: version 1.0 beta7 or higher

To build JDOM, you need Apache Ant 1.8.2 or later and Java JDK 1.6 or later.

1. Clone the repository from GitHub.
2. Navigate to the directory containing build.xml.
3. Run the ant command.

Successful builds generate a distribution zip file in the ./build/package directory following the pattern jdom-2.x-20yy.mm.dd.HH.MM.zip.

You can control the output filename and version by creating a build.properties file in the root directory with the following content:

version=2.0.0

The JElement class is a wrapper that allows you to interact with standard W3C DOM Element objects using the JDOM API. It implements the org.w3c.dom.Element interface while delegating core functionality to an underlying JDOM Element (referred to as the shadow).

Important Limitation: Read-Only Access JElement is designed as a read-only wrapper. Any attempt to modify the element via standard DOM mutation methods (such as setAttribute, removeAttribute, setAttributeNode, or setIdAttribute) will throw a DOMException with the code NO_MODIFICATION_ALLOWED_ERR and the message "JDOM Wrapper". Use the native JDOM API on the underlying JDOM objects for any modifications.

The TestIds.java program demonstrates how to build an IdDocument from an XML file and retrieve an element by its ID.

To use the sample, provide the path to an XML file (which must be associated with a DTD defining ID attributes) and the ID value you wish to look up.

Usage:

java TestIds <XML file> <ID>

The doc-files directory contains a demonstration program called ElementScannerTest.java. This program parses an XML file and uses ElementListeners to display the resulting parsed elements.

To run the test, use the following command structure:

java ElementScannerTest [XML file]

An example XML file named test.xml is provided in the same directory for testing purposes.

java ElementScannerTest test.xml

The JDOM build system provides several targets via build.xml. Use these commands to perform specific tasks during development or distribution.

 - package [default] -> generates ./build/package/jdom*.zip
 - compile -> compiles the source code
 - javadoc -> generates the API documentation in ./build/javadocs
 - junit -> runs the JUnit tests
 - coverage -> generates test coverage metrics
 - eclipse -> generates an Eclipse project (source folders, jars, etc)
 - clean -> restores the distribution to its original and clean state
 - maven -> generates the package, and makes a 'bundle' for maven-central

If you have access to the underlying org.jdom2 objects, you can use JDocument to find the corresponding JDOM-wrapped DOM nodes. This is useful when bridging code that uses JDOM with code that expects W3C DOM nodes.

Available find methods include:

• find(org.jdom2.Element): Returns a JElement.
• find(org.jdom2.Attribute): Returns a JAttribute.
• find(org.jdom2.CDATA): Returns a JCDATA.
• find(org.jdom2.DocType): Returns a JDocType.
• find(org.jdom2.ProcessingInstruction): Returns a JProcessingInstruction.
• find(org.jdom2.EntityRef): Returns a JEntityRef.
• find(org.jdom2.Comment): Returns a JComment.
• find(org.jdom2.Text): Returns a JText.