Entity resolvers

Using only the interfaces and classes discussed so far, the application remains unaware of the physical structure of the XML data. An XML document may be a single data file, or composed from a number of files that are managed as external entities. The parser contains an entity manager that hides this complexity from the application.

However, it has already been shown that it can be useful to know more about each entity, if only to be able to provide useful error reports when problems are encountered within them. It would also be useful to be able to intercept an entity reference, and redirect the parser to another resource, or simply to a local copy of the named resource.

Entity resolver interface

It is possible to intercept references to entities using the EntityResolver interface. The application needs to create a class that implements this interface, which defines the following single method:

InputSource resolveEntity( String publicId,
                           String systemId );

Note that this interface is unchanged in SAX 2.0.

Each time the parser encounters an entity reference that resolves to an external entity (but not to a binary entity), it stops and passes the system identifier (and public identifier, if present) to the resolveEntity method. It waits for the method to return, either with a null value, which signifies that the parser should continue as normal, or alternatively with a replacement data file or data stream to process.

This method returns an InputSource object. The following example shows how to return a locally valid system identifier, to a file called 'disc.xml' in the 'xml' directory, whenever an entity is encountered that has a system identifier of 'Disclaimer', or a public identifier of '-//MyCorp//TEXT Disclaimer//EN':

public InputSource resolveEntity( String publicID,
                                  String systemID)
{
  if ( systemID.equals("Disclaimer") ||
    publicID.equals("-//MyCorp//TEXT Disclaimer//EN") )
       return ( new InputSource( "file:///xml/disc.xml"));

  return null; // entity reference not intercepted
}

Catalogues

An application could implement a catalogue feature using this feature (assuming that the parser does not already have such a facility). For example, it could resolve public identifiers into local system identifiers (or URNs into URLs).