The Web conquered gopher for one reason: HTML made it possible to embed hypertext links in documents.
HTML linking has limits
You can only link to one document at a time
You must link to the entire document.
Once the link is traversed the trail of where you've been is lost.
Includes are server dependent and don't work across domains
Links break
Hypertext in XML is divided into multiple parts:
A Uniform Resource Identifier (URI) names or locates a resource
An XLink defines connections between two or more documents identified by URIs
XPath identifies particular nodes within a document
An XPointer adds an XPath to a URI
XBase defines the URI against which relative URIs are resolved
XInclude embeds a document identified by a URI inside an XML document.
<?xml version="1.0"?>
<story date="January 9, 2001"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xml:base="http://www.cafeaulait.org/">
<p>
The W3C XML Linking Working Group has pushed the
<cite xlink:href="http://www.w3.org/TR/2001/WD-xptr-20010108">
XPointer specification
</cite>
back to working draft status. The specific issue that was
uncovered during Candidate Recommendation was some
<em xlink:type="simple"
xlink:href="http://www.w3.org/TR/xptr#xpointer(//div[@class='div3'][7])">
confusion
</em>
over how to integrate XPointers, particularly those
in non-XML documents, with namespaces.
</p>
<p>
It's also come to light in this draft that Sun has
<em xlink:type="simple"
xlink:href=
"http://lists.w3.org/Archives/Public/www-xml-linking-comments/2000OctDec/0092.html"
>
claimed a patent</em> on some of the technologies needed to
implement XPointer. I think this is particularly offensive
because Eve L. Maler, a Sun employee, served as co-chair of
the XML Linking Working Group and a co-editor of the XPointer
specification. As usual Sun wants to use this as a club to lock
implementers and users into a licensing agreement that goes
beyond what Sun and the W3C could otherwise demand. The specific
patent is <cite>United States Patent No. 5,659,729, Method and
system for implementing hypertext scroll attributes</cite>, issued
to Jakob Nielsen in 1997. The patent was filed on February 1, 1996.
It claims:
</p>
<blockquote>
<xi:include href=
"http://www.delphion.com/details?&pn=US05659729__#xpointer(//abstract)"
></xi:include>
</blockquote>
</story>This talk covers:
XLinks: June 27, 2001 Recommendation
XPointers: January 8, 2001 2nd Last Call Working Draft
XInclude: May 16, 2001 Last Call Working Draft
XML Base: June 27, 2001 Recommendation
The problem is that we're not providing the tools. We're providing the specs. That's a whole different ball game. If tools existed for actually making really interesting use of RDF and XLink and XInclude then people would use them. If IE and/or Mozilla supported the full gamut of specs, from XSLT 1.0 to XLink and XInclude (OK, so they're not quite REC's, but with time...) then you would find people using them more.--Matt Sergeant on the xml-dev mailing list
A means of including one XML document inside another, irrespective of validation.
Based on the XML Infoset; a source infoset is transformed into a result infoset
xlink:show="embed" only graphically includes,
like the IMG element in HTML.
It does not merge infosets.
External parsed entities:
Require a DTD
Can only handle very limited documents; i.e. not all well-formed XML documents are well-formed external parsed entities. In particular XML declarations can be and document type declarations are a problem.
Doesn't allow unparsed text inserted as CDATA
XSLT document() function
Only handles XSLT
No unparsed, pure-text includes
Server side includes:
HTML only
Server dependent
Custom code or XSLT extension functions
href attribute identifies the document (or part thereof)
to be included
In the http://www.w3.org/2001/XInclude
namespace.
The prefixes xinclude or xi
are customary.
<book xmlns:xinclude="http://www.w3.org/2001/XInclude">
<title>Processing XML with Java</title>
<chapter><xinclude:include href="dom.xml"/></chapter>
<chapter><xinclude:include href="sax.xml"/></chapter>
<chapter><xinclude:include href="jdom.xml"/></chapter>
</book>
parse="xml"parse="text"< will change to < and so forth.
<slide xmlns:xinclude="http://www.w3.org/2001/XInclude">
<title>The href attribute</title>
<ul>
<li>Identifies the document to be included with a URI</li>
<li>The document at the URI replaces the <code>include</code>
element in the including document</li>
<li>The <code>xinclude</code> prefix is bound to the http://www.w3.org/2001/XInclude
namespace URI.
</li>
</ul>
<pre><code><xinclude:include parse="text" href="processing_xml_with_java.xml"/>
</code></pre>
<description>
A slide from Elliotte Rusty Harold's XInclude seminar at
<host_ref/>, <date_ref/>
</description>
<last_modified>October 26, 2000</last_modified>
</slide>
Determine from MIME media type in HTTP content-type header or similar
If the document parsed as text is in fact an XML document, use the normal XML heuristics
Refer to the encoding attribute
UTF-8
Used when parse="text"
Value is the name of the text file's character encoding, as in the encoding declaration in the XML declaration
e.g. ISO-8859-1, UTF-8, UTF-16, MacRoman, etc.
<slide xmlns:xinclude="http://www.w3.org/2001/XInclude">
<title>The href attribute</title>
<ul>
<li>Identifies the document to be included with a URI</li>
<li>The document at the URI replaces the <code>include</code>
element in the including document</li>
<li>The <code>xinclude</code> prefix is bound to the http://www.w3.org/2001/XInclude
namespace URI.
</li>
</ul>
<pre><code><xinclude:include parse="text" encoding="ISO-8859-1"
href="processing_xml_with_java.xml"/>
</code></pre>
<description>
A slide from Elliotte Rusty Harold's XInclude seminar at
<host_ref/>, <date_ref/>
</description>
<last_modified>October 26, 2000</last_modified>
</slide>
/*--
Copyright 2001 Elliotte Rusty Harold.
All rights reserved.
I haven't yet decided on a license.
It will be some form of open source.
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 ELLIOTTE RUSTY HAROLD OR ANY
OTHER CONTRIBUTORS TO THIS PACKAGE
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.
*/
package com.macfaq.xml;
import org.xml.sax.Attributes;
import org.xml.sax.SAXException;
import org.xml.sax.XMLReader;
import org.xml.sax.helpers.XMLReaderFactory;
import org.xml.sax.helpers.XMLFilterImpl;
import org.xml.sax.helpers.NamespaceSupport;
import java.net.URL;
import java.net.MalformedURLException;
import java.io.IOException;
import java.io.InputStream;
import java.io.BufferedInputStream;
import java.io.InputStreamReader;
import java.util.Stack;
/**
* <p>
* This is a SAX filter which resolves all XInclude include elements
* before passing them on to the client application. Currently this
* class has the following known deviation from the XInclude specification:
* </p>
* <ol>
* <li>XPointer is not supported.</li>
* </ol>
*
* <p>
* Furthermore, I would definitely use a new instance of this class
* for each document you want to process. I doubt it can be used
* successfully on multiple documents. Furthermore, I can virtually
* guarantee that this class is not thread safe. You have been
* warned.
* </p>
*
* <p>
* Since this class is not designed to be subclassed, and since
* I have not yet considered how that might affect the methods
* herein or what other protected methods might be needed to support
* subclasses, I have declared this class final. I may remove this
* restriction later, though the use-case for subclassing is weak.
* This class is designed to have its functionality extended via a
* a horizontal chain of filters, not a
* vertical hierarchy of sub and superclasses.
* </p>
*
* <p>
* To use this class:
* </p>
* <ol>
* <li>Construct an XIncludeFilter object with a known base URL</li>
* <li>Pass the XMLReader object from which the raw document will
* be read to the <code>setParent()</code> method of this object. </li>
* <li>Pass your own <code>ContentHandler</code> object to the
* <code>setContentHandler()</code> method of this object. This is the
* object which will receive events from the parsed and included
* document.
* </li>
* <li>Optional: if you wish to receive comments, set your own
* <code>LexicalHandler</code> object as the value of this object's
* http://xml.org/sax/properties/lexical-handler property.
* Also make sure your <code>LexicalHandler</code> asks this object
* for the status of each comment using <code>insideIncludeElement</code>
* before doing anything with the comment.
* </li>
* <li>Pass the URL of the document to read to this object's
* <code>parse()</code> method</li>
* </ol>
*
* <p> e.g.</p>
* <pre><code>XIncludeFilter includer = new XIncludeFilter(base);
* includer.setParent(parser);
* includer.setContentHandler(new SAXXIncluder(System.out));
* includer.parse(args[i]);</code>
* </pre>
* </p>
*
* @author Elliotte Rusty Harold
* @version 1.0d1
*/
public final class XIncludeFilter extends XMLFilterImpl {
public final static String XINCLUDE_NAMESPACE
= "http://www.w3.org/2001/XInclude";
// Does not yet handle xml:base; need to add that
// private URL base;
private Stack bases = new Stack();
/**
* <p>
* This constructor creates a new <code>XIncludeFilter</code>
* which can be used to read a document while merging in all
* XInclude references.
* </p>
*
* @param base <code>URL</code> The base URI against which
* relative URLs will be resolved.
*/
public XIncludeFilter(URL base) {
bases.push(base);
}
/**
* <p>
* This constructor creates a new <code>XIncludeFilter</code>
* which can be used to read a document while merging in all
* XInclude references.
* </p>
*
* @param base <code>String</code> The base URI against which
* relative URLs will be resolved.
* @throws <code>MalformedURLException</code> If the string cannot
* be converted to a <code>java.net.URL</code> object.
*/
public XIncludeFilter(String base) throws MalformedURLException {
this(new URL(base));
}
// necessary to throw away contents of non-empty XInclude elements
private int level = 0;
/**
* <p>
* This utility method returns true if and only if this reader is
* currently inside a non-empty include element. (This is <strong>
* not</strong> the same as being inside the node set whihc replaces
* the include element.) This is primarily needed for comments
* inside include elements. It must be checked by the actual
* LexicalHandler to see whether a comment is passed or not.
* </p>
*
* @return boolean
*/
public boolean insideIncludeElement() {
return level != 0;
}
public void startElement(String uri, String localName,
String qName, Attributes atts) throws SAXException {
if (level == 0) { // We're not inside an xi:include element
// Adjust bases stakc by pushing either the new
// value of xml:base or the base of the parent
String base = atts.getValue(NamespaceSupport.XMLNS, "base");
URL parentBase = (URL) bases.peek();
URL currentBase = parentBase;
if (base != null) {
try {
currentBase = new URL(parentBase, base);
}
catch (MalformedURLException e) {
throw new SAXException("Malformed base URL: "
+ currentBase, e);
}
}
bases.push(currentBase);
if (uri.equals(XINCLUDE_NAMESPACE) && localName.equals("include")) {
// include external document
String href = atts.getValue("href");
// Verify that there is an href attribute
if (href==null) {
throw new SAXException("Missing href attribute");
}
String parse = atts.getValue("parse");
if (parse == null) parse = "xml";
if (parse.equals("text")) {
includeTextDocument(href);
}
else if (parse.equals("xml")) {
includeXMLDocument(href);
}
// Do I check this one in DOM and JDOM????
else {
throw new SAXException(
"Illegal value for parse attribute: " + parse);
}
level++;
}
else {
super.startElement(uri, localName, qName, atts);
}
}
}
public void endElement (String uri, String localName, String qName)
throws SAXException {
if (uri.equals(XINCLUDE_NAMESPACE)
&& localName.equals("include")) {
level--;
}
else if (level == 0) {
bases.pop();
super.endElement(uri, localName, qName);
}
}
private int depth = 0;
public void startDocument() throws SAXException {
level = 0;
if (depth == 0) super.startDocument();
depth++;
}
public void endDocument() throws SAXException {
depth--;
if (depth == 0) super.endDocument();
}
// how do prefix mappings move across documents????
public void startPrefixMapping(String prefix, String uri)
throws SAXException {
if (level == 0) super.startPrefixMapping(prefix, uri);
}
public void endPrefixMapping(String prefix)
throws SAXException {
if (level == 0) super.endPrefixMapping(prefix);
}
public void characters(char[] ch, int start, int length)
throws SAXException {
if (level == 0) super.characters(ch, start, length);
}
public void ignorableWhitespace(char[] ch, int start, int length)
throws SAXException {
if (level == 0) super.ignorableWhitespace(ch, start, length);
}
public void processingInstruction(String target, String data)
throws SAXException {
if (level == 0) super.processingInstruction(target, data);
}
public void skippedEntity(String name) throws SAXException {
if (level == 0) super.skippedEntity(name);
}
/**
* <p>
* This utility method reads a document at a specified URL
* and fires off calls to <code>characters()</code>.
* It's used to include files with <code>parse="text"</code>
* </p>
*
* @param url URL of the document that will be read
* @return void
* @throws SAXException if the requested document cannot
be downloaded from the specified URL.
*/
private void includeTextDocument(String url)
throws SAXException {
URL source;
try {
URL base = (URL) bases.peek();
source = new URL(base, url);
}
catch (MalformedURLException e) {
UnavailableResourceException ex =
new UnavailableResourceException("Unresolvable URL " + url);
ex.setRootCause(e);
throw new SAXException("Unresolvable URL " + url, ex);
}
try {
InputStream in = new BufferedInputStream(source.openStream());
// does XInclude give you anything to specify the character set????
InputStreamReader reader = new InputStreamReader(in, "8859_1");
char[] c = new char[1024];
while (true) {
int charsRead = reader.read(c, 0, 1024);
if (charsRead == -1) break;
if (charsRead > 0) this.characters(c, 0, charsRead);
}
}
catch (IOException e) {
throw new SAXException("Document not found: "
+ source.toExternalForm(), e);
}
}
/**
* <p>
* This utility method reads a document at a specified URL
* and fires off calls to various ContentHandler methods.
* It's used to include files with <code>parse="xml"</code>
* </p>
*
* @param url URL of the document that will be read
* @return void
* @throws SAXException if the requested document cannot
be downloaded from the specified URL.
*/
private void includeXMLDocument(String url)
throws SAXException {
URL source;
try {
URL base = (URL) bases.peek();
source = new URL(base, url);
}
catch (MalformedURLException e) {
UnavailableResourceException ex =
new UnavailableResourceException("Unresolvable URL " + url);
ex.setRootCause(e);
throw new SAXException("Unresolvable URL " + url, ex);
}
try {
// make this more robust
XMLReader parser;
try {
parser = XMLReaderFactory.createXMLReader();
}
catch (SAXException e) {
try {
parser = XMLReaderFactory.createXMLReader(
"org.apache.xerces.parsers.SAXParser"
);
}
catch (SAXException e2) {
System.err.println("Could not find an XML parser");
return;
}
}
parser.setContentHandler(this);
// save old level and base
int previousLevel = level;
this.level = 0;
if (bases.contains(source)) {
// need to figure out how to get file and number where
// bad include occurs????
Exception e = new CircularIncludeException(
"Circular XInclude Reference to " + source + " in "
);
throw new SAXException("Circular XInclude Reference", e);
}
bases.push(source);
parser.parse(source.toExternalForm());
// restore old level and base
this.level = previousLevel;
bases.pop();
}
catch (IOException e) {
throw new SAXException("Document not found: "
+ source.toExternalForm(), e);
}
}
}
/*--
Copyright 2001 Elliotte Rusty Harold.
All rights reserved.
I haven't yet decided on a license.
It will be some form of open source.
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 ELLIOTTE RUSTY HAROLD OR ANY
OTHER CONTRIBUTORS TO THIS PACKAGE
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.
*/
package com.macfaq.xml;
import org.xml.sax.SAXException;
import org.xml.sax.ContentHandler;
import org.xml.sax.helpers.XMLReaderFactory;
import org.xml.sax.XMLReader;
import org.xml.sax.Locator;
import org.xml.sax.Attributes;
import org.xml.sax.ext.LexicalHandler;
import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.io.OutputStream;
import java.io.Writer;
import java.io.OutputStreamWriter;
import java.io.File;
import java.net.URL;
import java.net.MalformedURLException;
/**
* <p><code>SAXXIncluder</code> is a simple ContentHandler that
* writes its XML document onto an output stream after resolving
* all <code>xinclude:include</code> elements.
* </p>
*
*
* @author Elliotte Rusty Harold
* @version 1.0d1
*/
public class SAXXIncluder implements ContentHandler, LexicalHandler {
private Writer out;
private String encoding;
// should try to combine two constructors so as not to duplicate
// code
public SAXXIncluder(OutputStream out, String encoding)
throws UnsupportedEncodingException {
this.out = new OutputStreamWriter(out, encoding);
this.encoding = encoding;
}
public SAXXIncluder(OutputStream out) {
try {
this.out = new OutputStreamWriter(out, "UTF8");
this.encoding="UTF-8";
}
catch (UnsupportedEncodingException e) {
// This really shouldn't happen
}
}
public void setDocumentLocator(Locator locator) {}
public void startDocument() throws SAXException {
try {
out.write("<?xml version='1.0' encoding='"
+ encoding + "'?>\r\n");
}
catch (IOException e) {
throw new SAXException("Write failed", e);
}
}
public void endDocument() throws SAXException {
try {
out.flush();
}
catch (IOException e) {
throw new SAXException("Flush failed", e);
}
}
public void startPrefixMapping(String prefix, String uri)
throws SAXException {
}
public void endPrefixMapping(String prefix)
throws SAXException {
}
public void startElement(String namespaceURI, String localName,
String qualifiedName, Attributes atts)
throws SAXException {
try {
out.write("<" + qualifiedName);
for (int i = 0; i < atts.getLength(); i++) {
out.write(" ");
out.write(atts.getQName(i));
out.write("='");
out.write(atts.getValue(i));
out.write("'");
}
out.write(">");
}
catch (IOException e) {
throw new SAXException("Write failed", e);
}
}
public void endElement(String namespaceURI, String localName,
String qualifiedName) throws SAXException {
try {
out.write("</" + qualifiedName + ">");
}
catch (IOException e) {
throw new SAXException("Write failed", e);
}
}
// need to escape text????
public void characters(char[] ch, int start, int length)
throws SAXException {
try {
out.write(ch, start, length);
}
catch (IOException e) {
throw new SAXException("Write failed", e);
}
}
public void ignorableWhitespace(char[] ch, int start, int length)
throws SAXException {
this.characters(ch, start, length);
}
// do I need to escape text in PI????
public void processingInstruction(String target, String data)
throws SAXException {
try {
out.write("<?" + target + " " + data + "?>");
}
catch (IOException e) {
throw new SAXException("Write failed", e);
}
}
public void skippedEntity(String name) throws SAXException {
try {
out.write("&" + name + ";");
}
catch (IOException e) {
throw new SAXException("Write failed", e);
}
}
// This should check the encoding and use charrefs on
// non-encoded characters
public static String escapeText(String s) {
if (s.indexOf('&') != -1 || s.indexOf('<') != -1) {
StringBuffer result = new StringBuffer(s.length() + 5);
for (int i = 0; i < s.length(); i++) {
char c = s.charAt(i);
if (c == '&') result.append("&");
else if (c == '<') result.append("<");
else if (c == '"') result.append(""");
else if (c == '\'') result.append("'");
else result.append(c);
}
return result.toString();
}
else {
return s;
}
}
//LexicalHandler methods
private boolean inDTD = false;
public void startDTD(String name, String publicId, String systemId)
throws SAXException {
inDTD = true;
}
public void endDTD() throws SAXException {
inDTD = false;
}
public void startEntity(String name) throws SAXException {}
public void endEntity(String name) throws SAXException {}
public void startCDATA() throws SAXException {}
public void endCDATA() throws SAXException {}
// Just need this reference so we can ask if a comment is
// inside an include element or not
private XIncludeFilter filter = null;
public void setFilter(XIncludeFilter filter) {
this.filter = filter;
}
public void comment(char[] ch, int start, int length)
throws SAXException {
if (!inDTD && !filter.insideIncludeElement()) {
try {
out.write("<!--");
out.write(ch, start, length);
out.write("-->");
}
catch (IOException e) {
throw new SAXException("Write failed", e);
}
}
}
/**
* <p>
* The driver method for the SAXXIncluder program.
* </p>
*
* @param args contains the URLs and/or filenames
* of the documents to be procesed.
*/
public static void main(String[] args) {
// make this more robust
XMLReader parser;
try {
parser = XMLReaderFactory.createXMLReader();
}
catch (SAXException e) {
try {
parser = XMLReaderFactory.createXMLReader(
"org.apache.xerces.parsers.SAXParser");
}
catch (SAXException e2) {
System.err.println("Could not find an XML parser");
return;
}
}
// Need better namespace handling
try {
parser.setFeature("http://xml.org/sax/features/namespace-prefixes", true);
}
catch (SAXException e) {
System.err.println(e);
return;
}
for (int i = 0; i < args.length; i++) {
try {
URL base;
try {
base = new URL(args[i]);
}
catch (MalformedURLException e) {
File f = new File(args[i]);
base = f.toURL();
}
XIncludeFilter includer = new XIncludeFilter(base);
includer.setParent(parser);
SAXXIncluder s = new SAXXIncluder(System.out);
includer.setContentHandler(s);
try {
includer.setProperty(
"http://xml.org/sax/properties/lexical-handler",
s);
s.setFilter(includer);
}
catch (SAXException e) {
// Will not support comments
}
includer.parse(args[i]);
}
catch (Exception e) { // be specific about exceptions????
System.err.println(e);
e.printStackTrace();
}
}
}
}
/*--
Copyright 2000, 2001 Elliotte Rusty Harold.
All rights reserved.
I haven't yet decided on a license.
It will be some form of open source.
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.
*/
package com.macfaq.xml;
import java.net.URL;
import java.net.MalformedURLException;
import java.util.Stack;
import java.util.Iterator;
import java.util.List;
import java.util.LinkedList;
import java.io.File;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.BufferedInputStream;
import java.io.InputStream;
import org.jdom.Namespace;
import org.jdom.Comment;
import org.jdom.CDATA;
import org.jdom.JDOMException;
import org.jdom.Attribute;
import org.jdom.Element;
import org.jdom.ProcessingInstruction;
import org.jdom.Document;
import org.jdom.DocType;
import org.jdom.Entity;
import org.jdom.input.SAXBuilder;
import org.jdom.input.DOMBuilder;
import org.jdom.output.XMLOutputter;
/**
* <p><code>XIncluder</code> provides methods to
* resolve JDOM elements and documents to produce
* a new Document, Element, or List of nodes with all
* XInclude references resolved.
* </p>
*
*
* @author Elliotte Rusty Harold
* @version 1.0d5, June 6, 2001
*/
public class XIncluder {
public final static Namespace XINCLUDE_NAMESPACE
= Namespace.getNamespace("xi", "http://www.w3.org/2001/XInclude");
// No instances allowed
private XIncluder() {}
private static SAXBuilder builder = new SAXBuilder();
// private static DOMBuilder builder = new DOMBuilder();
/**
* <p>
* This method resolves a JDOM <code>Document</code>
* and merges in all XInclude references.
* The Document object returned is a new document.
* The original <code>Document</code> is not changed.
* </p>
*
* @param original <code>Document</code> that will be processed
* @param base <code>String</code> form of the base URI against which
* relative URLs will be resolved. This can be null if the
* document includes an <code>xml:base</code> attribute.
* @return Document new <code>Document</code> object in which all
* XInclude elements have been replaced.
* @throws MissingHrefException if an <code>xinclude:include</code> element does not have an href attribute.
* @throws UnavailableResourceException if an included document cannot be located
* or cannot be read.
* @throws MalformedResourceException if an included document is not namespace well-formed
* @throws CircularIncludeException if this document possesses a cycle of
* XIncludes.
* @throws XIncludeException if any of the rules of XInclude are violated
*/
public static Document resolve(Document original, String base)
throws XIncludeException {
if (original == null) {
throw new NullPointerException("Document must not be null");
}
Document result = (Document) original.clone();
Element root = result.getRootElement();
List resolved = resolve(root, base);
// check that the list returned contains
// exactly one root element
Element newRoot = null;
Iterator iterator = resolved.iterator();
while (iterator.hasNext()) {
Object o = iterator.next();
if (o instanceof Element) {
if (newRoot != null) {
throw new XIncludeException("Tried to include multiple roots");
}
newRoot = (Element) o;
/* System.err.println("Returned root: ");
XMLOutputter outputter = new XMLOutputter();
try {
outputter.output(newRoot, System.err);
}
catch (IOException e) {} */
}
else if (o instanceof Comment || o instanceof ProcessingInstruction) {
// do nothing
}
else if (o instanceof CDATA || o instanceof String) {
throw new XIncludeException(
"Tried to include text node outside of root element"
);
}
else if (o instanceof Entity) {
throw new XIncludeException(
"Tried to include entity node outside of root element"
);
}
else {
throw new XIncludeException(
"Unexpected type " + o.getClass()
);
}
}
if (newRoot == null) {
throw new XIncludeException("No root element");
}
// Could probably combine two loops
List newContent = result.getMixedContent();
// resolved contains list of new content
// use it to replace old root element
iterator = resolved.iterator();
// put in nodes before root element
int rootPosition = newContent.indexOf(result.getRootElement());
while (iterator.hasNext()) {
Object o = iterator.next();
if (o instanceof Comment || o instanceof ProcessingInstruction) {
newContent.add(rootPosition, o);
rootPosition++;
}
else if (o instanceof Element) { // the root
break;
}
else {
// throw exception????
}
}
// put in root element
result.setRootElement(newRoot);
int addPosition = rootPosition+1;
// put in nodes after root element
while (iterator.hasNext()) {
Object o = iterator.next();
if (o instanceof Comment || o instanceof ProcessingInstruction) {
newContent.add(addPosition, o);
addPosition++;
}
else {
// throw exception????
}
}
return result;
}
/**
* <p>
* This method resolves a JDOM <code>Element</code>
* 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 <code>Element</code> object returned is a new element.
* The original <code>Element</code> is not changed.
* </p>
*
* @param original <code>Element</code> that will be processed
* @param base <code>String</code> form of the base URI against which
* relative URLs will be resolved. This can be null if the
* element includes an <code>xml:base</code> attribute.
* @return List A List containing all nodes that replace this element.
* If this element is not an <code>xinclude:include</code>
* this list is guaranteed to contain a single <code>Element</code> object.
* @throws MissingHrefException if an <code>xinclude:include</code> element does not have an href attribute.
* @throws NullPointerException if <code>original</code> element is null.
* @throws UnavailableResourceException if an included document cannot be located
* or cannot be read.
* @throws MalformedResourceException if an included document is not namespace well-formed
* @throws CircularIncludeException if this <code>Element</code> contains an XInclude element
* that attempts to include a document in which
* this element is directly or indirectly included.
*/
public static List resolve(Element original, String base)
throws CircularIncludeException, XIncludeException, NullPointerException {
if (original == null) {
throw new NullPointerException("You can't XInclude a null element.");
}
Stack bases = new Stack();
if (base != null) bases.push(base);
List result = resolve(original, bases);
bases.pop();
return result;
}
private static boolean isIncludeElement(Element element) {
if (element.getName().equals("include") &&
element.getNamespace().equals(XINCLUDE_NAMESPACE)) {
return true;
}
return false;
}
/**
* <p>
* This method resolves a JDOM <code>Element</code>
* 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 <code>Element</code> is not changed.
* </p>
*
* @param original <code>Element</code> that will be processed
* @param bases <code>Stack</code> 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.
* @return List A List containing all nodes that replace this element.
* If this element is not an <code>xinclude:include</code>
* this list is guaranteed to contain a single <code>Element</code> object.
* @throws MissingHrefException if an <code>xinclude:include</code> element does not have an href attribute.
* @throws UnavailableResourceException if an included document cannot be located
* or cannot be read.
* @throws MalformedResourceException if an included document is not namespace well-formed
* @throws CircularIncludeException if this <code>Element</code> contains an XInclude element
* that attempts to include a document in which
* this element is directly or indirectly included.
*/
protected static List resolve(Element original, Stack bases)
throws CircularIncludeException, MalformedResourceException,
UnavailableResourceException, XIncludeException {
String base = "";
if (bases.size() != 0) base = (String) bases.peek();
if (isIncludeElement(original)) {
return resolveXIncludeElement(original, bases);
}
else {
Element resolvedElement = resolveNonXIncludeElement(original, bases);
List resultList = new LinkedList();
resultList.add(resolvedElement);
return resultList;
}
}
private static List resolveXIncludeElement(Element original, Stack bases)
throws CircularIncludeException, MalformedResourceException,
UnavailableResourceException, XIncludeException {
String base = "";
if (bases.size() != 0) base = (String) bases.peek();
// These lines are probably unnecessary
if (!isIncludeElement(original)) {
throw new RuntimeException("Bad private Call");
}
Attribute href = original.getAttribute("href");
if (href == null) {
throw new MissingHrefException("Missing href attribute");
}
Attribute baseAttribute
= original.getAttribute("base", Namespace.XML_NAMESPACE);
if (baseAttribute != null) {
base = baseAttribute.getValue();
}
URL remote;
if (base != null) {
try {
URL context = new URL(base);
remote = new URL(context, href.getValue());
}
catch (MalformedURLException ex) {
XIncludeException xex = new UnavailableResourceException(
"Unresolvable URL " + base + "/" + href);
xex.setRootCause(ex);
throw xex;
}
}
else { // base == null
try {
remote = new URL(href.getValue());
}
catch (MalformedURLException ex) {
XIncludeException xex = new UnavailableResourceException(
"Unresolvable URL " + href.getValue());
xex.setRootCause(ex);
throw xex;
}
}
boolean parse = true;
Attribute parseAttribute = original.getAttribute("parse");
if (parseAttribute != null) {
if (parseAttribute.getValue().equals("text")) parse = false;
}
if (parse) {
// System.err.println("parsed");
// checks for equality (OK) or identity (not OK)????
if (bases.contains(remote.toExternalForm())) {
// need to figure out how to get file and number where
// bad include occurs
throw new CircularIncludeException(
"Circular XInclude Reference to "
+ remote.toExternalForm() + " in "
);
}
try {
Document doc = builder.build(remote); // this Document object never leaves this method
// System.err.println(doc);
bases.push(remote.toExternalForm());
// This is the point where I need to select out
// the nodes pointed to by the XPointer
// I really need to push this out into a separate method
// that returns a list of the nodes pointed to by the XPointer
String fragment = remote.getRef();
// I need to return the full document child list including comments and PIs,
// not just the resolved root
Element root = doc.getRootElement();
List topLevelNodes = doc.getMixedContent();
int rootPosition = topLevelNodes.indexOf(root);
List beforeRoot = topLevelNodes.subList(0, rootPosition);
List afterRoot = topLevelNodes.subList(rootPosition+1, topLevelNodes.size());
List rootList = resolve(root, bases);
// List resultList = resolve(root, bases);
List resultList = new LinkedList();
resultList.addAll(beforeRoot);
resultList.addAll(rootList);
resultList.addAll(afterRoot);
// the top-level things I return should be disconnected from their parents
for (int i = 0; i < resultList.size(); i++) {
Object o = resultList.get(i);
if (o instanceof Element) {
Element element = (Element) o;
List nodes = resolve(element, bases);
resultList.addAll(i, nodes);
i += nodes.size();
resultList.remove(i);
i--;
// System.err.println(element);
element.detach();
}
if (o instanceof Comment) {
Comment comment = (Comment) o;
comment.detach();
}
if (o instanceof ProcessingInstruction) {
ProcessingInstruction pi = (ProcessingInstruction) o;
pi.detach();
}
}
bases.pop();
return resultList;
}
// should this be a MalformedResourceException????
// probably; maybe check on why JDOMException was thrown
catch (JDOMException e) {
XIncludeException xex = new UnavailableResourceException(
"Unresolvable URL " + href.getValue());
xex.setRootCause(e);
throw xex;
}
}
else { // unparsed, insert text
String s = downloadTextDocument(remote);
List resultList = new LinkedList();
resultList.add(s);
return resultList;
}
}
private static Element resolveNonXIncludeElement(Element original, Stack bases)
throws CircularIncludeException, MalformedResourceException,
UnavailableResourceException, XIncludeException {
String base = "";
if (bases.size() != 0) base = (String) bases.peek();
// Not an include element; a copy of this element in which its
// descendants have been resolved will be returned
// recursively process children
Element result = new Element(original.getName(), original.getNamespace());
Iterator attributes = original.getAttributes().iterator();
while (attributes.hasNext()) {
Attribute a = (Attribute) attributes.next();
result.setAttribute((Attribute) a.clone());
}
List newChildren = result.getMixedContent(); // live list
Iterator originalChildren = original.getMixedContent().iterator();
while (originalChildren.hasNext()) {
Object o = originalChildren.next();
if (o instanceof Element) {
Element element = (Element) o;
if (isIncludeElement(element)) {
newChildren.addAll(resolveXIncludeElement(element, bases));
}
else {
newChildren.add(resolveNonXIncludeElement(element, bases));
}
}
else if (o instanceof String) {
newChildren.add(o);
}
else if (o instanceof Comment) {
Comment c = (Comment) o;
newChildren.add(c.clone());
}
else if (o instanceof Entity) {
Entity entity = (Entity) o;
newChildren.add(entity.clone());
}
else if (o instanceof ProcessingInstruction) {
ProcessingInstruction pi = (ProcessingInstruction) o;
newChildren.add(pi.clone());
}
else {
throw new XIncludeException("Unexpected Type " + o.getClass());
}
} // end while
return result;
}
/**
* <p>
* This utility method reads a document at a specified URL
* and returns the contents of that document as a <code>String</code>.
* It's used to include files with <code>parse="text"</code>
* </p>
*
* @param source <code>URL</code> of the doucment that will be stored in
* <code>String</code>.
* @return String The document retrieved from the source <code>URL</code>.
* @throws UnavailableResourceException if the source document cannot be located
* or cannot be read.
*/
public static String downloadTextDocument(URL source)
throws UnavailableResourceException {
try {
StringBuffer s = new StringBuffer();
InputStream in = new BufferedInputStream(source.openStream());
// does XInclude give you anything to specify the character set????
InputStreamReader reader = new InputStreamReader(in, "8859_1");
int c;
while ((c = in.read()) != -1) {
if (c == '<') s.append("<");
else if (c == '&') s.append("&");
else s.append((char) c);
}
return s.toString();
}
catch (IOException e) {
UnavailableResourceException ex = new UnavailableResourceException(
"Document not found: " + source.toExternalForm());
ex.setRootCause(e);
throw ex;
}
}
/**
* <p>
* The driver method for the XIncluder program.
* I'll probably move this to a separate class soon.
* </p>
*
* @param args <code>args[0]</code> contains the URL or file name
* of the first document to be processed; <code>args[1]</code>
* contains the URL or file name
* of the second document to be processed, etc.
*/
public static void main(String[] args) {
SAXBuilder builder = new SAXBuilder();
XMLOutputter outputter = new XMLOutputter();
for (int i = 0; i < args.length; i++) {
try {
Document input = builder.build(args[i]);
// absolutize URL
String base = args[i];
if (base.indexOf(':') < 0) {
File f = new File(base);
base = f.toURL().toExternalForm();
}
Document output = resolve(input, base);
// need to set encoding on this to Latin-1 and check what
// happens to UTF-8 curly quotes
outputter.output(output, System.out);
}
catch (Exception e) {
System.err.println(e);
e.printStackTrace();
}
}
}
}
/*--
Copyright 2001 Elliotte Rusty Harold.
All rights reserved.
I haven't yet decided on a license.
It will be some form of open source.
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 ELLIOTTE RUSTY HAROLD OR ANY
OTHER CONTRIBUTORS TO THIS PACKAGE
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.
*/
package com.macfaq.xml;
import java.net.URL;
import java.net.MalformedURLException;
import java.util.Stack;
import java.util.List;
import java.util.ArrayList;
import org.xml.sax.SAXException;
import java.io.File;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.BufferedInputStream;
import java.io.InputStream;
import org.w3c.dom.Element;
import org.w3c.dom.Document;
import org.w3c.dom.Comment;
import org.w3c.dom.ProcessingInstruction;
import org.w3c.dom.DocumentType;
import org.w3c.dom.Text;
import org.w3c.dom.Node;
import org.w3c.dom.NodeList;
import org.apache.xerces.parsers.DOMParser;
import org.apache.xml.serialize.OutputFormat;
import org.apache.xml.serialize.XMLSerializer;
/**
* <p><code>DOMXIncluder</code> provides methods to
* resolve DOM elements and documents to produce
* a new <code>Document</code> or <code>Element</code> with all
* XInclude references resolved.
* </p>
*
*
* @author Elliotte Rusty Harold
* @version 1.0d6
*/
public class DOMXIncluder {
public final static String XINCLUDE_NAMESPACE
= "http://www.w3.org/2001/XInclude";
public final static String XML_NAMESPACE
= "http://www.w3.org/XML/1998/namespace";
// No instances allowed
private DOMXIncluder() {}
private static DOMParser parser = new DOMParser();
/**
* <p>
* This method resolves a DOM <code>Document</code>
* and merges in all XInclude references.
* The <code>Document</code> object returned is a new document.
* The original <code>Document</code> object is not changed.
* </p>
*
* <p>
* This method depends on the ability to clone a DOM <code>Document</code>
* which not all DOM parsers may be able to do.
* It definitely exercises a big in Xerces-J 1.3.1.
* This bug is fixed in Xerces-J 1.4.0.
* </p>
*
* @param original <code>Document</code> that will be processed
* @param base <code>String</code> form of the base URI against which
* relative URLs will be resolved. This can be null if the
* document includes an <code>xml:base</code> attribute.
* @return Document new <code>Document</code> object in which all
* XInclude elements have been replaced.
* @throws XIncludeException if this document, though namespace well-formed,
* violates one of the rules of XInclude.
* @throws NullPointerException if the original argument is null.
*/
public static Document resolve(Document original, String base)
throws XIncludeException, NullPointerException {
if (original == null) {
throw new NullPointerException("Document must not be null");
}
Document resultDocument = (Document) original.cloneNode(true);
Element resultRoot = resultDocument.getDocumentElement();
NodeList resolved = resolve(resultRoot, base, resultDocument);
// Check that this contains exactly one root element
// and no Text nodes
int numberRoots = 0;
for (int i = 0; i < resolved.getLength(); i++) {
if (resolved.item(i) instanceof Comment
||resolved.item(i) instanceof ProcessingInstruction
||resolved.item(i) instanceof DocumentType) {
continue;
}
else if (resolved.item(i) instanceof Element) numberRoots++;
else if (resolved.item(i) instanceof Text) {
// Is this OK if the text node only contains white space????
throw new XIncludeException(
"Tried to include text node outside document element");
}
else {
throw new XIncludeException(
// convert type to a string????
"Cannot include a " + resolved.item(i).getNodeType() + " node");
}
}
if (numberRoots != 1) {
throw new XIncludeException("Tried to include multiple roots");
}
// insert nodes before the root
int nodeIndex = 0;
while (nodeIndex < resolved.getLength()) {
if (resolved.item(nodeIndex) instanceof Element) break;
resultDocument.insertBefore(resolved.item(nodeIndex), resultRoot);
nodeIndex++;
}
// insert new root
resultDocument.replaceChild(
resolved.item(nodeIndex), resultRoot
);
nodeIndex++;
//insert nodes after new root
Node refNode = resultDocument.getDocumentElement().getNextSibling();
if (refNode == null) {
while (nodeIndex < resolved.getLength()) {
resultDocument.appendChild(resolved.item(nodeIndex));
nodeIndex++;
}
}
else {
while (nodeIndex < resolved.getLength()) {
resultDocument.insertBefore(resolved.item(nodeIndex), refNode);
nodeIndex++;
}
}
return resultDocument;
}
/**
* <p>
* This method resolves a DOM <code>Element</code>
* 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 <code>Element</code> object returned is a new element.
* The original <code>Element</code> is not changed.
* </p>
*
* @param original <code>Element</code> that will be processed
* @param base <code>String</code> form of the base URI against which
* relative URLs will be resolved. This can be null if the
* element includes an <code>xml:base</code> attribute.
* @param resolved <code>Document</code> into which the resolved element will be placed.
* @return NodeList the infoset that this element resolves to
* @throws CircularIncludeException if this <code>Element</code> contains an XInclude element
* that attempts to include a document in which
* this element is directly or indirectly included.
* @throws NullPointerException if the <code>original</code> argument is null.
*/
public static NodeList resolve(Element original, String base, Document resolved)
throws XIncludeException, NullPointerException {
if (original == null) {
throw new NullPointerException(
"You can't XInclude a null element."
);
}
Stack bases = new Stack();
if (base != null) bases.push(base);
NodeList result = resolve(original, bases, resolved);
bases.pop();
return result;
}
private static boolean isIncludeElement(Element element) {
if (element.getLocalName().equals("include") &&
element.getNamespaceURI().equals(XINCLUDE_NAMESPACE)) {
return true;
}
return false;
}
/**
* <p>
* This method resolves a DOM <code>Element</code> into an infoset
* and merges in all XInclude references. This process is recursive.
* The returned infoset contains no XInclude elements.
* If a referenced document cannot be found it is replaced with
* an error message. The <code>NodeList</code> object returned is new.
* The original <code>Element</code> is not changed.
* </p>
*
* @param original <code>Element</code> that will be processed
* @param bases <code>Stack</code> containing the string forms of
* all the URIs of documents which contain this element
* through XIncludes. This used to detect if a circular
* reference is being used.
* @param resolved <code>Document</code> into which the resolved element will be placed.
* @return NodeList the infoset into whihc this element resolves. This is just a copy
of the element if the element is not an XINclude element and does
not contain any XInclude elements.
* @throws CircularIncludeException if this <code>Element</code> contains an XInclude element
* that attempts to include a document in which
* this element is directly or indirectly included.
* @throws MissingHrefException if the <code>href</code> attribute is missing from an include element.
* @throws MalformedResourceException if an included document is not namespace well-formed or
* @throws UnavailableResourceException if the URL in the include element's
<code>href</code> attribute cannot be loaded.
* @throws XIncludeException if this document, though namespace well-formed,
* violates one of the rules of XInclude.
*/
private static NodeList resolve(Element original, Stack bases, Document resolved)
throws CircularIncludeException, MissingHrefException, MalformedResourceException,
UnavailableResourceException, XIncludeException {
XIncludeNodeList result = new XIncludeNodeList();
String base = null;
if (bases.size() != 0) base = (String) bases.peek();
if (isIncludeElement(original)) {
// Verify that there is an href attribute
if (!original.hasAttribute("href")) {
throw new MissingHrefException("Missing href attribute");
}
String href = original.getAttribute("href");
// Check for a base attribute
String baseAttribute
= original.getAttributeNS(XML_NAMESPACE, "base");
if (baseAttribute != null && !baseAttribute.equals("")) {
base = baseAttribute;
}
String remote;
if (base != null) {
try {
URL context = new URL(base);
URL u = new URL(context, href);
remote = u.toExternalForm();
}
catch (MalformedURLException ex) {
XIncludeException xex = new UnavailableResourceException(
"Unresolvable URL " + base + "/" + href);
xex.setRootCause(ex);
throw xex;
}
}
else {
remote = href;
}
// check for parse attribute; default is true
boolean parse = true;
if (original.hasAttribute("parse")) {
String parseAttribute = original.getAttribute("parse");
if (parseAttribute.equals("text")) {
parse = false;
}
}
if (parse) {
// checks for equality (OK) or identity (not OK)????
if (bases.contains(remote)) {
// need to figure out how to get file and number where
// bad include occurs????
throw new CircularIncludeException(
"Circular XInclude Reference to "
+ remote + " in " );
}
try {
parser.parse(remote);
Document doc = parser.getDocument();
bases.push(remote);
// this method need to remove DocType node if any
NodeList docChildren = doc.getChildNodes();
for (int i = 0; i < docChildren.getLength(); i++) {
Node node = docChildren.item(i);
if (node instanceof Element) {
result.add(resolve((Element) node, bases, resolved));
}
else if (node instanceof DocumentType) continue;
else result.add(node);
}
bases.pop();
}
// Make this configurable
catch (SAXException e) {
XIncludeException ex = new MalformedResourceException("Document "
+ remote + " is not well-formed.");
ex.setRootCause(e);
throw ex;
}
catch (IOException e) {
XIncludeException ex
= new UnavailableResourceException("Document not found: "
+ remote);
ex.setRootCause(e);
throw ex;
}
}
else { // insert text
String s = downloadTextDocument(remote);
result.add(resolved.createTextNode(s));
}
}
// not an include element
else { // recursively process children
// still need to adjust bases here????
// replace nodes instead
// Do I need to explicitly attach attributes here or does
// importing take care of that????
Element copy = (Element) resolved.importNode(original, false);
NodeList children = original.getChildNodes();
for (int i = 0; i < children.getLength(); i++) {
Node n = children.item(i);
if (n instanceof Element) {
Element e = (Element) n;
NodeList kids = resolve(e, bases, resolved);
for (int j = 0; j < kids.getLength(); j++) {
copy.appendChild(kids.item(j));
}
}
else {
copy.appendChild(resolved.importNode(n, true));
}
}
result.add(copy);
}
return result;
}
/**
* <p>
* This utility method reads a document at a specified URL
* and returns the contents of that document as a <code>Text</code>.
* It's used to include files with <code>parse="text"</code>
* </p>
*
* @param url URL of the document that will be stored in
* <code>String</code>.
* @return Text The document retrieved from the source <code>URL</code>
* or an error message if the document can't be retrieved.
* Note: throwing an exception might be better here. I should
* at least allow the setting of the error message.
* @throws UnavailableResourceException if the requested document cannot
be downloaded from the specified URL.
*/
private static String downloadTextDocument(String url)
throws UnavailableResourceException {
URL source;
try {
source = new URL(url);
}
catch (MalformedURLException e) {
UnavailableResourceException ex =
new UnavailableResourceException("Unresolvable URL " + url);
ex.setRootCause(e);
throw ex;
}
StringBuffer s = new StringBuffer();
try {
InputStream in = new BufferedInputStream(source.openStream());
// does XInclude give you anything to specify the character set????
InputStreamReader reader = new InputStreamReader(in, "8859_1");
int c;
while ((c = in.read()) != -1) {
s.append((char) c);
}
return s.toString();
}
catch (IOException e) {
UnavailableResourceException ex = new UnavailableResourceException(
"Document not found: " + source.toExternalForm());
ex.setRootCause(e);
throw ex;
}
}
/**
* <p>
* The driver method for the XIncluder program.
* I'll probably move this to a separate class soon.
* </p>
*
* @param args contains the URLs and/or filenames
* of the documents to be procesed.
*/
public static void main(String[] args) {
DOMParser parser = new DOMParser();
for (int i = 0; i < args.length; i++) {
try {
parser.parse(args[i]);
Document input = parser.getDocument();
// absolutize URL
String base = args[i];
if (base.indexOf(':') < 0) {
File f = new File(base);
base = f.toURL().toExternalForm();
}
Document output = resolve(input, base);
// need to set encoding on this to Latin-1 and check what
// happens to UTF-8 curly quotes
OutputFormat format = new OutputFormat("XML", "ISO-8859-1", false);
format.setPreserveSpace(true);
XMLSerializer serializer
= new XMLSerializer(System.out, format);
serializer.serialize(output);
}
catch (Exception e) {
System.err.println(e);
e.printStackTrace();
}
}
}
}
// I need to create NodeLists in a parser independent fashion
class XIncludeNodeList implements NodeList {
private List data = new ArrayList();
// could easily expose more List methods if they seem useful
public void add(int index, Node node) {
data.add(index, node);
}
public void add(Node node) {
data.add(node);
}
public void add(NodeList nodes) {
for (int i = 0; i < nodes.getLength(); i++) {
data.add(nodes.item(i));
}
}
public Node item(int index) {
return (Node) data.get(index);
}
// copy DOM JavaDoc
public int getLength() {
return data.size();
}
}XInclude Specification: http://www.w3.org/TR/xinclude
An inband means of specifying the proper URI for a document that can succeed even if out-of-band mechanisms aren't available.
A means of specifying the proper base URI which relative URLs are relative to, even if the document itself is copied to a different location.
An XML replacement for the HTML BASE element
<slide xml:base="http://www.ibiblio.org/xml/slides/sd2001east/xlinks/">
<title>The xml:base attribute</title>
...
<previous xlink:type="simple" xlink:href="What_Is_XBase.xml"/>
<next xlink:type="simple" xlink:href="xbaseexample.xml"/>
</slide>
May be attached to any element to set the base URI for that element and its descendants
The xml prefix is automatically bound
to the http://www.w3.org/XML/1998/namespace URI
The value should be an absolute URI
<COURSE xmlns:xlink="http://www.w3.org/1999/xlink"
xml:base="http://www.ibiblio.org/javafaq/course/"
xlink:type="extended">
<TOC xlink:type="locator" xlink:href="index.html" xlink:label="index"/>
<CLASS xlink:type="locator" xlink:label="class"
xlink:href="week1.xml"/>
<CLASS xlink:type="locator" xlink:label="class"
xlink:href="week2.xml"/>
<CLASS xlink:type="locator" xlink:label="class"
xlink:href="week3.xml"/>
<CLASS xlink:type="locator" xlink:label="class"
xlink:href="week4.xml"/>
<CLASS xlink:type="locator" xlink:label="class"
xlink:href="week5.xml"/>
<CLASS xlink:type="locator" xlink:label="class"
xlink:href="week6.xml"/>
<CLASS xlink:type="locator" xlink:label="class"
xlink:href="week7.xml"/>
<CLASS xlink:type="locator" xlink:label="class"
xlink:href="week8.xml"/>
<CLASS xlink:type="locator" xlink:label="class"
xlink:href="week9.xml"/>
<CLASS xlink:type="locator" xlink:label="class"
xlink:href="week10.xml"/>
<CLASS xlink:type="locator" xlink:label="class"
xlink:href="week11.xml"/>
<CLASS xlink:type="locator" xlink:label="class"
xlink:href="week12.xml"/>
<CLASS xlink:type="locator" xlink:label="class"
xlink:href="week13.xml"/>
<CONNECTION xlink:type="arc" from="index" to="class"/>
<CONNECTION xlink:type="arc" from="class" to="index"/>
</COURSE>
"index.html" now resolves to the URI "http://www.ibiblio.org/javafaq/course/index.html"
"week1.xml" resolves to the URI "http://www.ibiblio.org/javafaq/course/week1.xml"
"week2.xml" resolves to the URI "http://www.ibiblio.org/javafaq/course/week2.xml"
"week3.xml" resolves to the URI "http://www.ibiblio.org/javafaq/course/week3.xml"
etc.
How does it interact with XHTML? in particular,
the XHTML base
element?
Browser and other application support?
XML Base Specification: http://www.w3.org/TR/xmlbase
The many advantages of descriptive pointing are crucial for a scalable, generic pointing system. Descriptive pointing is crucial for all the same reasons that descriptive markup is crucial to documents, and that making links first-class objects is crucial to linking. It is also clearly feasible, as shown by multiple implementations of the prior WDs from the XML WG, and of TEI extended pointers.--XML Linking Working Group, XML XPointer Requirements
Why Use XPointers?
XPointer Examples
A Concrete Example
Location Paths, Steps, and Sets
Axes
Node Tests
Predicates
Functions that Return Node Sets
Points
Ranges
Child Sequences
XPointer, the XML Pointer Language, defines an addressing scheme for individual parts of an XML document.
XLinks point to a URI (in practice, a URL) that specifies a particular resource.
The URI may include an XPointer part that more specifically identifies the desired part or element of the targeted resource or document.
XPointers use the same XPath syntax you're familiar with from XSL transformations to identify the parts of the document they point to, along with a few additional pieces.
The element with a given ID
All elements that possess a certain attribute
The first element of a certain type
The last element whose class attribute has the value pending.
The seventh element of a given type
The first child of the seventh element
and many more including combinations of these addresses...
xpointer(id("ebnf"))
xpointer(descendant::language[position()=2])
ebnf
xpointer(/child::spec/child::body/child::*/child::language[position()=2])
/1/14/2
xpointer(id("ebnf"))xpointer(id("EBNF"))
The XPointer does not specify the document. A URI does.
XPointers can be used as fragment identifiers
in a URI after a #
For example,
http://www.w3.org/TR/1998/REC-xml-19980210.xml#xpointer(id("ebnf"))
http://www.w3.org/TR/1998/REC-xml-19980210.xml#xpointer(descendant::language[position()=2])
http://www.w3.org/TR/1998/REC-xml-19980210.xml#ebnf
http://www.w3.org/TR/1998/REC-xml-19980210.xml#xpointer(/child::spec/child::body/child::*/child::language[position()=2])
http://www.w3.org/TR/1998/REC-xml-19980210.xml#/1/14/2
http://www.w3.org/TR/1998/REC-xml-19980210.xml#xpointer(id("ebnf"))xpointer(id("EBNF"))
<SPECIFICATION xmlns:xlink="http://www.w3.org/1999/xlink" xlink:type="simple"
xlink:href="http://www.w3.org/TR/1998/REC-xml-19980210.xml#xpointer(id('ebnf'))">
xlink:actuate="onRequest" xlink:show="replace">
Extensible Markup Language (XML) 1.0
</SPECIFICATION>
<?xml version="1.0"?>
<!DOCTYPE FAMILYTREE [
<!ELEMENT FAMILYTREE (PERSON | FAMILY)*>
<!-- PERSON elements -->
<!ELEMENT PERSON (NAME*, BORN*, DIED*, SPOUSE*)>
<!ATTLIST PERSON
ID ID #REQUIRED
FATHER CDATA #IMPLIED
MOTHER CDATA #IMPLIED
>
<!ELEMENT NAME (#PCDATA)>
<!ELEMENT BORN (#PCDATA)>
<!ELEMENT DIED (#PCDATA)>
<!ELEMENT SPOUSE EMPTY>
<!ATTLIST SPOUSE IDREF IDREF #REQUIRED>
<!--FAMILY-->
<!ELEMENT FAMILY (HUSBAND?, WIFE?, CHILD*) >
<!ATTLIST FAMILY ID ID #REQUIRED>
<!ELEMENT HUSBAND EMPTY>
<!ATTLIST HUSBAND IDREF IDREF #REQUIRED>
<!ELEMENT WIFE EMPTY>
<!ATTLIST WIFE IDREF IDREF #REQUIRED>
<!ELEMENT CHILD EMPTY>
<!ATTLIST CHILD IDREF IDREF #REQUIRED>
]>
<FAMILYTREE>
<PERSON ID="p1">
<NAME>Domeniquette Celeste Baudean</NAME>
<BORN>21 Apr 1836</BORN>
<DIED>Unknown</DIED>
<SPOUSE IDREF="p2"/>
</PERSON>
<PERSON ID="p2">
<NAME>Jean Francois Bellau</NAME>
<SPOUSE IDREF="p1"/>
</PERSON>
<PERSON ID="p3" FATHER="p2" MOTHER="p1">
<NAME>Elodie Bellau</NAME>
<BORN>11 Feb 1858</BORN>
<DIED>12 Apr 1898</DIED>
<SPOUSE IDREF="p4"/>
</PERSON>
<PERSON ID="p4" FATHER="p2" MOTHER="p1">
<NAME>John P. Muller</NAME>
<SPOUSE IDREF="p3"/>
</PERSON>
<PERSON ID="p7">
<NAME>Adolf Eno</NAME>
<SPOUSE IDREF="p6"/>
</PERSON>
<PERSON ID="p6" FATHER="p2" MOTHER="p1">
<NAME>Maria Bellau</NAME>
<SPOUSE IDREF="p7"/>
</PERSON>
<PERSON ID="p5" FATHER="p2" MOTHER="p1">
<NAME>Eugene Bellau</NAME>
</PERSON>
<PERSON ID="p8" FATHER="p2" MOTHER="p1">
<NAME>Louise Pauline Bellau</NAME>
<BORN>29 Oct 1868</BORN>
<DIED>3 May 1938</DIED>
<SPOUSE IDREF="p9"/>
</PERSON>
<PERSON ID="p9">
<NAME>Charles Walter Harold</NAME>
<BORN>about 1861</BORN>
<DIED>about 1938</DIED>
<SPOUSE IDREF="p8"/>
</PERSON>
<PERSON ID="p10" FATHER="p2" MOTHER="p1">
<NAME>Victor Joseph Bellau</NAME>
<SPOUSE IDREF="p11"/>
</PERSON>
<PERSON ID="p11">
<NAME>Ellen Gilmore</NAME>
<SPOUSE IDREF="p10"/>
</PERSON>
<PERSON ID="p12" FATHER="p2" MOTHER="p1">
<NAME>Honore Bellau</NAME>
</PERSON>
<FAMILY ID="f1">
<HUSBAND IDREF="p2"/>
<WIFE IDREF="p1"/>
<CHILD IDREF="p3"/>
<CHILD IDREF="p5"/>
<CHILD IDREF="p6"/>
<CHILD IDREF="p8"/>
<CHILD IDREF="p10"/>
<CHILD IDREF="p12"/>
</FAMILY>
<FAMILY ID="f2">
<HUSBAND IDREF="p7"/>
<WIFE IDREF="p6"/>
</FAMILY>
</FAMILYTREE>
Many (though not all) XPointers are location paths. These are the same location paths used by XSLT.
Location paths are built from location steps.
Each location step specifies a point in the targeted document, generally relative to some other well-known point such as the start of the document or another location step. This well-known point is called the context node.
A location step has three parts:
The axis
The node test
An optional predicate
axis::node-test[predicate]
child::PERSON[position()=2]
The axis tells you in what direction to search from the context node.
The node test tells you which nodes to consider along the axis.
The predicate is a boolean expression that tests each node in that set. If that expression returns false, then the node is removed from the set.
xpointer(/child::FAMILYTREE/child::PERSON[position()=3])
The location path of this XPointer is
/child::FAMILYTREE/child::PERSON[position()=3].
It is built from two location steps:
/child::FAMILYTREE
child::PERSON[position()=3]
It identifies the single node:
<PERSON ID="p3" FATHER="p2" MOTHER="p1">
<NAME>Elodie Bellau</NAME>
<BORN>11 Feb 1858</BORN>
<DIED>12 Apr 1898</DIED>
<SPOUSE IDREF="p4"/>
</PERSON>
xpointer(/child::FAMILYTREE/child::PERSON[position()>3])
Identifies all PERSON element nodes after Elodie Bellau
XPath defines twelve axes along which an XPointer may search for nodes
These depend on context to determine exactly what they point to.
For instance, consider this location path:
id("p6")/child::NAME
id() function that returns a
node set containing the element with the ID type attribute whose
value is p6. This provides a context node for the
following location step along the relative child
axis. Other axes include
ancestor
descendant
self
ancestor-or-self
descendant-or-self
attribute
Each selects nodes from a
particular subset of the nodes in the document. For instance,
the following axis selects from nodes that come
after the context node. The preceding axis selects
from nodes that come before the context node.
| Axis | Selects From |
ancestor |
the parent of the context node, the parent of the parent of the context node, the parent of the parent of the parent of the context node, and so forth back to the root node |
ancestor-or-self |
the ancestors of the context node and the context node itself |
attribute |
the attributes of the context node |
child |
the immediate children of the context node |
descendant |
the children of the context node, the children of the children of the context node, and so forth |
descendant-or-self |
the context node itself and its descendants |
following |
all nodes that start after the end of the context node, excluding attribute and namespace nodes |
following-sibling |
all nodes that start after the end of the context node and have the same parent as the context node |
parent |
the unique parent node of the context node |
preceding |
all nodes that end before the beginning of the context node, excluding attribute and namespace nodes |
preceding-sibling |
all nodes that start before the beginning of the context node and have the same parent as the context node |
self |
the context node |
There are ten node tests in XPointer, eight from XPath and two new ones:
name*prefix:*@namenode()text()comment()processing-instruction()point()range()A node test is attached to an axis to specify which nodes along the axis are chosen.
For example:
/descendant::body/child::*/attribute::xlink:*
Each location step can contain zero or more predicates that further restrict which nodes an XPointer points to. In most non-trivial cases a predicate is necessary to pick the one node from a node set that you want.
Each predicate contains a boolean
expression in square brackets ([]) that further
winnows the node set.
This allows an XPointer to select nodes according to many different criteria. For example, you can select:
All elements that have a specified attribute
All elements that have a specified attribute with a specified value
The first element that contains a specified child element
An element whose text content includes a specified string
All elements that are not the first or last children of their parents
All elements whose value is a number
All elements whose value is a number greater than 100
XPath predicate expressions are ultimately converted to a boolean after all calculations are finished. Non-boolean results are converted as follows:
A number is true if it's equal to the position of the context node, false otherwise.
An empty node set is false; all other node sets are true.
A zero length string is false; all other strings are true (including the string "false")
The predicate expression is evaluated for each node in the context node list. Each node for which the expression ultimately evaluates to false is removed from the list. Thus only those nodes that satisfy the predicate remain.
Probably the function most frequently used in XPointer
predicates is position(). This returns the index of
the node in the context node list. This allows you to find the
first, second, third, or other indexed node.
You can compare
positions using the various relational operators like
<, >, =,
!=, >=, and <=.
xpointer(/child::FAMILYTREE/child::*[position()=1])
xpointer(/child::FAMILYTREE/child::*[position()=2])
xpointer(/child::FAMILYTREE/child::*[position()=3])
xpointer(/child::FAMILYTREE/child::*[position()=4])
xpointer(/child::FAMILYTREE/child::*[position()=5])
xpointer(/child::FAMILYTREE/child::*[position()=6])
xpointer(/child::FAMILYTREE/child::*[position()=7])
xpointer(/child::FAMILYTREE/child::*[position()=8])
xpointer(/child::FAMILYTREE/child::*[position()=9])
xpointer(/child::FAMILYTREE/child::*[position()=10])
xpointer(/child::FAMILYTREE/child::*[position()=11])
xpointer(/child::FAMILYTREE/child::*[position()=12])
xpointer(/child::FAMILYTREE/child::*[position()=13])
xpointer(/child::FAMILYTREE/child::*[position()=14])
xpointer(/child::FAMILYTREE/child::*[1])
xpointer(/child::FAMILYTREE/child::*[2])
xpointer(/child::FAMILYTREE/child::*[3])
xpointer(/child::FAMILYTREE/child::*[4])
xpointer(/child::FAMILYTREE/child::*[5])
xpointer(/child::FAMILYTREE/child::*[6])
xpointer(/child::FAMILYTREE/child::*[7])
xpointer(/child::FAMILYTREE/child::*[8])
xpointer(/child::FAMILYTREE/child::*[9])
xpointer(/child::FAMILYTREE/child::*[10])
xpointer(/child::FAMILYTREE/child::*[11])
xpointer(/child::FAMILYTREE/child::*[12])
xpointer(/child::FAMILYTREE/child::*[13])
xpointer(/child::FAMILYTREE/child::*[14])
id()
here()
origin()
The last two, here() and origin()
are XPointer extensions to XPath that are not available in XSLT.
The id() function
selects the element in the
document that has an ID type attribute with a specified value.
For example, consider the URI http://www.theharolds.com/genealogy.xml#xpointer(id("p12")). If you look back at Listing 17-1, you find this element:
<PERSON ID="p12" FATHER="p2" MOTHER="p1">
<NAME>Honore Bellau</NAME>
</PERSON>
Since ID pointers are so common and so useful, there's also
a shortcut for this. If all you want to do is point to a
particular element with a particular ID, you can skip all the
xpointer(id("")) fru-fru and just use the
bare ID after the #
like this:
http://www.theharolds.com/genealogy.xml#p12
Consider a simple slide show. In this example,
here()/following::SLIDE[1] refers to the next slide in the
show. here()/preceding::SLIDE[1] refers to the previous slide
in the show. Presumably this would be used in conjunction with a
style sheet that showed one slide at a time.
<?xml version="1.0"?>
<SLIDESHOW xmlns:xlink="http://www.w3.org/1999/xlink">
<SLIDE>
<H1>Welcome to the slide show!</H1>
<BUTTON xlink:type="simple"
xlink:href="here()/following::SLIDE[1]">
Next
</BUTTON>
</SLIDE>
<SLIDE>
<H1>This is the second slide</H1>
<BUTTON xlink:type="simple"
xlink:href="here()/preceding::SLIDE[1]">
Previous
</BUTTON>
<BUTTON xlink:type="simple"
xlink:href="here()/following::SLIDE[1]">
Next
</BUTTON>
</SLIDE>
<SLIDE>
<H1>This is the second slide</H1>
<BUTTON xlink:type="simple"
xlink:href="here()/preceding::SLIDE[1]">
Previous
</BUTTON>
<BUTTON xlink:type="simple"
xlink:href="here()/following::SLIDE[1]">
Next
</BUTTON>
</SLIDE>
<SLIDE>
<H1>This is the third slide</H1>
<BUTTON xlink:type="simple"
xlink:href="here()/preceding::SLIDE[1]">
Previous
</BUTTON>
<BUTTON xlink:type="simple"
xlink:href="here().following(1,SLIDE)">
Next
</BUTTON>
</SLIDE>
...
<SLIDE>
<H1>This is the last slide</H1>
<BUTTON xlink:type="simple"
xlink:href="here()/preceding::SLIDE[1]">
Previous
</BUTTON>
</SLIDE>
</SLIDESHOW>
Generally, the here() location term is only used in fully
relative URIs in XLinks. If any URI part is included, it must be
the same as the URI of the current document.
The origin() function is much the same as here();
that is, it refers to the source of a link. However,
origin() is used in out-of-line links where the
link is not actually present in the source document. It points to the
element in the source document from which the user activated the link.
Every point is either between two nodes or between two characters in the parsed character data of a document. To make sense of this you have to remember that parsed character data is part of a text node. For instance, consider this very simple but well-formed XML document:
<GREETING>
Hello
</GREETING>
There are exactly three nodes and 13 distinct points in this document. In order the points are:
The point before the root node
The point before the GREETING element node
The point before the text node containing the text "Hello" (as well as assorted white space)
The point before the white space between <GREETING> and Hello.
The point before the first H in Hello
The point between the H and the e in Hello
The point between the e and the l in Hello
The point between the l and the l in Hello
The point between the l and the o in Hello
The point after the o in Hello
The point after the white space between Hello and </GREETING>.
The point after the GREETING element.
The point after the root node.
The exact details of the white space in the document are not considered here. XPointer collapses all runs of white space to a single space.
In some applications it may be important to specify a range across a document rather than a particular point in the document. For instance, the selection a user makes with a mouse is not necessarily going to match up with any one element or node. It may start in the middle of one paragraph, extend across a heading and a picture and then into the middle of another paragraph two pages down. Any such contiguous area of a document can be described with a range.
A range begins at one point and continues until another point.
The start- and end-points of the range are identified by location paths.
The first point in the location set the start path identifies is the start-point.
The last point in the location set the end path identifies is the end-point of the range.
To specify a range, you append
/range-to(end-point)
to a location path specifying the start-point of the range.
The parentheses contain a location path specifying the end-point of the range.
For example, suppose you want to select everything
between the first PERSON element and the last
PERSON element
xpointer(/child::PERSON[position() = 1]/range-to(/child::PERSON[position() = last()]))
range(location-set) The range is the minimum range necessary to cover the entire location.
range-inside(location-set) Returns a location set containing the interiors of each of the locations in the input.
start-point(location-set) Returns a location set that contains
one point representing the first point of each location in
the input location set.
For example,
start-point(//PERSON[1])
Returns the point immediately before the first PERSON element.
start-point(//PERSON)
returns the set of points immediately before each PERSON element.
end-point(location-set) The same as start-point() except that it returns the
points immediately after each location in its input.
string-range(node-set,substring,index,length)
A string range points to an occurrence of a specified string, or a substring of a given string in the text (not markup) of the document.
string-range()
takes as arguments a node set to search and a substring to
search for.
string-range() returns a node set containing one range for each
non-overlapping match to the string.
By default, the range returned starts before the first matched character and encompasses all the matched characters.
You can also provide optional index and length arguments indicating how many characters after the match the range should start and how many characters after the start the range should continue.
For example, this XPointer finds all occurrences of the string "Harold":
xpointer(string-range(/,"Harold"))
You can change the first argument to specify what nodes you want
to look in. For example, this XPointer finds all occurrences of
the string "Harold" in NAME elements:
xpointer(string-range(//NAME,"Harold"))
String ranges may have node tests. Thus this XPointer finds only the first occurrence of the string "Harold" in the document:
xpointer(string-range(/,"Harold")[position()=1])
This targets the position immediately preceding the word Harold
in Charles Walter Harold's NAME element. This is not
the same as pointing at the entire NAME element as an
element-based selector would do.
A third numeric argument targets a particular position in the string. For example, this targets the point immediately following the first occurrence of the string "Harold" because Harold has six letters:
xpointer(string-range(/,"Harold",6)[position()=1])
An optional fourth argument specifies the number of characters to select. For example, this URI selects the "old" from the first occurrence of the entire string "Harold":
xpointer(string-range(/,"Harold",4,3)[position()=1])
When matching strings, case is considered. All white space is condensed to a single space. Markup characters are ignored.
Normally, the only way to get a point location is by getting
a range first and using the
start-point() or end-point() functions
For example, to
select the point immediately before the D in Domeniquette
Celeste Baudean's NAME element,
start-point(range-inside(/child::FAMILYTREE/descendant::*[position()=1]/child::NAME/))
XPointers may appear in non-XML documents where namespace prefixes are not defined.
You use an xmlns() scheme to
map a prefix to a URI. For example,
xmlns(svg=http://www.w3.org/2000/svg) xpointer(//svg:polygon[3])
A child sequence is a shortcut for XPointers that consist of nothing but a series of child relative location steps counting down from the root node, each of which selects a particular child by position only.
The shortcut is to use only the position number and the slashes that separate individual elements from each other, like this:
http://www.theharolds.com/genealogy.xml#/1/4
/1/4 is a child sequence that says to select the
fourth child element of the first child element of the root.
Child sequences may include an initial ID. In that case the
counting begins from the element with that ID rather than from
the root. For example, John P. Muller's PERSON element has an ID
attribute with the value p4. Consequently the XPointer p4/1
points to his NAME element and p4/2 points to his SPOUSE
element.
Each child sequence always points to a single element. You cannot use child sequences with any other relative location steps. You cannot use them to select elements of a particular type. You cannot use them to select attribute or strings. You can only use them to select a single element by its relative location in the tree.
XPointers refer to particular parts of or locations in XML documents.
The syntax of an XPointer is the keyword xpointer, followed
by parentheses containing an XPath expression that returns a
node set.
The id() function points to an element with a
specified value for an ID type attribute.
Location steps can be chained to make more sophisticated location paths.
Each location step contains an axis, a node test, and zero or more predicates.
Relative location steps select nodes in a document based on their relationship to a context node.
The self axis points to the context node. It
can be abbreviated as a period (.).
The parent axis points to the node that
contains the context node. It can be abbreviated as a double
period (..).
The child axis points to immediate children of
the context node. It can be abbreviated simply by a node test.
The descendant axis points to all elements
contained in the context node. It can be abbreviated as a double
slash (//).
The descendant-or-self axis points to all
elements contained in the context node as well as the context
node itself.
The ancestor axis points to an element that
contains the context node.
The ancestor-or-self axis points to all
elements that contain the context node as well as the context
node itself.
The preceding axis points to any element that
comes before the context node.
The following axis points to any element
following the context node.
The preceding-sibling axis selects from sibling
elements that precede the context node.
The following-sibling axis selects from sibling
elements that follow the context node.
The attribute axis points to an attribute of the context
node. It can be abbreviated as a @ sign.
The node test of a relative location step is normally an
element name, but may also be * to
select all elements, @* to
select all attributes, @name
to select all attributes with the given name,
prefix:* to select all
elements in the specified namespace,
or one of the keywords
comment(), text(),
processing-instruction(), node(),
point() or range().
The optional predicate of a relative location step is an XPath boolean expression enclosed in square brackets that further narrows down the node set the XPointer refers to.
A point indicates a position preceding or following a node or a character.
A range identifies the parsed character data between two points.
The string-range() function points to a
specified block of text.
A child sequence points to an element by counting children from the root.
This presentation: http://www.ibiblio.org/xml/slides/sd2001east/xinclude
XPointer Specification: http://www.w3.org/TR/xptr
Chapter 20 of the XML Bible, 2nd Edition: http://www.ibiblio.org/xml/books/bible2/chapters/ch20.html
Chapter 10 of XML in a Nutshell
This presentation: http://www.ibiblio.org/xml/slides/sd2001east/xinclude
XML Base Specification: http://www.w3.org/TR/xmlbase
XInclude Specification: http://www.w3.org/TR/xinclude
XPath Specification: http://www.w3.org/TR/xpath
XPointer Specification: http://www.w3.org/TR/xptr
XML Bible, Gold edition
Elliotte Rusty Harold
Hungry Minds, 2001
ISBN 0-7645-4819-0