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.