One of the basic building blocks of the SAX API is the process of entity resolution; this process is handled through the org.xml.sax.EntityResolver interface. Unfortunately, the EntityResolver interface is often ignored by all but the most advanced SAX developers. This shouldn't be the case, as this interface allows all sorts of performance improvements in your applications. If you use a clever EntityResolver implementation, you can dramatically speed up parsing and simplify resource management.

A simple entity resolution

At its simplest, an EntityResolver tells a SAX parser implementation how to look up resources specified in an XML document. Listing 1 shows an XML document fragment with an entity reference.

<footer>
  <smallText>&copyright;</smallText>
</footer>

This simple document fragment shown in Listing 1 illustrates an entity reference (named copyright). When a SAX parsing process runs across this entity reference, it has to resolve the entity into another piece of content. The parsing process first consults the document's DTD or XML schema for a definition like that shown in Listing 2.

<!ENTITY copyright 
    PUBLIC "-//IBM//TEXT DeveloperWorks Copyright//EN"
    "copyright.xml"
>

From this reference, the parser figures out the public ID (-//IBM//TEXT DeveloperWorks Copyright//EN) and system ID (copyright.xml) of the entity reference. The parsing process then checks to see if an EntityResolver implementation has been registered on the current XMLReader implementation. If so, it invokes the resolveEntity() method with the public and system IDs extracted from the DTD or schema. Listing 3 shows an EntityResolver implementation at its simplest.

import java.io.IOException;

import org.xml.sax.SAXException;
import org.xml.sax.EntityResolver;
import org.xml.sax.InputSource;

public class SimpleEntityResolver implements EntityResolver {

    public InputSource resolveEntity(String publicId, String systemId)
        throws SAXException, IOException {

        // Returning null means use normal resolution
        return null;
    }
}

This implementation simply returns null every time which signals the parser that normal entity resolution should occur. The public ID and (subsequently) the system ID, are looked up through the Internet or local file system, as specified by the IDs of the reference. In this case, the parser resolves the public ID through the Internet, and if that fails, the parser searches for a local file called copyright.xml. The contents of this process are then inserted into the document.

Looking up resources on the Internet is time-consuming, and slows your application down every time the document is parsed. To combat this, it is common to download all required references and resources to a local file system. To ensure that these local files are used instead of the online resources, developers often change the constraint set of the XML and point the system ID of the entity reference definition to the local copy of a file or downloaded resource. Unfortunately, this turns out to be a bad idea: It ties the reference to a specific file, on a specific file system, in a specific location.

A better solution is to leave the document's constraints alone, and package all required resources in a jar file with the XML document and Java classes used in the application. This means you'll have your libraries (like an XML parser), your application files (Java classes), your XML documents and constraints, and any resources referenced by the XML (like the copyright.xml file). When you use a jar file, deployment is very simple, as all required resources are included in the jar file. Then, add this archive to the Java classpath.

Back to top

Register the entity resolver

Your final step is to register an entity resolver that looks up entity references on the current classpath. Listing 4 shows just such a resolver.

import java.io.InputStream;
import java.io.IOException;

import org.xml.sax.SAXException;
import org.xml.sax.EntityResolver;
import org.xml.sax.InputSource;

public class ClassPathEntityResolver implements EntityResolver {

    public InputSource resolveEntity(String publicId, String systemId)
        throws SAXException, IOException {

        InputSource inputSource = null;
      
        try {
            InputStream inputStream =    
                EntityResolver.class.getResourceAsStream(
                    systemId);
            inputSource = new InputSource(inputStream);
        } catch (Exception e) {
            // No action; just let the null InputSource pass through
        }

        // If nothing found, null is returned, for normal processing
        return inputSource;
    }
}

If the system ID of your XML reference is copyright.xml, you simply put the resource in the top level of your jar file, and ensure that it is named copyright.xml. You then register an instance of the ClassPathEntityResolver with your XMLReader, and let parsing and resolution take off.

Resources

• Find out more about the SAX API at the official SAX Web site.
  
  
• Read Using an entity resolver, a previous tip by Brett McLaughlin that shows you how to use external entity references to include external content in an XML document, and how to use the SAX EntityResolver interface (developerWorks, June 2001).
  
  
• Take a closer look at SAX with the developerWorks tutorial Understanding SAX by Nicholas Chase (developerWorks, September 2001).
  
  
• Find more XML resources on the developerWorks XML zone. For a complete list of XML tips to date, check out the tips summary page.
  
  
• IBM trial software: Build your next development project with trial software available for download directly from developerWorks.
  
  
• Find out how you can become an IBM Certified Developer in XML and related technologies.
  
  
• Want us to send you useful XML tips like this every week? Sign up for the developerWorks XML Tips newsletter.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• A simple entity resolution
• Register the entity resolver
• Resources
• About the author
• Comments