Getting started with the Resolver API

Section overview

This section reviews how to install the Apache XML Commons Resolver API, which is used throughout the rest of this tutorial. Also introduced are the command-line applications provided with the API, which are useful for exploring how a catalog processor will respond to requests to resolve various combinations of URIs and system and public identifiers.

The Resolver API is provided as part of the Apache XML Commons project, which bundles together a number of standard XML APIs and related utilities shared by a number of different Apache XML projects.

While available as part of the main XML Commons distribution, the Resolver API is also available as a separate bundle for applications that only need to use this facility. The installation of this distribution is discussed next.

Installing the XML Commons Resolver classes

All of the the Apache XML Commons distributions are available from: http://xml.apache.org/dist/commons/.

The Resolver API 1.0 release can be downloaded from: http://apache.us.lucid.dk/xml/commons/.

Installation is simple: Download the above file and unzip the archive into a local directory. This directory will be referred to as $RESOLVER_HOME from this point forward. After you unzip the distribution, the directory contains the following structure:

• build -- build directory into which the compiled classes are placed
• docs -- contains the Javadoc-generated API documentation
• src -- the source code for the Resolver API
• resolver.xml -- an Ant build script for compiling the API from the provided source
• resolver.jar -- a pre-built version of the API

Building the Resolver API directly from source is outside the scope of this tutorial, but is quite straightforward using the provided Ant script. (See Resources for more information about installing and using the Ant build tool.)

Installation of the API is completed by adding resolver.jar to the Java CLASSPATH as follows:

set CLASSPATH=$CLASSPATH:$RESOLVER_HOME/resolver.jar
export CLASSPATH

Back to top

The command-line tools

The Resolver API distribution includes several command-line applications that are useful tools for exploring how a catalog processor processes XML catalogs. The first of these is a simple command-line wrapper around the catalog processor component that allows the user to specify a catalog file and various combinations of identifiers to see how the catalog processor will respond. This application called resolver will be used extensively in the next section (Exploring XML catalogs ).

The full command-line for invoking this application is as follows:

java org.apache.xml.resolver.apps.resolver [options] [keyword]

The examples (available for download from Tools) include both a Unix shell script and a Windows batch file for invoking this application as follows:

$EXAMPLES_HOME/bin/resolver.sh [options] [keyword]

Before using these scripts, edit them to ensure that the value of $RESOLVER_HOME conforms to the local installation of the Resolver API. Adding the $EXAMPLES_HOME/bin directory to the PATH further simplifies the command-line, allowing resolver.sh to be invoked directly.

Back to top

The command-line options

For the full set of command-line options for this class, consult the Resolver API Javadoc for the org.apache.xml.resolver.apps.resolve class. The options useful for this tutorial are summarized here:

• -c -- specifies the catalog file to load
• -p -- specifies a public identifier to be resolved
• -s -- specifies a system identifier to be resolved
• -u -- specifies a URI to be resolved

The command-line ends with a keyword indicating the type of resolution that the catalog processor should perform. Again, a number of alternatives cover different types of XML entities (such as DTD, entity, and notation); however, the only two used in this tutorial are:

• doctype -- simulates resolution of identifiers supplied in a DOCTYPE declaration
• uri -- simulates resolution of a URI, for example as specified in the XSLT document function

Some examples illustrate how these options are used:

resolver.sh -c catalog.xml -s http://www.example.com/dtd/example.dtd doctype

The above instructs the resolver application to load the catalog catalog.xml and attempt to resolve the system identifier http://www.example.com/dtd/example.dtd. Resolving a public identifier works similarly, substituting the -p parameter and public identifier in place of the -s parameter.

Both a public and a system identifier can be specified as follows:

resolver.sh -c catalog.xml \
            -s http://www.example.com/dtd/example.dtd \
            -p "-//Example Inc.//Example DTD//EN" doctype

The above, which should be entered as a single line, requests that the processor try to resolve both identifiers.

Simulating the resolution of a URL involves using the -u option and the uri keyword as follows:

resolver.sh -c catalog.xml -u http://www.remote-site.com/stylesheet.xsl uri

The other useful application is xread, a simple command-line XML parser that incorporates XML catalog support. This application, while useful for testing whether a given document will parse using a catalog, is not covered further in this tutorial. For further information on using it from the command line, see the Resolver API Javadoc for the org.apache.xml.resolver.apps.xread class. It should be obvious how to customize the shell scripts included in the examples to run this application instead.

Back to top

Section recap

This section described the installation of the Apache XML Resolver API, which is available as a standalone distribution from the Apache XML Commons project.

This API provides two useful command-line tools, one of which is used extensively in the next section to explore the XML Catalog specification. This application enables the simulation of catalog resolution for different catalogs and combinations of XML identifiers.

3 of 9 | Previous | Next

Comments

Back to top

Table of contents

• Introduction
• Entity management
• Getting started with the Resolver API
• Exploring XML catalogs
• Adding catalog support to XML applications
• Summary
• Download
• Resources
• About the author

---

3 of 9 | Previous | Next

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

Dig deeper into XML on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.