1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!--ArborText, Inc., 1988-2000, v.4002-->
<html>
<head>
<title>README for Arbortext Catalog Classes</title>
</head>
<body><div><h1>README for Arbortext Catalog Classes</h1><p><b>10 Apr 2000
</b></p><p>These Java classes implement the <a href="http://www.oasis-open.org/html/a401.htm">
OASIS Entity Management Catalog</a> format as well as an <a href="http://www.ccil.org/~cowan/XML/XCatalog.html">
XML Catalog</a> 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.</p><p>
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.</p><p>For more information, see also the <a href="http://www.arbortext.com/Think_Tank/Norm_s_Column/norm_s_column.html"><em>
Standard Deviations from Norm</em></a> column "<a href="http://www.arbortext.com/Think_Tank/Norm_s_Column/issue_three/issue_three.html">
If You Can Name It, You Can Claim It!</a>"</p><div><h2>Manifest</h2><p>The
Catalog distribution contains the following:</p><dl>
<dt><b>com/</b></dt>
<dd>The root directory of the class files.</dd>
<dt><b>docs/</b></dt>
<dd>Documentation</dd>
<dt><b>docs/api/</b></dt>
<dd>API documentation (JavaDoc)</dd>
<dt><b>patches/</b></dt>
<dd>Extensions to other applications, adding Catalog support. For this release,
the only extension demonstrated is an alternative Driver for XT that adds
Catalog support.</dd>
<dt><b>samples/</b></dt>
<dd>Sample applications.</dd>
<dt><b>test/</b></dt>
<dd>Test documents.</dd>
<dt><b>catalog.jar</b></dt>
<dd>The Catalog classes in a single jar file.</dd>
<dt><b>catalog-apps.jar</b></dt>
<dd>The Catalog sample applications a single jar file. In order to use the
sample applications, you must have the <a href="http://xml.apache.org/xerces-j/">
Xerces</a> parser classes on your <em>CLASSPATH</em>. To use the demonstration
version of <a href="http://www.jclark.com/xml/xt.html">XT</a>, you must also
have <a href="http://www.jclark.com/xml/xp/">XP</a>.</dd>
</dl></div><div><h2>Installation</h2><p>To install the class files, simply
place the Jar files on your class path. (On most systems, this is specified
by the <em>CLASSPATH</em> environment variable)</p></div><div><h2>Use</h2><p>
This section provides a very brief overview of the classes. For more complete
information, see the <a href="api/index.html">API Documentation</a>.</p><div><h3>
Using the Catalog class in your own applications</h3><p>To add Catalog support
to an application, create a new <code>CatalogEntityResolver</code> object
and initialize it:</p><pre>import com.arbortext.catalog.*;
...
CatalogEntityResolver cer = new CatalogEntityResolver();
Catalog myCatalog = new Catalog();
myCatalog.loadSystemCatalogs();
cer.setCatalog(myCatalog);
...
yourParser.setEntityResolver(cer)
</pre></div><div><h3>Sample Applications</h3><p>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.</p><div><h4>Running the catalog application</h4><p>
The <em>catalog</em> program parses one or more Catalog files and performs
a single lookup:</p><pre>>java -cp catalog.jar;catalog-apps.jar
catalog -c test/catalog
public "-//Arbortext//TEXT Test Public Identifier//EN"</pre><p>(with
the whole command on a single line, naturally).</p><p>In this example, <em>
catalog</em> loads the OASIS Catalog file <em>test/catalog</em>, looks up
the requested public identifier, and displays the resulting system identifier.
There are a number of options that you can pass to the <em>catalog</em> program:
</p><table summary="Summary of parameters; run catalog with no arguments for a text-only summary"
width="100%" border="1" cellpadding="5"><tbody>
<tr><th align="left" valign="top" height="28">Option</th><th align="left"
valign="top" height="28">Example</th><th align="left" valign="top" height="28">
Description</th></tr>
<tr valign="top"><td>-c <em>catalogfile</em></td><td>-c test/catalog</td>
<td bgcolor="white">Load the specified catalog file.</td></tr>
<tr valign="top"><td>-d <em>debuglevel</em></td><td>-d 1</td><td bgcolor="white">
Set the debug level; the default debug level is 3.</td></tr>
<tr valign="top"><td>-p <em>parserClass</em></td><td>-p org.apache.xerces.parsers.SAXParser
</td><td bgcolor="white">Select the SAX Parser to use to parse XML Catalog
files.</td></tr>
<tr valign="top"><td>-s</td><td>-s</td><td bgcolor="white">Load system catalogs.
</td></tr>
</tbody></table><p>Running <em>catalog</em> with no arguments will display
a summary of this usage information.</p><p>Note: in order to use the <code>
-p</code> option, you will need to have the relevant class files for the parser
class that you select on your <em>CLASSPATH</em>. In the example above, the <a
href="http://xml.apache.org/xerces-j/">Xerces</a> parser from the <a href="http://xml.apache.org/">
Apache XML Project</a> would be required. You can use any SAX compliant parser
with the Catalog files.</p></div><div><h4>Running the eresolve application
</h4><p>The <em>eresolve</em> application demonstrates the use of a <a href="api/com/arbortext/catalog/CatalogEntityResolver.html">
CatalogEntityResolver</a> class as a SAX <code>entityResolver</code> hook.
</p><pre>>java -cp catalog.jar;catalog-apps.jar;xerces.jar
-Dxml.catalog.files=test/catalog
eresolve test/test.xml</pre><p>(with the whole command on a single
line, naturally).</p><p>In this example, the system catalog path is set to <em>
test/catalog</em> and the XML Parser is asked to parse <em>test/test.xml</em>.
In the course of this parsing, it will encounter entities which need to be
resolved. The SAX <code>entityResolver</code> hook will use the catalog to
locate appropriate resources. If you attempt to parse <em>test/test.xml</em>
without a catalog, the parse will fail.</p><p>This example program uses the <a
href="http://xml.apache.org/xerces-j/">Xerces</a> parser from the <a href="http://xml.apache.org/">
Apache XML Project</a> and those classes must be available in order to run <em>
eresolve</em>. 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.</p></div><div><h4>Running a modified version of XT</h4><p>The patches
directory contains a modified version of the command-line driver class for <a
href="http://www.jclark.com/xml/xt.html">XT</a>. In order to use this application,
you must have <a href="http://www.jclark.com/xml/xt.html">XT</a> and <a href="http://www.jclark.com/xml/xp/">
XP</a> on your <em>CLASSPATH</em> in addition to the Arbortext Catalog classes.
This modified version includes support for Catalogs:</p><pre>>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</pre><p>
(with the whole command on a single line, naturally).</p><p>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.</p><p>Note: the XT classes automatically include an
XML Parser, <code>com.arbortext.xsl.sax.Driver</code> 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.</p></div></div></div><div><h2>Change Log</h2><dl>
<dt>1.0.1, 10 Apr 2000</dt>
<dd>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.</dd>
<dt>1.0, 04 Apr 2000</dt>
<dd>Initial release.</dd>
</dl></div><div><h2>Copyright</h2><p>This code is placed in the public domain.
</p></div><div><h2>Warranty</h2><p>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.</p></div></div></body>
</html>
|
