XInclude Engine 1.0d11

These are three rudimentary XInclude processors based on JDOM, SAX, and DOM2. These should work with Java 1.3 or later, and probably with Java 1.2, though you may have to recompile to get that to work. In a couple of places, I use the Collections API so if you're using Java 1.1, you'll need to install that and modify the source code as well. This version endeavors to support the September 17, 2002 Candidate Recommendation of XInclude though it falls short in a couple of areas, notably fallbacks and XPointers. It consists of several classes:

You can download an archive that includes the sources, the JAR file, support JARs, some simple test cases, the API docs, and so forth:

Known Problems

On Windows 2000 with the Sun JDK 1.3.1 (and possibly other versions) resolving a master document using a local file name relative to the current working directory fails. This isn't a problem with the XInclude code, but rather just a problem in the user interface when converting local file names like mybook.xml to URLs like file:/C:/books/mybook.xml. Everything should work as long as you use the full URL form.

URIs with fragment identifiers, particularly XPointers, are not yet handled. However, this would be a very obvious extension and would certainly give XPointer something to do. I plan to look into this.

Namespace mappings in the included documents are not necessarily maintained. Currently this problem is hidden because only entire documents can be included. However, once XPointers are resolved, I'll need to address this as well.

Fallbacks are not yet supported.

Attribute types, most notably notations and unparsed entities, in the included documents are not preserved.

Xerces 1.3.1 and earlier have some bugs that prevent the DOM version from working. You'll need Xerces 1.4.0 to 1.4.3 or 2.0.2. Xerces 1.4.4 reintroduces the bug. It should work with other DOM compliant parsers but I haven't tested it.

Xerces 2.0.1 has some bugs that add extra comments from the external DTD subset as part of the prolog. You should use Xerces 2.0.2 or later

API Documentation

Sourceforge Project Page

Build notes

A build file for Ant 1.4.1 or later is included. The necessary libraries for JDOM and Xerces are in the lib directory. Assuming you have ant installed, you should be able to build everything just by typing "ant jar" from inside the XInclude directory.

Install Notes

First you need to add the bundled xincluder.jar file to your CLASSPATH. You'll also need to install a parser that support SAX2 and DOM2 in your CLASSPATH. The bundled xercesImpl-2.0.2.jar and xmlParserAPIs-2.0.2.jar in the libs directory will suffice.

For JDOM, you also need to install JDOM 1.0beta9 or later in your CLASSPATH. You probably need to get the latest version out of CVS. I've only tested it with the current CVS version. The version I used is in the lib directory as jdom-1.0b9rc.jar.

SAX XIncluder Usage

You can process a file like this

% java com.elharo.xml.xinclude.SAXXIncluder filename.xml

The processed file will be printed on System.out and can be redirected into a file in the usual ways. The original file is not changed.

You can also process a file at a URL like this

% java com.elharo.xml.xinclude.SAXXIncluder http://www.mysite.com/myfile.xml

The processed file will be printed on System.out and can be redirected into a file in the usual ways. The original file is not changed.

If you have the Apache XML Project's resolver classes installed, then SAXXIncluder supports catalogs. Pass the fully-package qualified name of the EntityResolver class after the -r command line option like this:

% java -r org.apache.xml.resolver.tools.CatalogResolver com.elharo.xml.xinclude.SAXXIncluder url

XML catalogs are not yet supported for either JDOM or DOM.

Finally, you can use this class from inside your own SAX programs through the XIncludeFilter which is an XML filter that resolves all XIncludes before passing them along to the client application. The API documentation may be helpful for this purpose.

SAXXIncluder relies on the SAX2 XMLReaderFactory to locate a SAX parser. You can change the specific implementation in the usual way by setting the org.xml.sax.driver system property.

DOMXIncluder Usage

You can process a file like this

% java com.elharo.xml.xinclude.DOMXIncluder filename.xml

The processed file will be printed on System.out and can be redirected into a file in the usual ways. The original file is not changed.

You can also process a file at a URL like this

% java com.elharo.xml.xinclude.DOMXIncluder http://www.mysite.com/myfile.xml

Finally, you can use this class from inside your own programs to create unified Document or Element objects in which all XInclude references have been resolved. The API documentation may be helpful for this purpose.

DOMXIncluder relies on JAXP to locate a DOM implementation. You can change the specific implementation in the usual ways. For example, to use GNU JAXP,

% java -Djavax.xml.parsers.DocumentBuilderFactory=gnu.xml.dom.JAXPFactory com.elharo.xml.xinclude.DOMXIncluder http://www.mysite.com/myfile.xml

JDOM XIncluder Usage

You can process a file like this

% java com.elharo.xml.xinclude.JDOMXIncluder filename.xml

The processed file will be printed on System.out and can be redirected into a file in the usual ways. The original file is not changed.

You can also process a file at a URL like this

% java com.elharo.xml.xinclude.JDOMXIncluder http://www.mysite.com/myfile.xml

Finally, you can use this class from inside your own JDOM programs to create unified Document or Element objects in which all XInclude references have been resolved. The API documentation may be helpful for this purpose.

JDOM Notes

Licenses

The lib directory contains two JAR files from the Apache XML Project, and one JAR file from the JDOM Project. The build.xml file is based on the JDOM build file. otherwise, no source code has been used from either one. These are subject to the following licenses:

The Apache Software License, Version 1.1

Copyright (c) 1999-2002 The Apache Software Foundation. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: "This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.

  4. The names "Xerces" and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact apache@apache.org.

  5. Products derived from this software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation.

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation and was originally based on software copyright (c) 1999, International Business Machines, Inc., http://www.ibm.com. For more information on the Apache Software Foundation, please see <http://www.apache.org/>.

JDOM License

Copyright (C) 2000-2002 Brett McLaughlin & Jason Hunter. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the disclaimer that follows these conditions in the documentation and/or other materials provided with the distribution.

  3. The name "JDOM" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact license@jdom.org.

  4. Products derived from this software may not be called "JDOM", nor may "JDOM" appear in their name, without prior written permission from the JDOM Project Management (pm@jdom.org).

In addition, we request (but do not require) that you include in the end-user documentation provided with the redistribution and/or in the software itself an acknowledgement equivalent to the following:

"This product includes software developed by the JDOM Project (http://www.jdom.org/)."

Alternatively, the acknowledgment may be graphical using the logos available at http://www.jdom.org/images/logos.

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE JDOM AUTHORS OR THE PROJECT CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This software consists of voluntary contributions made by many individuals on behalf of the JDOM Project and was originally created by Brett McLaughlin <brett@jdom.org> and Jason Hunter <jhunter@jdom.org>. For more information on the JDOM Project, please see <http://www.jdom.org/>.

Last Modified March 9, 2003
Copyright 2000-2003 Elliotte Rusty Harold