XPointer (Java & XML, 2nd Edition)

16.2. XPointer

XPointer is another XML linking technology, and in fact builds on XLink's capabilities. XLink, while useful in and of itself, only allows you to refer to another document. However, there are many times when you may want to refer to a specific part of another document. This is a very common task, and is somewhat analogous to using named anchors in HTML. It is made possible by using XPointer on top of XLink; the specs build very naturally on each other, and are intended to work together. First, you want to take a look at the target document you are going to link to. If you can, ensure that this document uses id attributes in it. This will make the linking and pointing much easier. Example 16-2 shows the listing of some of the guitars that luthier Dana Bourgeois makes, and has IDs for each type.

Example 16-2. A listing of Bourgeois guitars

<?xml version="1.0"?>

<guitarTypes xmlns="http://www.bourgeoisguitars.com">
 <type model="OM" ID="OM">
  <picture url="http://www.bourgeoisguitars.com/images/vvOM.jpg"/>
  <description>Small bodied orchestra model.</description>
 </type>
 <type model="D" ID="D">
  <picture 
   url="http://www.bourgeoisguitars.com/images/ricky%20skaggs%20model.jpg"/>
  <description>Bluegrass powerhouse in a standard dreadnought shape.</description>
 </type>
 <type model="slopeD" ID="slopeD">
  <picture 
   url="http://www.bourgeoisguitars.com/images/slope%20d,%20custom%20version.jpg"/>
  <description>
    Slope shouldered dreadnought, perfect for vocal accompaniment.
  </description>
 </type>
</guitarTypes>

For the sake of discussion, assume that this document is available at http://www.bourgeoisguitars.com/guitars.xml. Instead of just referencing the entire document, which doesn't help a whole lot, XPointer allows for linking to specific parts of the document. Remember the xlink:href attribute? The value supplied to that attribute was the target of an XLink. But you can add a pound sign (#), and then an XPointer expression to these URLs. For example, the expression xpointer(id("slopeD")) refers to an element in a document with the ID "slopeD". So, to refer to the XML shown in Example 16-2, and then to the Slope D model guitar described in that document, the URL http://www.bourgeoisguitars.com/guitars.xml#xpointer(id("slopeD")) would be used. Easy enough. Let me show you a modified version of the XML document I introduced in the XLink section (Example 16-1), which describes my guitars, using some XPointer references. (Forgive the awkward formatting; I had a lot to fit on some lines.) Take a look at Example 16-3.

Example 16-3. My guitars in XML using XPointer

<?xml version="1.0"?>

<guitars xmlns="http://www.newInstance.com/about/guitars"
         xmlns:xlink="http://www.w3.org/1999/xlink">
 <guitar luthier="Bourgeois"
          xlink:type="simple"
          xlink:href=
         "http://www.bourgeoisguitars.com/guitars.xml#xpointer(id(&apos;OM&apos;))">
  <descripton xlink:type="simple"
              xlink:href="http://www.newinstance.com/pics/bougOM_front_full.jpg"
              xlink:actuate="onLoad" xlink:show="embed">
   This is a real beauty in a small body. Although this is an OM, I use it for
   flatpicking bluegrass as well as for producing some beautiful 
   fingerstyle sounds.
  </description>
 </guitar>
 <guitar luthier="Bourgeois"
         xlink:type="simple"
         xlink:href=
          "http://www.bourgeoisguitars.com/guitars.xml#xpointer(id(&apos;D&apos;))">
  <descripton xlink:type="simple"
              xlink:href="http://www.newinstance.com/pics/bougd150_con_rim2.jpg"
              xlink:actuate="onLoad" xlink:show="embed">
  Here's the holy grail in process. Dana Bourgeois is building this Brazilian 
  rosewood and adirondack bluegrass monster right now... you'll know it's 
  finished when you hear a run and your windows shatter!
  </description>
 </guitar>
</guitars>

Now my document can reference the XML content that Dana Bourgeois keeps about his guitars. If he changes this information, I don't have to worry; my document stays current because it simply links to his information. Notice that I had to "escape" the quotation marks within the XPointer expression by using & instead of an ampersand (&). However, this makes for a rather long URL to link to. Long URLs, in my experience, lead to annoying typos (and annoying formatting in a book!). Luckily, XPointer allows a handy shorthand form when linking to an element with an ID tag. Instead of using the xpointer(id("D")) form, you can simply use the value of the ID to target. In this case, that would simply be "D". I can simply combine the document in Example 16-3 to that shown in Example 16-4. Makes for a much cleaner link syntax.

