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:

ftp://ftp.ibiblio.org/pub/languages/java/javafaq/xincluder.tar.gz

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

     
       The inability to get the base URI of a Document
       hinders this
       The inability to get the line number of a particular element
       makes error reporting less useful.
       
     

     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:
 

 
 

 
 Redistributions of source code must retain the above copyright
     notice, this list of conditions and the following disclaimer. 
 
 
 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.
 
 
 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.

 
  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.

 
  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:
 
 
 
 
  Redistributions of source code must retain the above copyright
    notice, this list of conditions, and the following disclaimer.
 
 
  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.
 
 
 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.
 
 
  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