System Reference

Use a CatalogResolver object to locate a local resource.

Locating a Local Resource

The following example demonstrates how to use a CatalogResolver object to locate a local resource.

Consider the following XML file:

<?xml version="1.0"?> 
<!DOCTYPE catalogtest PUBLIC "-//OPENJDK//XML CATALOG DTD//1.0" 
  "http://openjdk.java.net/xml/catalog/dtd/example.dtd">

<catalogtest>
  Test &example; entry
</catalogtest>

The example.dtd file defines an entity example:

<!ENTITY example "system">

However, the URI to the example.dtd file in the XML file doesn't need to exist. The purpose is to provide a unique identifier for the CatalogResolver object to locate a local resource. To do this, create a catalog entry file called catalog.xml with a system entry to refer to the local resource:

<?xml version="1.0" encoding="UTF-8"?> 
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <system
    systemId="http://openjdk.java.net/xml/catalog/dtd/example.dtd"
    uri="example.dtd"/>
</catalog>

With this catalog entry file and the system entry, all you need to do is get a default CatalogFeatures object and set the URI to the catalog entry file to create a CatalogResolver object:

CatalogResolver cr =
  CatalogManager.catalogResolver(CatalogFeatures.defaults(), catalogUri);

catalogUri must be a valid URI. For example:

URI.create("file:///users/auser/catalog/catalog.xml")

The CatalogResolver object can now be used as a JDK XML resolver. In the following example, it’s used as a SAX EntityResolver:

SAXParserFactory factory = SAXParserFactory.newInstance();
factory.setNamespaceAware(true);
XMLReader reader = factory.newSAXParser().getXMLReader();
reader.setEntityResolver(cr);

Notice that in the example the system identifier is given an absolute URI. That makes it easy for the resolver to find the match with exactly the same systemId in the catalog's system entry.

If the system identifier in the XML is relative, then it may complicate the matching process because the XML processor may have made it absolute with a specified base URI or the source file's URI. In that situation, the systemId of the system entry would need to match the anticipated absolute URI. An easier solution is to use the systemSuffix entry, for example:

<systemSuffix systemIdSuffix="example.dtd" uri="example.dtd"/>

The systemSuffix entry matches any reference that ends with example.dtd in an XML source and resolves it to a local example.dtd file as specified in the uri attribute. You may add more to the systemId to ensure that it’s unique or the correct reference. For example, you may set the systemIdSuffix to xml/catalog/dtd/example.dtd, or rename the id in both the XML source file and the systemSuffix entry to make it a unique match, for example my_example.dtd.

The URI of the system entry can be absolute or relative. If the external resources have a fixed location, then an absolute URI is more likely to guarantee uniqueness. If the external resources are placed relative to your application or the catalog entry file, then a relative URI may be more effective, allowing the deployment of your application without knowing where it’s installed. Such a relative URI then is resolved using the base URI or the catalog file’s URI if the base URI isn’t specified. In the previous example, example.dtd is assumed to have been placed in the same directory as the catalog file.