README for Arbortext Catalog Classes

10 Apr 2000

These Java classes implement the OASIS Entity Management Catalog format as well as an XML Catalog format for resolving XML public identifiers into accessible files or resources on a user's system or throughout the Web. These definitions can easily be incorporated into most Java-based XML processors, thereby giving the users of these processors all the benefits of public identifier use.

As XML processors incorporate this code, users will be able to utilize public identifiers in XML documents with the confidence that they will be able to move those documents from one system to another and around the Web knowing that they will also be able to refer to the appropriate external file or Web page.

For more information, see also the Standard Deviations from Norm column " If You Can Name It, You Can Claim It!"

Manifest

The Catalog distribution contains the following:

com/
The root directory of the class files.
docs/
Documentation
docs/api/
API documentation (JavaDoc)
patches/
Extensions to other applications, adding Catalog support. For this release, the only extension demonstrated is an alternative Driver for XT that adds Catalog support.
samples/
Sample applications.
test/
Test documents.
catalog.jar
The Catalog classes in a single jar file.
catalog-apps.jar
The Catalog sample applications a single jar file. In order to use the sample applications, you must have the Xerces parser classes on your CLASSPATH. To use the demonstration version of XT, you must also have XP.

Installation

To install the class files, simply place the Jar files on your class path. (On most systems, this is specified by the CLASSPATH environment variable)

Use

This section provides a very brief overview of the classes. For more complete information, see the API Documentation.

Using the Catalog class in your own applications

To add Catalog support to an application, create a new CatalogEntityResolver object and initialize it:

import com.arbortext.catalog.*;

...
	CatalogEntityResolver cer = new CatalogEntityResolver();
	Catalog myCatalog = new Catalog();
	myCatalog.loadSystemCatalogs();
	cer.setCatalog(myCatalog);
...
   yourParser.setEntityResolver(cer)

Sample Applications

The sample applications demonstrate some of the features of Catalogs. Each of the examples that follows assumes that you're current working directory is the directory where you unpacked the catalog distribution.

Running the catalog application

The catalog program parses one or more Catalog files and performs a single lookup:

>java -cp catalog.jar;catalog-apps.jar
       catalog -c test/catalog
       public "-//Arbortext//TEXT Test Public Identifier//EN"

(with the whole command on a single line, naturally).

In this example, catalog loads the OASIS Catalog file test/catalog, looks up the requested public identifier, and displays the resulting system identifier. There are a number of options that you can pass to the catalog program:

OptionExample Description
-c catalogfile-c test/catalog Load the specified catalog file.
-d debuglevel-d 1 Set the debug level; the default debug level is 3.
-p parserClass-p org.apache.xerces.parsers.SAXParser Select the SAX Parser to use to parse XML Catalog files.
-s-sLoad system catalogs.

Running catalog with no arguments will display a summary of this usage information.

Note: in order to use the -p option, you will need to have the relevant class files for the parser class that you select on your CLASSPATH. In the example above, the Xerces parser from the Apache XML Project would be required. You can use any SAX compliant parser with the Catalog files.

Running the eresolve application

The eresolve application demonstrates the use of a CatalogEntityResolver class as a SAX entityResolver hook.

>java -cp catalog.jar;catalog-apps.jar;xerces.jar
       -Dxml.catalog.files=test/catalog
       eresolve test/test.xml

(with the whole command on a single line, naturally).

In this example, the system catalog path is set to test/catalog and the XML Parser is asked to parse test/test.xml. In the course of this parsing, it will encounter entities which need to be resolved. The SAX entityResolver hook will use the catalog to locate appropriate resources. If you attempt to parse test/test.xml without a catalog, the parse will fail.

This example program uses the Xerces parser from the Apache XML Project and those classes must be available in order to run eresolve. You can add the Catalog functionality to any SAX compliant parser, but for the purpose of this example, we've explicitly chosen the Xerces parser.

Running a modified version of XT

The patches directory contains a modified version of the command-line driver class for XT. In order to use this application, you must have XT and XP on your CLASSPATH in addition to the Arbortext Catalog classes. This modified version includes support for Catalogs:

>java -cp catalog.jar;catalog-apps.jar;xp.jar;xt.jar
       -Dxml.catalog.files=test/catalog
       com.arbortext.xsl.sax.Driver test/test.xml test/style.xsl

(with the whole command on a single line, naturally).

Running this example displays the styled (transformed to HTML document) on the screen. Running an unmodified version of XT on this document produces parsing errors as did the previous example.

Note: the XT classes automatically include an XML Parser, com.arbortext.xsl.sax.Driver uses that parser to parse XML Catalogs, if it supports the SAX interface. If it does not support the SAX interface, this modified version of XT has no built-in support for XML Catalogs.

Change Log

1.0.1, 10 Apr 2000
Fixed a bug in the calculation of the list of subordinate catalogs. This bug caused an infinite loop where parsing would alternately process two catalogs indefinitely.
1.0, 04 Apr 2000
Initial release.

Copyright

This code is placed in the public domain.

Warranty

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL ARBORTEXT OR ANY OTHER CONTRIBUTOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.