You are viewing a plain text version of this content. The canonical link for it is here.
Posted to woden-dev@ws.apache.org by gt...@apache.org on 2007/02/08 23:20:44 UTC
svn commit: r505060 -
/incubator/woden/Site/src/documentation/content/xdocs/userguide.xml
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: woden-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: woden-dev-help@ws.apache.org