Difference between revisions of "Using the XML Catalog"

From Eclipsepedia

Jump to: navigation, search
Line 30: Line 30:
 
TODO... describe how to working DTD's that reference DTDs work the same way
 
TODO... describe how to working DTD's that reference DTDs work the same way
  
<h3>Working With Schemas</h3>
+
<h3>Working With XML Schemas</h3>
TODO..
+
 
by Namespace Name
+
XML instance document can be associated with XML Schemas in two ways. The first way involves explicit location attributes specified directly in the XML document that specify a URI location to XML Schema document.  The second way involves a more implicit association between an XML namespace and a XML Schema.  
by Schema Location
+
 
 +
 
 +
Often XML documents are designed as shown below (in partial form) where explict schema locations are explicitly specified using the 'xsi:schemaLocation' or the 'xsi:noNamespaceSchemaLocation' attributes. In these cases you can use the XML Catalog to register a local XML Sschema file using the Schema Location as the key.
 +
 
 +
 +
  <xyz:foo xmln:foo="http://www.example.org/foo/" xsi:schemaLocation="http://www.example.org/foo/ http://www.example.org/foo/schemas/foo.xsd" ...
 +
 
 +
  <foo xsi:noNamespaceSchemaLocation="http://www.example.org/foo/schemas/foo.xsd" ...
 +
 
 +
 
 +
As you can see from the code snippet above explict schema locations involve some ugly syntax and become hard to read when multipe namespaces are used in the same XML document.  The Eclipse WTP XML Catalog allows user to associate XML Schemas with a namespace. So if you're working with XML documents that use namespaces but don't specify explicit schema locations (as shown below) then you can use the XML Catalog to register an XML Sschema file using the Namesace Name as the key.
 +
 
 +
  <xyz:foo xmln:foo="http://www.example.org/foo/">
 +
 
 +
Note that if your XML document utlizes a DOCTYPE declaration that specifies a SYSTEM ID (as shown below) that specifies a relative URI location (as opposed to a fully qualified URI) then a DTD can <b>NOT</b> be registered using "Invoice.dtd" as the System Id key.  TODO.. reference section below that describes why this is the case and how XML Catalog v1.1 provides a way to partially solve this.
 +
 
 +
  <!DOCTYPE Invoice SYSTEM "Invoice.dtd">
 +
 
 +
TODO... describe how to working XSD's that reference XSDs work the same way
  
 
<h3>FAQ</h3>
 
<h3>FAQ</h3>

Revision as of 17:07, 23 June 2006


 Note that this document is a work in progress.  Various portions are missing and incomplete.

