blob: 16f5140f3d04d7252a4aea4845ef3c794eee3fb7 [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<!-- /*******************************************************************************
* Copyright (c) 2000, 2005 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/ -->
<link rel="stylesheet" type="text/css" href="../../org.eclipse.wst.doc.user/common.css" />
<title>Adding entries to the XML Catalog</title>
</head>
<body id="txmlcat"><a name="txmlcat"><!-- --></a>
<h1 class="topictitle1">Adding entries to the XML Catalog</h1>
<div><div class="skipspace"><p>An XML Catalog entry contains two parts - a Key (which represents
a DTD or XML schema) and a Uniform Resource Identifier (URI) (which contains
information about a DTD or XML schema's location).  You can place the
Key in an XML file. When the XML processor encounters it, it will use the
XML Catalog entry to find the location of the DTD or XML schema associated
with the Key</p>
<div class="section"><p>XML Catalog entries can be used in various situations. For example,
you are working on an XML file on your main desktop computer and point its <samp class="codeph">schemaLocation</samp> towards
a schema called <samp class="codeph">c:\MySchema.xsd</samp>. You then save it to your
laptop computer so you can work on it later. When you open the file on your
laptop, however, you encounter a problem - the XML editor cannot find the <samp class="codeph">MySchema.xsd</samp> schema because
it is actually installed on your D drive. You will have to edit the <samp class="codeph">schemaLocation</samp>to
point to <samp class="codeph">d:\MySchema.xsd</samp>. When you have finished editing
the XML file and are ready to publish it on the Web, you will need to edit
the URI again so that it points to a resource that is accessible on the Web.
By now, the problem is obvious. A URI used within an XML file is not as portable
as you would like it to be. To avoid making frequent changes to your XML document,
you can use the XML Catalog.</p>
<p>An XML Catalog entry is used by an XML
processor when resolving entity references. You can provide rules to the catalog
to specify how entities should be resolved. If you consider the example above,
you could specify a rule that redirects an Internet resource reference (for
example, <samp class="codeph">"http://www.ibm.com/published-schemas/MySchema.xsd"</samp>)
so that it points to a resource on the developer's local machine (for example,
<samp class="codeph">"file:///C:/MySchema.xsd"</samp>). Now, instead of frequently editing
XML documents to update the URIs (especially when there may be many documents
in your project), you only need to update a single rule in your XML Catalog.</p>
<p>The following instructions were written for the
XML perspective, but they will also work in many other perspectives.</p>
<p>To
add an entry to the XML Catalog, follow these steps:</p>
</div>
<ol><li class="skipspace"><span>Open the XML file that you want to associate with a DTD or XML
schema.</span></li>
<li class="skipspace"><span>Click <b> <span class="menucascade"><span class="uicontrol">Window</span> &gt; <span class="uicontrol">Preferences</span> &gt; <span class="uicontrol">Web and XML</span> &gt; <span class="uicontrol">XML Catalog</span></span></b>.</span></li>
<li class="skipspace"><span>The <b> <span class="uicontrol">XML Catalog Entries</span></b> field contains
a list of any user-defined and plug-in defined catalog entries.</span><ol type="a"><li><span>Select any entry to see details about it in the
<b> <span class="uicontrol">Details</span></b> field. </span></li>
<li><span>Click <span class="uicontrol"><b>Add</b></span> to create a new catalog entry.</span></li>
</ol>
</li>
<li class="skipspace"><span>In the <b> <span class="uicontrol">URI</span></b> field, type the location of the DTD or XML schema
or browse for it. </span></li>
<li class="skipspace"><span>If you specified a DTD in the <b> <span class="uicontrol">URI</span></b> field,
you can select either <span class="uicontrol"><b>Public ID</b></span> or <b>
<span class="uicontrol">System
ID</span> </b>from the <b> <span class="uicontrol">Key Type</span></b> field.</span> If
you select<b><span class="uicontrol"> Public ID,</span></b> the value you enter in the
<b> <span class="uicontrol">Key</span></b> field
should be the same as the <b>Public ID i</b>n the XML file's DOCTYPE declaration.
If you select <b> <span class="uicontrol">System ID</span>,</b> the value you enter should
correspond to the System ID in an XML file's DOCTYPE declaration.</li>
<li class="skipspace"><span>If you specified an XML schema in the <b> <span class="uicontrol">URI</span></b> field,
you can select either <b> <span class="uicontrol">Namespace Name</span> </b>or
<b> <span class="uicontrol">Schema
Location</span> </b>from the <b> <span class="uicontrol">Key Type</span></b> field.</span> If the schema defines a target namespace, it will automatically appear
in the<span class="uicontrol"> <b>Key</b></span> field. Otherwise, you can enter the schema
location in the <b> <span class="uicontrol">Key</span></b> field.</li>
<li class="skipspace"><span>Select the <b> <span class="uicontrol">Specify alternative Web address</span>
</b>check
box if you want to be able to specify an alternate Web address for the resource.</span>
This Web address is used when an XML instance is generated from this catalog
entry. <b>Note</b>: This option is only available if you select <b> <span class="uicontrol">Public
ID</span> </b>(for a DTD) or <b> <span class="uicontrol">Namespace Name</span>
</b>(for
a schema) in the <b> <span class="uicontrol">Key type</span> </b>field.</li>
<li class="skipspace">If you want to refer to another catalog without
importing it into the workbench, click <b>Next Catalog. </b>Type or browse
for the XML catalog you want to refer to. </li>
<li class="skipspace"><span>When you are done creating catalog entries, click <span class="uicontrol">
<b>OK</b></span> to close the Add XML Catalog Entry dialog. </span></li>
<li class="skipspace"><span>Click <b> <span class="uicontrol">Advanced</span></b> if you want to import or
export any XML Catalog settings.</span></li>
<li class="skipspace"><span>Click <b> <span class="uicontrol">Export</span></b> if you want to persist the
XML Catalog information. Only your user specified entries will be exported.</span><ol type="a"><li class="skipspace"><span>You will be prompted to select a project and provide a file
name to store your catalog entries in an .xmlcatalog file, which can be opened
from the Navigator view.</span> Since your catalog entries are stored in
an .xmlcatalog file, you can check them in and out and share them like any
other project resource.</li>
<li class="skipspace"><span> Click<span class="uicontrol"> <b>OK</b></span>.</span></li>
</ol>
</li>
<li class="skipspace"><span>Click <b> <span class="uicontrol">Import</span></b> if you want to import an .xmlcatalog
file. You will be prompted to select the file you want to import.</span><ol type="a"><li><span>When you import a .xmlcatalog file, any entries in it will be
loaded into the XML Catalog (and any existing entries will be overwritten). </span></li>
<li><span>Click <b> <span class="uicontrol">OK</span></b>.</span></li>
</ol>
</li>
<li class="skipspace"><span>Click <b> <span class="uicontrol">OK</span></b> to close the Advanced XML Catalog
Preferences dialog.</span></li>
<li class="skipspace"><span>Make sure the XML file is in focus and click the<span class="uicontrol">
<b>Reload</b>
dependencies</span> toolbar button. </span></li>
</ol>
<div class="skipspace">The XML file is now associated with the latest version of the XML
schema or DTD.</div>
</div>
<div>
<p><b class="relconceptshd">Related concepts</b><br />
<a href="../topics/cxmlcat.html" title="There are two different ways to associate XML files with DTDs or XML schemas.">XML file associations with DTDs and XML schemas</a><br />
</p>
<p><b class="reltaskshd">Related tasks</b><br />
<a href="../topics/tedtcnst.html" title="In the Design view, when you edit an XML file that has a set of constraints (that is, a set of rules) defined by a DTD or an XML schema, you can turn the constraints on and off to provide flexibility in the way you edit, but still maintain the validity of the document periodically.">Editing with DTD or XML schema constraints</a><br />
<a href="../topics/tedtdoc.html" title="The DOCTYPE declaration in an XML file is used at the beginning of it to associate it with a DTD file. You can edit your DOCTYPE declaration to change the DTD file your XML file is associated with.">Editing your DOCTYPE declaration</a><br />
<a href="../topics/tedtgram.html" title="If you make changes to a DTD file or XML schema associated with an XML file (that is currently open), click XML &gt; Reload Dependencies to update the XML file with these changes.">Updating XML files with changes made to DTDs and schemas</a><br />
<a href="../topics/tedtsch.html" title="Your namespace information is used to provide various information about the XML file, such as the XML schema it is associated with.?">Editing your namespace information</a><br />
</p>
</div>
</body>
</html>