The ProcessingInstruction Class

The ProcessingInstruction class represents an XML processing instruction such as <?xml-stylesheet href="book.xsl" type="application/xml"?> or <?php mysql_connect("database.unc.edu", "debra", "secret"); ?>. Each processing instruction has a target string, which must be a legal XML name, a value string, which may not contain the end-delimiter ?>, and a parent element (which may be null if the instruction is a child of a Document instead of an Element).

Note

At the time of this writing, JDOM only checks processing instruction targets for well-formedness. It does not check processing instruction data. However, checking data for the presence of illegal characters is on the TODO list.

Because so many (though not all) processing instructions have the pseudo-attribute format exemplified by <?xml-stylesheet href="book.xsl" type="application/xml"?>, this class also offers a second view of the instruction’s data, as a map of name-value pairs. Internally, ProcessingInstruction always stores the string form but only stores the map form if it can successfully parse the data as pseudo-attributes. If a program uses the map-based methods like getValue() and removeValue() but the actual format of the data is not pseudo-attributes, then they return null (getters). Using a setter method replaces the existing data with a pseudo-attribute.

Example 15.14. The JDOM ProcessingInstruction class

package org.jdom;

public class ProcessingInstruction 
 implements Serializable, Cloneable {

  protected String target;
  protected String rawData;
  protected Map    mapData;
  protected Object parent;

  protected ProcessingInstruction();
  public    ProcessingInstruction(String target, Map data);
  public    ProcessingInstruction(String target, String data);
  
  public Element               getParent();
  public ProcessingInstruction detach();
  public Document              getDocument();

  public String getTarget();
  public String getData();
  public List   getNames();
  public String getValue(String name);

  public ProcessingInstruction setTarget(String target) 
   throws IllegalTargetException;
  public ProcessingInstruction setData(String data);
  public ProcessingInstruction setData(Map data);
  public ProcessingInstruction setValue(String name, 
   String value);
  
  public boolean removeValue(String name);

  public String        toString();
  public final boolean equals(Object ob);
  public final int     hashCode();
  public Object        clone();

}

For example, robots and spiders that process XML documents are supposed to recognize processing instructions in the form <?robots index="yes | no" follow="yes | no"?> to decide whether or not to index and/or follow the links in an XML document. Such a robot could use this method to decide whether to index a document it had parsed:

  public static boolean canIndex(Document doc) {
    
    List content = doc.getContent();
    Iterator iterator = content.iterator();
    while (iterator.hasNext()) {
      Object o = iterator.next();
      if (o instanceof ProcessingInstruction) {
        ProcessingInstruction pi = (ProcessingInstruction) o;
        if (pi.getTarget().equals("robots")) {
          if ("no".equals(pi.getValue("index"))) return false; 
        }
      }
      else if (o instanceof Element) {
        // This is the root element. The prolog is done.
        break;
      }
    }
    
    return true;
    
  }

This method looks for the first robots processing instruction in the document’s prolog. When it finds it, it requests the value of the index pseudo-attribute and returns true if it has the value yes or the value null and false if it has the value no. If no robots processing instruction is present, or it has the wrong format, the default is to assume that indexing is permitted. A canSpider() method is almost identical except that you’d ask for the value of the follow pseudo-attribute instead.


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