blob: 025015b18604b5cc4297e2fa75e5df6f8559e5d8 [file] [log] [blame]
kpriceef160682006-08-29 18:08:31 +00001<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "">
2<html lang="en-us" xml:lang="en-us">
syeshinbefd53e2005-07-27 18:16:40 +00003<head>
kpriceef160682006-08-29 18:08:31 +00004<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
kpriceb59c9f62008-04-02 21:24:37 +00005<meta name="copyright" content="Copyright (c) 2000, 2008 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 Contributors: IBM Corporation - initial API and implementation" />
6<meta name="DC.rights.owner" content="(C) Copyright 2000, 2008" />
kpriceef160682006-08-29 18:08:31 +00007<meta content="public" name="security" />
8<meta content="index,follow" name="Robots" />
9<meta http-equiv="PICS-Label" content='(PICS-1.1 "" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "" l gen true r (n 0 s 0 v 0 l 0) "" l gen true r (SS~~000 1))' />
10<meta content="task" name="DC.Type" />
11<meta name="DC.Title" content="Adding entries to the XML Catalog" />
kpriceb59c9f62008-04-02 21:24:37 +000012<meta name="abstract" content="An XML Catalog entry contains two parts - a Key (which represents a DTD or XML schema) and a Location (similar to a 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" />
13<meta name="description" content="An XML Catalog entry contains two parts - a Key (which represents a DTD or XML schema) and a Location (similar to a 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" />
14<meta content="XML catalog, adding entries" name="DC.subject" />
15<meta content="XML catalog, adding entries" name="keywords" />
kpriceef160682006-08-29 18:08:31 +000016<meta scheme="URI" name="DC.Relation" content="../topics/cxmlcat.html" />
17<meta scheme="URI" name="DC.Relation" content="../topics/tedtcnst.html" />
18<meta scheme="URI" name="DC.Relation" content="../topics/tedtdoc.html" />
19<meta scheme="URI" name="DC.Relation" content="../topics/tedtgram.html" />
20<meta scheme="URI" name="DC.Relation" content="../topics/cxmlcat.html" />
21<meta scheme="URI" name="DC.Relation" content="../topics/tedtcnst.html" />
22<meta scheme="URI" name="DC.Relation" content="../topics/tedtsch.html" />
23<meta scheme="URI" name="DC.Relation" content="../topics/tedtgram.html" />
24<meta content="XHTML" name="DC.Format" />
25<meta content="txmlcat" name="DC.Identifier" />
26<meta content="en-us" name="DC.Language" />
27<link href="../../org.eclipse.wst.doc.user/common.css" type="text/css" rel="stylesheet" />
syeshind0bdb8e2005-10-27 17:44:14 +000028<title>Adding entries to the XML Catalog</title>
syeshinaaa21932005-09-22 17:13:22 +000029</head>
syeshinbefd53e2005-07-27 18:16:40 +000030<body id="txmlcat"><a name="txmlcat"><!-- --></a>
kpriceef160682006-08-29 18:08:31 +000032
syeshind0bdb8e2005-10-27 17:44:14 +000033<h1 class="topictitle1">Adding entries to the XML Catalog</h1>
kpriceef160682006-08-29 18:08:31 +000034
38<div><p>An XML Catalog entry contains two parts - a Key (which represents
kpriceb59c9f62008-04-02 21:24:37 +000039a DTD or XML schema) and a Location (similar to a URI, which contains information
40about a DTD or XML schema's location). You can place the Key in an XML file.
41When the XML processor encounters it, it will use the XML Catalog entry to
42find the location of the DTD or XML schema associated with the Key</p>
kpriceef160682006-08-29 18:08:31 +000043
syeshind0bdb8e2005-10-27 17:44:14 +000044<div class="section"><p>XML Catalog entries can be used in various situations. For example,
45you are working on an XML file on your main desktop computer and point its <samp class="codeph">schemaLocation</samp> towards
syeshinbefd53e2005-07-27 18:16:40 +000046a schema called <samp class="codeph">c:\MySchema.xsd</samp>. You then save it to your
47laptop computer so you can work on it later. When you open the file on your
kpriceef160682006-08-29 18:08:31 +000048laptop, however, you encounter a problem - the XML editor cannot find the <samp class="codeph">MySchema.xsd</samp> schema
49because it is actually installed on your D drive. You will have to edit the <samp class="codeph">schemaLocation</samp> to
syeshinbefd53e2005-07-27 18:16:40 +000050point to <samp class="codeph">d:\MySchema.xsd</samp>. When you have finished editing
51the XML file and are ready to publish it on the Web, you will need to edit
52the URI again so that it points to a resource that is accessible on the Web.
53By now, the problem is obvious. A URI used within an XML file is not as portable
54as you would like it to be. To avoid making frequent changes to your XML document,
55you can use the XML Catalog.</p>
56<p>An XML Catalog entry is used by an XML
57processor when resolving entity references. You can provide rules to the catalog
kpriceef160682006-08-29 18:08:31 +000058to specify how entities should be resolved. If you consider the preceding
59example, you could specify a rule that redirects an Internet resource reference
60(for example, <samp class="codeph">""</samp>)
syeshinbefd53e2005-07-27 18:16:40 +000061so that it points to a resource on the developer's local machine (for example,
62 <samp class="codeph">"file:///C:/MySchema.xsd"</samp>). Now, instead of frequently editing
kpriceb59c9f62008-04-02 21:24:37 +000063XML documents to update the URIs or locations (especially when there are many
64documents in your project), you only need to update a single rule in your
65XML Catalog.</p>
66<p>The following instructions were written for the Resource
67perspective, but they will also work in many other perspectives.</p>
69add an entry to the XML Catalog, follow these steps:</p>
syeshinbefd53e2005-07-27 18:16:40 +000070</div>
kpriceef160682006-08-29 18:08:31 +000072<ol>
73<li class="stepexpand"><span>Open the XML file that you want to associate with a DTD or XML
76<li class="stepexpand"><span>Click <span class="menucascade"><span class="uicontrol">Window</span> &gt; <span class="uicontrol">Preferences</span>
kpriceb59c9f62008-04-02 21:24:37 +000077</span> and select <span class="menucascade"><span class="uicontrol">XML</span> &gt; <span class="uicontrol">XML
78Catalog</span></span>.</span> The <span class="uicontrol">XML Catalog
79Entries</span> section contains a list of any user-defined and plug-in
80defined catalog entries. Select any entry to see information about it in the <span class="uicontrol">Details</span> section.
kpriceef160682006-08-29 18:08:31 +000081</li>
kpriceb59c9f62008-04-02 21:24:37 +000083<li class="stepexpand"><span>Click <span class="uicontrol">Add</span> to create a new catalog entry.</span>
kpriceef160682006-08-29 18:08:31 +000084</li>
kpriceb59c9f62008-04-02 21:24:37 +000086<li class="stepexpand"><span>In the <span class="uicontrol">Location</span> field, enter or browse for
87the location or URI of the DTD or XML schema file. This uses your computer's
88path style to describe the location of the file.</span></li>
kpriceef160682006-08-29 18:08:31 +000089
kpriceb59c9f62008-04-02 21:24:37 +000090<li class="stepexpand"><span>Select a key type for the catalog entry from the <span class="uicontrol">Key
91Type</span> drop down.</span> The values in this list will change
92depending on the type of file you specified in the <span class="uicontrol">Location</span> field:<ul>
93<li>If you specified a DTD: select <span class="uicontrol">Public ID</span>, <span class="uicontrol">System
94ID</span>, or <span class="uicontrol">URI</span> from the <span class="uicontrol">Key Type</span> field.
95If you select <span class="uicontrol">Public ID,</span> the value you enter in the <span class="uicontrol">Key</span> field
kpriceef160682006-08-29 18:08:31 +000096should be the same as the Public ID in the XML file's DOCTYPE declaration.
97If you select <span class="uicontrol">System ID</span>, the value you enter should
kpriceb59c9f62008-04-02 21:24:37 +000098correspond to the System ID in an XML file's DOCTYPE declaration. If you select <span class="uicontrol">URI</span>,
99the value you enter must be a fully qualified URI.</li>
kpriceef160682006-08-29 18:08:31 +0000100
kpriceb59c9f62008-04-02 21:24:37 +0000101<li>If you specified an XML schema: select either <span class="uicontrol">Namespace Name</span> or
102 <span class="uicontrol">Schema Location</span> from the <span class="uicontrol">Key Type</span> field.
103If the schema defines a target namespace, it will automatically appear in
104the <span class="uicontrol">Key</span> field. Otherwise, you can enter the schema
kpriceef160682006-08-29 18:08:31 +0000105location in the <span class="uicontrol">Key</span> field.</li>
kpriceb59c9f62008-04-02 21:24:37 +0000107</ul>
kpriceef160682006-08-29 18:08:31 +0000110<li class="stepexpand"><span>Select the <span class="uicontrol">Specify alternative Web address</span> check
111box if you want to be able to specify an alternate Web address for the resource.</span>
112 This Web address is used when an XML instance is generated from this
kpriceb59c9f62008-04-02 21:24:37 +0000113catalog entry.<div class="note"><span class="notetitle">Note:</span> This option is only available if you select <span class="uicontrol">Public
kpriceef160682006-08-29 18:08:31 +0000114ID</span> (for a DTD) or <span class="uicontrol">Namespace Name</span> (for
kpriceb59c9f62008-04-02 21:24:37 +0000115a schema) in the <span class="uicontrol">Key type</span> field.</div>
kpriceef160682006-08-29 18:08:31 +0000117
118<li class="stepexpand"><span>If you want to refer to another catalog without importing it into
119the workbench, click <span class="uicontrol">Next Catalog</span>. Type or browse for
120the XML catalog you want to refer to. </span></li>
122<li class="stepexpand"><span>When you are done creating catalog entries, click <span class="uicontrol">OK</span> to
kpriceb59c9f62008-04-02 21:24:37 +0000123close the Add XML Catalog Entry dialog. Click <span class="uicontrol">OK</span> again
124to save your settings.</span></li>
kpriceef160682006-08-29 18:08:31 +0000125
126<li class="stepexpand"><span>Make sure the XML file is in focus and click the <span class="uicontrol">Reload
127dependencies</span> toolbar button. </span></li>
131<div class="section">The XML file is now associated with the latest version of the XML
132schema or DTD.</div>
kpriceb59c9f62008-04-02 21:24:37 +0000134<div class="section"><p>You can also export and import XML Catalog information: </p>
136export, click <span class="uicontrol">File &gt; Export</span> and select <span class="uicontrol">XML
137&gt; XML Catalog</span>. You will be prompted to select a project and provide
138a file name to store your catalog entries in an .xmlcatalog file, which can
139be opened from the Navigator view. Since your catalog entries are stored in
140an .xmlcatalog file, you can check them in and out and share them like any
141other project resource.</p>
142<p>To import, click <span class="uicontrol">File &gt; Import</span> and
143select <span class="uicontrol">XML &gt; XML Catalog</span>. Then specify the file that
144will be used to load the XML Catalog settings. When you import a .xmlcatalog
145file, any entries in it will be loaded into the XML Catalog (and any existing
146entries will be overwritten). </p>
syeshin66078272005-09-20 16:53:38 +0000149</div>
kpriceef160682006-08-29 18:08:31 +0000150
151<div><div class="relconcepts"><strong>Related concepts</strong><br />
152<div><a href="../topics/cxmlcat.html" title="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.">XML file associations with DTDs and XML schemas</a></div>
154<div class="reltasks"><strong>Related tasks</strong><br />
kpriceb59c9f62008-04-02 21:24:37 +0000155<div><a href="../topics/tedtcnst.html" title="In the Design view, when you edit an XML file that has a set of constraints or 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></div>
kpriceef160682006-08-29 18:08:31 +0000156<div><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 DOCTYPE declarations</a></div>
157<div><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. The changes will be reflected in the guided editing mechanisms available in the editor, such as content assist.">Updating XML files with changes made to DTDs and schemas</a></div>
158<div><a href="../topics/tedtsch.html" title="Your namespace information is used to provide various information about the XML file, such as the XML schema and namespace it is associated with. If desired, you can change the schema and namespace your XML file is associated with or add a new association. Modifying any associations can impact what content is allowed in the XML file.">Editing namespace information</a></div>
syeshinbefd53e2005-07-27 18:16:40 +0000162</body>