4.2.1. Using an EntityResolver

public InputSource resolveEntity(String publicID, String systemID)
    throws SAXException, IOException;

You can create an implementation of this interface, and register it with your XMLReader instance (through setEntityResolver( ), not surprisingly). 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 implementation. Now you can change the normal process of entity resolution.

You can compile this class with no problems, and register it with the reader implementation used in the SAXTreeViewer class within the buildTree( ) method:

        // Create instances needed for parsing
        XMLReader reader = 
            XMLReaderFactory.createXMLReader(vendorParserClass);
        ContentHandler jTreeContentHandler = 
            new JTreeContentHandler(treeModel, base, reader);
        ErrorHandler jTreeErrorHandler = new JTreeErrorHandler( );

        // Register content handler
        reader.setContentHandler(jTreeContentHandler);

        // Register error handler
        reader.setErrorHandler(jTreeErrorHandler);
            
        // Register entity resolver
        reader.setEntityResolver(new SimpleEntityResolver( ));

        // Other instructions and parsing...

Recompiling and rerunning the example class creates no change. Of course, that's exactly what was predicted, so don't be too surprised. By always returning a null value, the process of entity resolution proceeds normally. If you don't believe that anything is happening, though, you can make this small change to echo what's going on to the system output:

    public InputSource resolveEntity(String publicID, String systemID)
        throws IOException, SAXException {
            
        System.out.println("Found entity with public ID " + publicID +
            " and system ID " + systemID);
        
        // In the default case, return null
        return null;    
    }

As always, the line breaks are purely for display purposes. In any case, you can see that both references in the XML document, for the DTD and the OReillyCopyright entity reference, are passed to the resolveEntity( ) method.

Save this in a directory you can access from your Java code (I used the same directory as my contents.xml file), and make the following change to the resolveEntity( ) method:

    public InputSource resolveEntity(String publicID, String systemID)
        throws IOException, SAXException {
         
        // Handle references to online version of copyright.xml   
        if (systemID.equals(
            "http://www.newInstance.com/javaxml2/copyright.xml")) {
            return new InputSource(
                "file:///c:/javaxml2/ch04/xml/copyright.xml");
        }
        
        // In the default case, return null
        return null;    
    }

Figure 4-1. SAXTreeViewer running with local copyrights.xml

In real-world applications, this method 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 class and 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 applications, rather than trying to use one generic implementation for all your applications. Doing this avoids code bloat, and more importantly, speeds up entity resolution. If you have to wait for your reader to run through fifty or a hundred String.equals( ) comparisons, you can really bog down an application. Be sure to put references accessed often at the top of the if/else stack, so they are encountered first and result in quicker entity resolution.

4.2.2. Using a DTDHandler

These two methods do exactly what you would expect. The first reports a notation declaration, including its name, public ID, and system ID. Remember the NOTATION structure in DTDs?

<!NOTATION jpeg SYSTEM "images/jpeg">

The second method provides information about an unparsed entity declaration, which looks as follows:

<!ENTITY stars_logo SYSTEM "http://www.nhl.com/img/team/dal38.gif"
                    NDATA jpeg>

4.2.3. The DefaultHandler Class

And here comes DefaultHandler to the rescue. This class doesn't define any behavior of its own; however, it does implement ContentHandler, ErrorHandler, EntityResolver, and DTDHandler, and provides empty implementations of each method of each interface. So you can have a single class (call it, for example, MyHandlerClass) that extends DefaultHandler. This class only needs to override methods it needs to perform action in. You might implement startElement( ), characters( ), endElement( ), and fatalError( ), for example. In any combination of implemented methods, though, you'll save tons of lines of code for methods you don't need to provide action for, and make your code a lot clearer too. Then, the argument to setErrorHandler( ), setContentHandler( ), and setDTDHandler( ) would be the same instance of this MyHandlerClass. Theoretically, you could pass the instance to setEntityResolver( ) as well, although (for about the fourth time!) I discourage mixing the resolveEntity( ) method in with these other interface methods.