com.elharo.xml.xinclude
Class JDOMXIncluder

java.lang.Object
  |
  +--com.elharo.xml.xinclude.JDOMXIncluder

public class JDOMXIncluder

extends java.lang.Object

JDOMXIncluder provides methods to resolve JDOM elements and documents to produce a new Document, Element, or List of nodes with all XInclude references resolved.

Known bugs include:

• XPointer fragment identifiers are not handled
• Notations and unparsed entities from the included infosets are not merged into the final infoset
• The xinclude:fallback element is not yet supported.

Version:

1.0d9, July 4, 2002

Author:

Elliotte Rusty Harold

Field Summary

static org.jdom.Namespace

XINCLUDE_NAMESPACE

Method Summary

static org.jdom.Text	downloadTextDocument(java.net.URL source, java.lang.String encoding) This utility method reads a document at a specified URL and returns the contents of that document as a Text.
static void	main(java.lang.String[] args) The driver method for the XIncluder program.
static org.jdom.Document	resolve(org.jdom.Document original, java.lang.String base) This method resolves a JDOM Document and merges in all XInclude references.
protected static java.util.List	resolve(org.jdom.Element original, java.util.Stack bases) This method resolves a JDOM Element and merges in all XInclude references.
static java.util.List	resolve(org.jdom.Element original, java.lang.String base) This method resolves a JDOM Element and merges in all XInclude references.

Methods inherited from class java.lang.Object

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

Field Detail

XINCLUDE_NAMESPACE

public static final org.jdom.Namespace XINCLUDE_NAMESPACE

Method Detail

resolve

public static org.jdom.Document resolve(org.jdom.Document original,
                                        java.lang.String base)
                                 throws XIncludeException

This method resolves a JDOM Document and merges in all XInclude references. The Document object returned is a new document. The original Document is not changed.

Parameters:

original - Document that will be processed

base - String form of the base URI against which relative URLs will be resolved. This can be null if the document includes an xml:base attribute.

Returns:

Document new Document object in which all XInclude elements have been replaced.

Throws:

MissingHrefException - if an xinclude:include element does not have an href attribute.

UnavailableResourceException - if an included document cannot be located or cannot be read.

MalformedResourceException - if an included document is not namespace well-formed

CircularIncludeException - if this document possesses a cycle of XIncludes.

XIncludeException - if any of the rules of XInclude are violated

resolve

public static java.util.List resolve(org.jdom.Element original,
                                     java.lang.String base)
                              throws CircularIncludeException,
                                     XIncludeException,
                                     java.lang.NullPointerException

This method resolves a JDOM Element and merges in all XInclude references. This process is recursive. The element returned contains no XInclude elements. If a referenced document cannot be found it is replaced with an error message. The Element object returned is a new element. The original Element is not changed.

Parameters:

original - Element that will be processed

base - String form of the base URI against which relative URLs will be resolved. This can be null if the element includes an xml:base attribute.

Returns:

List A List containing all nodes that replace this element. If this element is not an xinclude:include this list is guaranteed to contain a single Element object.

Throws:

MissingHrefException - if an xinclude:include element does not have an href attribute.

java.lang.NullPointerException - if original element is null.

UnavailableResourceException - if an included document cannot be located or cannot be read.

MalformedResourceException - if an included document is not namespace well-formed

CircularIncludeException - if this Element contains an XInclude element that attempts to include a document in which this element is directly or indirectly included.

resolve

protected static java.util.List resolve(org.jdom.Element original,
                                        java.util.Stack bases)
                                 throws CircularIncludeException,
                                        MalformedResourceException,
                                        UnavailableResourceException,
                                        BadParseAttributeException,
                                        XIncludeException

This method resolves a JDOM Element and merges in all XInclude references. This process is recursive. The list returned contains no XInclude elements. The nodes in the list returned are new objects. The original Element is not changed.

Parameters:

original - Element that will be processed

bases - Stack containing the string forms of all the URIs of documents which contain this element through XIncludes. This is used to detect if any circular references occur.

Returns:

List A List containing all nodes that replace this element. If this element is not an xinclude:include this list is guaranteed to contain a single Element object.

Throws:

MissingHrefException - if an xinclude:include element does not have an href attribute.

UnavailableResourceException - if an included document cannot be located or cannot be read.

BadParseAttributeException - if an include element has a parse attribute with any value other than text or parse

MalformedResourceException - if an included document is not namespace well-formed

CircularIncludeException - if this Element contains an XInclude element that attempts to include a document in which this element is directly or indirectly included.

downloadTextDocument

public static org.jdom.Text downloadTextDocument(java.net.URL source,
                                                 java.lang.String encoding)
                                          throws UnavailableResourceException

This utility method reads a document at a specified URL and returns the contents of that document as a Text. It's used to include files with parse="text".

Parameters:

source - URL of the document that will be stored in String.

encoding - Encoding of the document; e.g. UTF-8, ISO-8859-1, etc.

Returns:

Text The document retrieved from the source URL.

Throws:

UnavailableResourceException - if the source document cannot be located or cannot be read.

main

public static void main(java.lang.String[] args)

The driver method for the XIncluder program. I'll probably move this to a separate class soon.

Parameters:

args - args[0] contains the URL or file name of the first document to be processed; args[1] contains the URL or file name of the second document to be processed, etc.