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!"
The Catalog distribution contains the following:
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)
This section provides a very brief overview of the classes. For more complete information, see the API Documentation.
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)
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.
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:
Option | Example | 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 | -s | Load 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.
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.
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.
This code is placed in the public domain.
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.