Resolving Entities - XML - Java Programming Language

You've already seen how to interact with content in the XML document you're parsing (using ContentHandler), and how to deal with error conditions (ErrorHandler). Both of these are concerned specifically with the data in an XML document. What I haven't talked about is the process by which the parser goes outside of the document and gets data. For example, consider a simple entity reference in an XML document:

<FM>
<P>Text placed in the public domain by Moby Lexical Tools, 1992.</P>
<P>SGML markup by Jon Bosak, 1992-1994.</P>
<P>XML version by Jon Bosak, 1996-1998.</P>
<P>&usage-terms;</P>
</FM>

Your schema then indicates to the parser how to resolve that entity:

<!ENTITY usage-terms SYSTEM "http://www.newInstance.com/entities/usage-terms.xml">

At parse time, the usage-terms entity reference will be expanded (in this case, to "This work may be freely copied and distributed worldwide.", as seen in Figure 4-1).

The usage-terms entity was resolved to a URI, which was then parsed and inserted into the document

However, there are several cases where you might not want this "default" behavior:

You don't have network access, so you want the entity to resolve to a local copy of the referenced document (perhaps a version you've downloaded yourself).
You want to substitute your own content for the content specified in the schema.

You can short-circuit normal entity resolution using org.xml.sax.EntityResolver. This interface does exactly what it says: resolves entities. More important, it allows you to get involved in the entity resolution process. The interface defines only a single method, as shown in .

There's not much to the EntityResolver class; just a single, albeit useful, method

To insert your own logic into the resolution process, create an implementation of this interface, and register it with your XMLReader instance through setEntityResolver( ). Once that's done, every time the reader comes across an entity reference, it passes the public ID and system ID for that entity to the resolveEntity( ) method of your EntityResolver implementation. Typically, the XML reader resolves the entity through the specified public or system ID. If you want to accept this default behavior in your own EntityResolver implementation, just return null from your version of resolveEntity( ). In fact, you should always make sure that whatever code you add to your resolveEntity( ) implementation, it returns null in the default case. In other words, start with an implementation class that looks like Example 4-1.

Example Before coding in special entity resolution, always ensure that any unhandled cases result in a null return value (and therefore normal entity resolution)

package javaxml3;
import java.io.IOException;
import org.xml.sax.EntityResolver;
import org.xml.sax.InputSource;
import org.xml.sax.SAXException;
public class SimpleEntityResolver implements EntityResolver {
 public InputSource resolveEntity(String publicID, String systemID)
 throws IOException, SAXException {
 // In the default case, return null
 return null; }
}

Of course, things are more interesting when you don't return null. If you return an InputSource from this method, that InputSource is used in resolution of the entity reference, rather than the public or system ID specified in your schema. In other words, you can specify your own data instead of letting the reader handle resolution on its own. As an example, create a usage-terms.xml file on your local machine:

Any use of this file could result in your <i>imminent</i> destruction.
Consider yourself warned!

Now you can indicate that this file should be used via resolveEntity( ):

private static final String USAGE_TERMS_ID =
 "http://www.newInstance.com/entities/usage-terms.xml";
private static final String USAGE_TERMS_LOCAL_URI =
 "/your/path/to/usage-terms.xml";
public InputSource resolveEntity(String publicID, String systemID)
 throws IOException, SAXException {
 if (systemID.equals(USAGE_TERMS_ID)) {
 return new InputSource(USAGE_TERMS_LOCAL_URI);
 }
 // In the default case, return null
 return null;
}

Be sure to change the USAGE_TERMS_LOCAL_URI to match your own filesystem path.

You can see that instead of allowing resolution to the online resource, an InputSource that provides access to the local version of copyright.xml is returned. If you recompile your source file and run the tree viewer, you can visually verify that this local copy is used. You register this resolver on your XMLReader via the setEntityResolver( ) method, as shown here (using the SAXTreeViewer example again):

// Register content handler reader.setContentHandler(jTreeHandler);
// Register error handler reader.setErrorHandler(jTreeHandler);
// Register entity resolver reader.setEntityResolver(new SimpleEntityResolver( ));
// Turn on validation featureURI = "http://xml.org/sax/features/validation";
reader.setFeature(featureURI, true);
// Turn on schema validation, as well featureURI = "http://apache.org/xml/features/validation/schema";
reader.setFeature(featureURI, true);

shows the usage-terms entity reference expanded, using the local file, rather than the URI specified in the schema.

This time, the local entity is used (and parsed, as seen by the expanded i element)

In real-world apps, resolveEntity( ) tends to become a lengthy laundry list of if/then/else blocks, each one handling a specific system or public ID. And this brings up an important point: try to avoid this method becoming a kitchen sink for IDs. If you no longer need a specific resolution to occur, remove the if clause for it. Additionally, try to use different EntityResolver implementations for different apps, rather than creating one generic implementation for all your apps. Doing this avoids code bloat, and more important, speeds up entity resolution. If you have to wait for your reader to run through 50 String.equals( ) comparisons, you can really bog down an app. Be sure to put references accessed often at the top of the if/else stack, as well, so they are encountered first and result in quicker entity resolution. Finally, I want to make one more recommendation concerning your EntityResolver implementations. You'll notice that I defined my implementation in a separate class file, while the ErrorHandler, ContentHandler, and (as you'll see in "Notations and Unparsed Entities") DTDHandler implementations were in the same source file as parsing occurred in. That wasn't an accident! You'll find that the way you deal with content, errors, and DTDs is fairly static. You write your program, and that's it. When you make changes, you're performing a larger code rewrite, so recompiling your core parsing program is a given. However, you'll make many changes to the way you want your app to resolve entities. Depending on the machine you're on, the type of client you're deploying to, and what (and where) documents are available, you'll often use several different versions of an EntityResolver implementation. To allow for rapid changes to this implementation without causing editing or recompilation of your core parsing code, I use a separate source file for EntityResolver implementations; I suggest you do the same. And with that, you should know all that you need to know about resolving entities in your apps using SAX.