Example 16-4. Using XPointer shorthand to simplify Example 16-3

<?xml version="1.0"?>

<guitars xmlns="http://www.newInstance.com/about/guitars"
         xmlns:xlink="http://www.w3.org/1999/xlink">
 <guitar luthier="Bourgeois"
          xlink:type="simple"
          xlink:href="http://www.bourgeoisguitars.com/guitars.xml#OM" >
  <descripton xlink:type="simple"
              xlink:href="http://www.newinstance.com/pics/bougOM_front_full.jpg"
              xlink:actuate="onLoad" xlink:show="embed">
   This is a real beauty in a small body. Although this is an OM, I use it for
   flatpicking bluegrass as well as for producing some beautiful 
   fingerstyle sounds.
  </description>
 </guitar>
 <guitar luthier="Bourgeois"
         xlink:type="simple"
         xlink:href="http://www.bourgeoisguitars.com/guitars.xml#D" >
  <descripton xlink:type="simple"
              xlink:href="http://www.newinstance.com/pics/bougd150_con_rim2.jpg"
              xlink:actuate="onLoad" xlink:show="embed">
   Here's the holy grail in process. Dana Bourgeois is building this Brazilian 
  rosewood and adirondack bluegrass monster right now... you'll know it's 
  finished when you hear a run and your windows shatter!
  </description>
 </guitar>
</guitars>

In addition to this direct listing, you can point to elements relative to other elements. As an example of this, my description elements in Example 16-5 have been changed to point to the image specified in the bourgeois.xml file from Example 16-2.

NOTE: For the sake of getting this lengthy URL into the code space of an O'Reilly book, I've abbreviated the URL http://www.bourgeoisguitars.com as simply http://bg.com. This isn't a valid URL, but it works for the example.

Example 16-5. Using relative links

<?xml version="1.0"?>

<guitars xmlns="http://www.newInstance.com/about/guitars"
         xmlns:xlink="http://www.w3.org/1999/xlink">
 <guitar luthier="Bourgeois"
          xlink:type="simple"
          xlink:href=
 "http://bg.com/guitars.xml#xpointer(id(&apos;OM&apos;))/descendant::picture[@url]">
  <descripton xlink:type="simple"
              xlink:href="http://www.newinstance.com/pics/bougOM_front_full.jpg"
              xlink:actuate="onLoad" xlink:show="embed">
   This is a real beauty in a small body. Although this is an OM, I use it for
   flatpicking bluegrass as well as for producing some beautiful 
   fingerstyle sounds.
  </description>
 </guitar>
 <guitar luthier="Bourgeois"
         xlink:type="simple"
         xlink:href=
  "http://bg.com/guitars.xml#xpointer(id(&apos;D&apos;))/descendant::picture[@url]" >
  <descripton xlink:type="simple"
              xlink:href="http://www.newinstance.com/pics/bougd150_con_rim2.jpg"
              xlink:actuate="onLoad" xlink:show="embed">
  Here's the holy grail in process. Dana Bourgeois is building this Brazilian 
  rosewood and adirondack bluegrass monster right now... you'll know it's 
  finished when you hear a run and your windows shatter!
  </description>
 </guitar>
</guitars>

Here, you can see that once the element referred to by the ID is found, the descendant of that element (specified by the descendant keyword) named "picture" is found. Then, the value of the attribute of that element named "url" is the final target of the link. I know that's a mouthful, but if you take it step by step, it turns out to be fairly straightforward. For more information on the huge variety of options that XPointer offers, check out the XPointer specification online at http://www.w3.org/TR/xptr.

NOTE: Notice that I did not use the shorthand form of ID links I talked about in the last section. That's because using that form of ID linking allows for only a direct link; no further linking (such as the child-traversing reference in Listing 4) is allowed without the longer form of ID linking.

XLink and XPointer stand to change how XML is linked and authored in major ways. I expect to see a variety of support in Java APIs for this once the specifications are fully supported by browsers as well, so keep an eye out.