Author: gturrell
Date: Thu Feb 8 14:20:44 2007
New Revision: 505060
URL: http://svn.apache.org/viewvc?view=rev&rev=505060
Log:
[WODEN-144] Added URI Resolver documentation to the Woden Userguide.
Modified:
incubator/woden/Site/src/documentation/content/xdocs/userguide.xml
Modified: incubator/woden/Site/src/documentation/content/xdocs/userguide.xml
URL:
http://svn.apache.org/viewvc/incubator/woden/Site/src/documentation/content/xdocs/userguide.xml?view=diff&rev=505060&r1=505059&r2=505060
==============================================================================
--- incubator/woden/Site/src/documentation/content/xdocs/userguide.xml
(original)
+++ incubator/woden/Site/src/documentation/content/xdocs/userguide.xml Thu Feb
8 14:20:44 2007
@@ -578,6 +578,162 @@
<!-- ================================================================ -->
<section>
+ <title>Woden URI Resolver</title>
+ <p>
+ This allows URIs referred to in WSDL 2.0 and XML Schema
documents to be redirected to alternative URIs.
+ Woden is equipped with such a resolver as default, and an API to define
alternative implementations.
+ </p>
+ <p><strong>The Resolver API</strong></p>
+ <p>Users are free to create their own custom URI Resolvers, by
implementing the interface
+ <code>org.apache.woden.resolver.URIResolver</code>.
+ </p>
+ <p>
+ The resolver should be registered with the WSDLReader object before
invoking <em>readWSDL()</em> methods.
+ </p>
+ <p>Example:</p>
+ <source>
+ URIResolver myResolver = new CustomURIResolver();
+ WSDLFactory factory = WSDLFactory.newInstance();
+ WSDLReader reader = factory.newWSDLReader();
+ reader.setURIResolver(myResolver);
+ ...
+ reader.readWSDL(â¦..);
+ </source>
+
+ <p><strong>SimpleURIResolver</strong></p>
+ <p>
+ This is the URI resolver implementation provided with the Woden
distribution, and it is also the default.
+ When a WSDLReader object is requested, a <code>SimpleURIResolver</code>
is automatically instantiated and
+ registered with it. In other words the following happens implicitly:</p>
+ <source>
+ reader.setURIResolver(new SimpleURIResolver());
+ </source>
+ <p>
+ If required, a custom resolver can be registered programmatically in
place of the default, as shown above.
+ </p>
+
+ <p><strong>1 - Catalog file format</strong></p>
+ <p>
+ The catalog file follows the Java Properties file syntax: rows of
entries of the form
+ <code><property name>=<property value></code>, interspersed
with comment lines starting with the â#â character.
+ However, with catalog notation the meaning of the left and right hand
expressions is slightly different:</p>
+ <source>
+ <resolve-from URI>=<resolve-to URI>
+ </source>
+ <p>
+ where <em>resolve-from URI</em> is the subject of the resolution, and
<em>resolve-to URI</em> is the place where the resolver looks
+ for the resource. To be meaningful, the <em>resolve-to URI</em> should
be a valid URL (that is, a reference
+ a physical document).
+ </p>
+ <p>By convention, URI catalog file names have the suffix
<code>.catalog</code>, though this is not mandatory.</p>
+ <p>Note that the first â:â in the line of each entry must be
escaped. See examples below.</p>
+ <p>
+ The schema catalog is read sequentially when a
<code>SimpleURIResolver</code> is instantiated.
+ Where multiple entries exist in the catalog for a given resolve-from
URI, the last such entry is used.
+ </p>
+
+ <p><strong>Absolute URIs</strong></p>
+ <p>Examples:</p>
+ <source>
+ Resource held locally on an NTFS file system:
+ http\://test.com/interface.wsdl=file:///c:/resources/interface.wsdl
+
+ Similarly on a Un*x-based file system:
+ http\://test.com/interface.wsdl=file:///resources/interface.wsdl
+
+ Resource held remotely and accessed over http:
+
http\://test.com/interface.wsdl=http://aplace.org/resources/interface.wsdl
+ </source>
+
+ <p><strong>Relative URIs</strong></p>
+ <p>
+ If relative URIs appear in any resolve-to entries in the catalog, then
a search path is used
+ (on initialisation of the resolver) to convert them to absolute URIs.
Any <em>resolve-to</em> entry
+ that does include a Protocol (e.g. starting with <em>file:</em> or
<em>http:</em>) is regarded as relative.
+ Otherwise it is treated as absolute.
+ </p>
+ <p>
+ By default, the Java classpath is searched left to right for a base URI
to complete the
+ relative URI in the catalog. However, it is more useful to prepend the
classpath with a
+ user-defined list of base locations.
+ The System Property
<code>org.apache.woden.resolver.simpleresolver.baseURIs</code> may be used to
specify such a list.
+ </p>
+ <p>
+ For example, say we wish to resolve to two files stored on the local
file system as <code>/wsdl/resources/interface.wsdl</code>,
+ <code>/xsd/resources/schema.xsd</code> and one file
<code>/wibble/random.wsdl</code> contained in a JAR called
<code>/mydocs.jar</code>.
+ </p>
+ <p>
+ We set the
<code>org.apache.woden.resolver.simpleresolver.baseURIs</code> property to the
value
+ <code>file:///wsdl/;file:///xsd/;file:///mydocs.jar</code>.
+ Note the trailing â/â on the first two semi-colon separated entries
which indicates a base URI.
+ If this is omitted the entry is assumed to be a URL of a JAR file.
+ Now we can use the following in the catalog to reference the files:</p>
+ <source>
+ http\://test.com/importinterface.wsdl=resources/interface.wsdl
+ http\://test.com/myschema.xsd=resources/schema.xsd
+ http\://test.com/random.wsdl=wibble/random.wsdl
+ </source>
+ <p>
+ Note that when the resolver creates its resolution table, for each
relative entry the baseURIs list is
+ searched left-to-right and the first match that references a physical
resource is used.
+ </p>
+ <p>Typically, baseURIs will be set to a single path from which all
relative URIs in the catalog descend.</p>
+
+ <p><strong>URLs from JAR files</strong></p>
+ <p>
+ These are references to resources contained within a jar file, and may
be used as absolute resolve-to
+ URLs in the catalog.
+ </p>
+ <p>Example:</p>
+ <source>
+ http\://test.com/doit.wsdl=jar:file:///wibble/pling.jar!/doit.wsdl
+ </source>
+
+ <p><strong>2 â Configuration Properties</strong></p>
+ <p>
+ When a SimpleURIResolver is instantiated, it examines two system
properties:</p>
+ <ul>
+ <li>org.apache.woden.resolver.simpleresolver.catalog</li>
+ <li>org.apache.woden.resolver.simpleresolver.baseURIs</li>
+ </ul>
+ <p>
+ The first should contain a URL for the location of the userâs catalog
file. If this is unset,
+ no URI resolving will occur, except for that defined in the woden
schema catalog (see below).
+ </p>
+ <p>
+ The second is introduced in the discussion on relative URIs above.
+ </p>
+ <p>
+ An application using the Woden WSDLReader to parse a document might
configure the URI resolver
+ as in the flowing snippet:</p>
+ <source>
+
System.setProperty(âorg.apache.woden.resolver.simpleresolver.catalogâ,
+ âfile:///myplace/myresolves.catalogâ);
+
System.setProperty(âorg.apache.woden.resolver.simpleresolver.baseURIsâ,
+ âfile:///wsdl/;file:///xsd/;file:///mydocs.jarâ);
+
+ WSDLReader reader = factory.newWSDLReader(); // instantiates the
default resolver
+ reader.readWSDL(âfile:///mydoc.wsdlâ); // this is also a candidate
for the resolver
+ </source>
+
+ <p><strong>3 â Automatic schema resolution -
schema.catalog</strong></p>
+ <p>
+ The Woden <em>schema catalog</em> is a predefined catalog which is
loaded automatically when a
+ <code>SimpleURIResolver</code> is instantiated.
+ It is loaded immediately before the user-defined catalog (if any).
+ </p>
+ <p>
+ The Woden schema catalog contains resolutions of the standard XML
Schema schema, and the WSDL 2.0 schema, necessary
+ to allow the parser to operate when in network isolation. Because the
user catalog is loaded second, it is possible
+ to override schema entries by redefining them there.
+ </p>
+ <p>The schema catalog is located in
<code>meta-inf/schema.catalog</code> in the Woden distribution jar.</p>
+
+ </section>
+
+
+ <!-- ================================================================ -->
+ <section>
<title>More topics to be added...</title>
<p>
<em>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
