Receiving Processing Instructions

Each processing instruction the parser reads is passed to the processingInstruction() method in one invocation. This includes processing instructions that occur before and after the root element. The target is given as the first argument and the data as the second argument.

public void processingInstruction(String target, String data)
    throws SAXException;

Caution

The XML declaration is technically not a processing instruction, even though it looks like one; and it is not passed to the processingInstruction() method. SAX 2.1 will add some additional features and properties for retrieving the values of the version, standalone, and encoding attributes from the XML declaration. However, until then SAX parsers do not tell client programs what was in the XML declaration or even whether the document contained an XML declaration in the first place.

Although many processing instructions such as xml-stylesheet use a pseudo-attribute format, this depends on the semantics defined for the particular target. The processingInstruction() method does not distinguish between processing instructions like xml-stylesheet that use pseudo-attributes and processing instructions like php that don’t. The data of both kinds is passed to the processingInstruction() method as a single String. If you want to split that string into attributes and values, you have to write the code to do that yourself. SAX doesn’t do it for you.

Tip

The JDOM ProcessingInstruction class is able to break up processing instructions that use pseudo-attributes into name-value pairs. Even if you’re primarily parsing with SAX, you can still use the JDOM ProcessingInstruction class to extract these pairs for processing instructions that are known to contain pseudo-attributes. For example, this SAX processingInstruction() method uses JDOM to find the value of the href attribute of an xml-stylesheet processing instruction:

  public void processingInstruction(String target, String data) {
     
    if (target.equals("xml-stylesheet")) { 
      ProcessingInstruction xml-stylesheet 
       = new ProcessingInstruction(target, data);
      String href = xml-stylesheet.getValue("href");
    }
    
  }

Of course for this to work, you’ll need to have the JDOM class library installed in your class path, and have imported at least org.jdom.ProcessingInstruction.

Example 6.11 demonstrates with a straightforward program to list the targets and data of all the processing instructions found in a document. Of course the real purpose of processing instructions is to pass their data to a separate program somehow identified by the target.

Example 6.11. A ContentHandler that prints processing instruction targets and data on System.out

import org.xml.sax.*;
import org.xml.sax.helpers.*;


public class ProcessingInstructionLister extends DefaultHandler {

  
  public void processingInstruction(String target, String data) {
     
    System.out.println("Processing Instruction:");
    System.out.println("  target: " + target);
    System.out.println("  data:   " + data);
    System.out.println();
    
  }
  
  
  public static void main(String[] args) {
      
    try {
      XMLReader parser = XMLReaderFactory.createXMLReader(
        "org.apache.xerces.parsers.SAXParser"
      );
      ContentHandler handler = new ProcessingInstructionLister();
      parser.setContentHandler(handler);
      for (int i = 0; i < args.length; i++) {  
        parser.parse(args[i]);
      }
    }
    catch (Exception e) {
      System.err.println(e);
    }
  
  }    
  
}

Here’s the output from running this program over styled_order.xml from Chapter 1. This document contains a single xml-stylesheet processing instruction. Note especially that the XML declaration is not considered to be a processing instruction and is not reported.

C:\XMLJAVA>java ProcessingInstructionLister styled_order.xml
Processing Instruction:
  target: xml-stylesheet
  data:   type="text/css" href="order.css"  

Copyright 2001, 2002 Elliotte Rusty Haroldelharo@metalab.unc.eduLast Modified October 17, 2001
Up To Cafe con Leche