The eclipes WTP project provides support for using an XML Catalog based on the OASIS XML Catalog specification. An XML Catalog provides some limited control over how references to other resources handled. So for example if a user has one or more XML documents that reference a DTD or XML Schema via a web address (e.g. http://www.example.org/foo.xsd) they can use the XML Catalog to map this address to their own local copy of this resource. This way 'catalog aware' tools won't need to go off to the internet to fetch the resource. There's several other ways an XML Catalog can be used as defined by the OASIS XML Catalog specification. If you're an eclipse plugin developer there's also some convenient extension points you can utilize to contribute to the XML Catalog settings.

Editing the XML Catalog Settings

TODO...

The XML Catalog can be accessed through the preferences as follows...
1. Select “Window -> Preferences” to launch the Preferences dialog.
2. Expand the “Web and XML” heading and select “XML Catalog”.

Working With DTDs

If you're working with XML documents that contain 'DOCTYPE' declarations to reference DTD resources you can control how the referenced DTD documents are located. If an XML document utlizes a DOCTYPE declaration that specifies a PUBLIC ID (as shown below) you can use the XML Catalog to register a local DTD file using the PUBLIC ID as the key. If you examine the XML Catalog setting in WTP you'll notice that there's several DTD related entries that specify a PUBLIC ID key.

 <!DOCTYPE Invoice PUBLIC "-//EXAMPLE//DTD INVOICE//EN" "http://www.example.org/Invoice.dtd">
 

If an XML document utlizes a DOCTYPE declaration that specifies a SYSTEM ID (as shown below) you can use the XML Catalog to register a local DTD file using the SYSTEM ID as the key.

 <!DOCTYPE Invoice SYSTEM "http://www.example.org/Invoice.dtd">


Note that if your XML document utlizes a DOCTYPE declaration that specifies a SYSTEM ID (as shown below) that specifies a relative URI location (as opposed to a fully qualified URI) then a DTD can NOT be registered using "Invoice.dtd" as the System Id key. TODO.. reference section below that describes why this is the case and how XML Catalog v1.1 provides a way to partially solve this.

 <!DOCTYPE Invoice SYSTEM "Invoice.dtd">

TODO... describe how to working DTD's that reference DTDs work the same way

Working With XML Schemas

XML instance document can be associated with XML Schemas in two ways. The first way involves explicit location attributes specified directly in the XML document that specify a URI location to XML Schema document. The second way involves a more implicit association between an XML namespace and a XML Schema.


Often XML documents are designed as shown below (in partial form) where explict schema locations are explicitly specified using the 'xsi:schemaLocation' or the 'xsi:noNamespaceSchemaLocation' attributes. In these cases you can use the XML Catalog to register a local XML Sschema file using the Schema Location as the key.


 <xyz:foo xmln:foo="http://www.example.org/foo/" xsi:schemaLocation="http://www.example.org/foo/ http://www.example.org/foo/schemas/foo.xsd" ...
 <foo xsi:noNamespaceSchemaLocation="http://www.example.org/foo/schemas/foo.xsd" ...
 

As you can see from the code snippet above explict schema locations involve some ugly syntax and become hard to read when multipe namespaces are used in the same XML document. The Eclipse WTP XML Catalog allows user to associate XML Schemas with a namespace. So if you're working with XML documents that use namespaces but don't specify explicit schema locations (as shown below) then you can use the XML Catalog to register an XML Sschema file using the Namesace Name as the key.

 <xyz:foo xmln:foo="http://www.example.org/foo/">

Note that if your XML document utlizes a DOCTYPE declaration that specifies a SYSTEM ID (as shown below) that specifies a relative URI location (as opposed to a fully qualified URI) then a DTD can NOT be registered using "Invoice.dtd" as the System Id key. TODO.. reference section below that describes why this is the case and how XML Catalog v1.1 provides a way to partially solve this.

 <!DOCTYPE Invoice SYSTEM "Invoice.dtd">

TODO... describe how to working XSD's that reference XSDs work the same way

FAQ

TODO...

  1. I've registered a DTD with a 'System ID' key of 'foo.dtd' and it doesn't work. Why not? Locations in an XML instance get expanded _before_ the XML Catalog is referenced. So the XML Catalog should contain only fully qualified URIs (e.g. http://www.example.org/foo.dtd).
  2. I've registered an XML Schema with a 'Schema Location' key of 'foo.xsd' and it doesn't work. Why not? Locations in an XML instance get expanded _before_ the XML Catalog is referenced. So the XML Catalog should contain only fully qualified URIs(e.g. http://www.example.org/foo.xsd).
  3. I've registered my DTD or XML Schema but eclipse is still going off to the internet to fetch a resource. Why? The registested DTD and XML Schema may have references to more DTDs and XML Schemas.
  4. I've registered an XML Schema by namespace but XML files are still using the 'xsi:schemaLocation' value. Why?
    An explicitly specified schema location value takes precedence over XML Catalog entries that are keyed by namespace.
  5. Can I register multiple XML Schemas for the same namespace?
    No you can't. There should be only one XML Schema registered for a given namespace.

Some links to other XML Catalog related resources

OASIS XML Catalog specification
OASIS XML Catalog V1.1 specification
XML Catalog Tutorial