docs/org.eclipse.wst.xmleditor.doc.user/topics/cxmlcat.dita

<?xml version="1.0" encoding="utf-8"?>
<!--Arbortext, Inc., 1988-2005, v.4002-->
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
 "concept.dtd">
<concept id="cxmlcat" xml:lang="en-us">
<title>XML file associations with DTDs and XML schemas</title>
<titlealts>
<searchtitle>XML file associations with DTDs and XML schemas</searchtitle>
</titlealts>
<shortdesc>When an XML file is associated with a DTD or XML schema, it is
bound by any structural rules contained in the DTD or XML schema. To be considered
a valid XML file, a document must be accompanied by a DTD or an XML schema,
and conform to all of the declarations in the DTD or the XML schema.</shortdesc>
<prolog><metadata>
<keywords><indexterm>XML catalog<indexterm>overview</indexterm></indexterm>
<indexterm>XML files<indexterm>associations</indexterm></indexterm>
</keywords>
</metadata></prolog>
<conbody>
<p>There are two different ways to associate XML files with DTDs or XML schemas.</p>
<ol>
<li>Direct association - The XML file contains either the name of a DTD in
its doctype declaration (for example, &lt;!DOCTYPE root-element SYSTEM " <varname>dtdfile.dtd</varname>"
>, where  <varname>dtdfile.dtd</varname> is the name of the DTD file) or it
contains the path of an XML schema in the schemaLocation attribute of the
XML file root element (for example, &lt;xsi:schemaLocation="http://www.ibm.com
 <varname>schema.xsd</varname>">, where  <varname>schema.xsd</varname> is
the name of the XML schema.</li>
<li>XML Catalog entry - You can register DTD and XML schema files in the XML
Catalog and associate them with a  <varname>Key</varname> that represents
them. You can then refer to a DTD or XML schema file  <varname>Key</varname> from
an XML file instead of referring directly to the DTD or XML schema file. An
XML Catalog entry contains two parts - the Key (which represents the DTD or
XML schema) and a URI (which contains information about the DTD or XML schema
location).</li>
</ol>
<section><title>How an association works</title><b>Associating an XML file
with a DTD </b><p>If an XML file is associated with a DTD, a DOCTYPE tag such
as the following one is included in the XML file:<codeblock>&lt;!DOCTYPE root-name PUBLIC "<varname>InvoiceId</varname>" "<varname>C:\mydtds\Invoice.dtd</varname
>">
</codeblock></p><p><varname>InvoiceId</varname> is the public identifier of
the DTD file. It is used to associate the XML file with a DTD file (in this
case, the DTD file is  <varname>Invoice.dtd</varname>). If the public identifier
InvoiceId corresponds to the  <varname>Key</varname> of the XML Catalog entry
for Invoice.dtd, then the  <varname>URI</varname> of the XML Catalog entry
(which contains information about the location of Invoice.dtd) is used to
locate the DTD. Otherwise, the DOCTYPE's system identifier ( <varname>"C:\mydtds\Invoice.dtd"</varname>),
which refers directly to the file system location of the DTD, is used to locate
the DTD.</p><p> <b>Note</b>: You can also use a system identifier as a Key
in an XML Catalog entry. If you use a system identifier as a Key, a DOCTYPE
tag such as the following one is included in an XML file:</p><codeblock>&lt;!DOCTYPE Root-name SYSTEM "<varname>MyDTD.dtd</varname>"> </codeblock
><p>where  <varname>MyDTD.dtd</varname> is the system identifier that corresponds
to the Key of an XML Catalog entry.</p></section>
<section><b>Associating an XML file with an XML schema</b><p>If an XML file
is associated with an XML schema, one or more schema location attributes are
included in the XML file. The information in the schemaLocation is provided
as a "hint" to the XML processor. The following examples show schemaLocation
attributes.</p><p> <b>Example 1 </b><codeblock>&lt;purchaseOrder xmlns="http://www.ibm.com"
xsi:schemaLocation="http://www.ibm.com C:\myschemas\PurchaseOrder.xsd">
&lt;shipTo country="US">
...</codeblock>    </p><p><b>Example 2 </b><codeblock>&lt;purchaseOrder xmlns="http://www.ibm.com"
xsi:schemaLocation="http://www.ibm.com PO.xsd">
&lt;shipTo country="US">
....</codeblock>  </p><p>In Example 1, the schemaLocation 'hint' ('C:\myschemas\PurchaseOrder.xsd')
refers directly to the file system location or URI of the XML schema. In this
case, the schema file will be located by the XML processor directly.</p><p>In
Example 2, the schemaLocation 'hint' ('PO.xsd') refers to an XML Catalog entry.
PO.xsd corresponds to the  <varname>Key</varname> of the XML Catalog entry
for PurchaseOrder.xsd, and the URI of the XML Catalog entry (which contains
information about the location of PurchaseOrder.xsd) will be used to located
the XML schema.</p><p>In both examples, <codeph>http://www.ibm.com</codeph> in
the <codeph>xsi:schemaLocation</codeph> tag is a URI that identifies the namespace
for the XML schema.</p><p>You can also use a namespace as a Key for an XML
Catalog entry. If you use a namespace as a Key, a schemaLocation tag such
as the following one is included in an XML file:<codeblock>&lt;purchaseOrder xmlns:="www.ibm.com"
xsi:schemaLocation="http://www.ibm.com po/xsd/PurchaseOrder.xsd "></codeblock></p><p>The
schemaLocation attribute points to both the Key and the actual location of
the schema.</p><p><b>DTD or XML schema resides on a remote server</b></p><p>Several
functions in the XML editor, such as validation and content assist, require
the availability of a DTD or an XML schema. The product documentation provides
usage information for cases when the DTD or XML schema resides on your local
machine. However, in many cases, the DTD or XML schema can reside on a remote
server, for example:</p><p><codeph>&lt;!DOCTYPE Catalog PUBLIC "abc/Catalog"
"http://xyz.abc.org/dtds/catalog.dtd"></codeph></p><p>Normally, this case
poses no problem, because the DTD or XML schema can be retrieved from the
remote server. However, if you are behind a firewall, and do not have a SOCKSified
system, the workbench currently does not provide a way for you to specify
a socks server for retrieving a DTD or XML schema. If you are unable to SOCKSify
your system, the workaround for this problem is to retrieve a copy of the
DTD or XML schema (using a Web browser, for example) and save that copy on
your local machine. Then, you can either place a local copy in the same project
as your XML file, or use the XML Catalog to associate a public identifier
with the DTD's (local) location.</p><p><b>Note</b>: If you have an XML file
associated with an XML schema or DTD that is elsewhere in the network, and
you are working on a machine disconnected from the network, you can follow
the steps described previously if you want to use content assist or validate
your XML file.  </p></section>
<section><title>Advantages of XML Catalog entry associations</title><p>If
you create a direct association between an XML file and an XML schema or DTD
file, any time you change the location of the schema or DTD you have to track
down and update all of the referencing XML files with the new location of
the DTD or schema. If, however, you associate an XML file with an XML schema
or DTD Key, then, when you change the location of the schema or DTD, you only
have to update the XML Catalog entry, instead of each individual XML file.</p><p>For
example, you have a DTD called "Building.dtd", which is associated with five
XML files - Office.xml, House.xml, Apartment.xml, Bank.xml, and PostOffice.xml.
You move the DTD file Building.dtd to a new location. If you have a direction
association between Building.dtd and all the XML files, you will have to update
the &lt;DOCTTYPE> declaration in each XML file to reflect the new location
of Building.dtd. If, however, you have an XML Catalog association, and all
the XML files just refer to the Key of Building.dtd, then you only have to
update the URI and all the XML files will point to the new location of Building.dtd.</p></section>
<section><title>Updating an entry in the XML Catalog</title><p>After you have
updated an entry in the XML Catalog, you might need to refresh the XML editor
view so that it uses the new information. To do this, click the <uicontrol>Reload
Dependencies</uicontrol> toolbar button <image href="../images/rldgrmr.gif">
<alt>This graphic is the Reload Dependencies toolbar button</alt></image> and
the view will be updated using the current XML Catalog settings. You only
need to refresh the XML editor view when you have an XML file open that references
the XML Catalog entry that was updated.</p><p>For more information, refer
to the related tasks.</p></section>
</conbody>
</concept>