ws-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From veit...@apache.org
Subject svn commit: r1689248 [7/8] - in /webservices/website/woden-staging: ./ css/ dev/ dev/1.0/ fonts/ images/ images/logos/ images/profiles/ img/ js/ skin/
Date Sun, 05 Jul 2015 12:35:56 GMT
Modified: webservices/website/woden-staging/userguide.html
URL: http://svn.apache.org/viewvc/webservices/website/woden-staging/userguide.html?rev=1689248&r1=1689247&r2=1689248&view=diff
==============================================================================
--- webservices/website/woden-staging/userguide.html (original)
+++ webservices/website/woden-staging/userguide.html Sun Jul  5 12:35:55 2015
@@ -1,1046 +1,1175 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
-<meta content="Apache Forrest" name="Generator">
-<meta name="Forrest-version" content="0.8">
-<meta name="Forrest-skin-name" content="pelt">
-<title>Woden User Guide</title>
-<link type="text/css" href="skin/basic.css" rel="stylesheet">
-<link media="screen" type="text/css" href="skin/screen.css" rel="stylesheet">
-<link media="print" type="text/css" href="skin/print.css" rel="stylesheet">
-<link type="text/css" href="skin/profile.css" rel="stylesheet">
-<script src="skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="skin/fontsize.js" language="javascript" type="text/javascript"></script>
-<link rel="shortcut icon" href="">
-</head>
-<body onload="init()">
-<script type="text/javascript">ndeSetTextSize();</script>
-<div id="top">
-<!--+
-    |breadtrail
-    +-->
-<div class="breadtrail">
-<a href="http://www.apache.org/">apache</a> &gt; <a href="http://ws.apache.org/">ws.apache</a><script src="skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
-</div>
-<!--+
-    |header
-    +-->
-<div class="header">
-<!--+
-    |start group logo
-    +-->
-<div class="grouplogo">
-<a href="http://ws.apache.org/"><img class="logoImage" alt="Web Services" src="images/ws-logo.gif" title="Web Services @ Apache"></a>
-</div>
-<!--+
-    |end group logo
-    +-->
-<!--+
-    |start Project Logo
-    +-->
-<div class="projectlogo">
-<a href="http://incubator.apache.org/woden/"><img class="logoImage" alt="Woden" src="images/wodentitle.png" title="Woden is a WSDL 2.0 validating parser."></a>
-</div>
-<!--+
-    |end Project Logo
-    +-->
-<!--+
-    |start Search
-    +-->
-<div class="searchbox">
-<form action="http://www.google.com/search" method="get" class="roundtopsmall">
-<input value="ws.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">&nbsp; 
-                    <input name="Search" value="Search" type="submit">
-</form>
-</div>
-<!--+
-    |end search
-    +-->
-<!--+
-    |start Tabs
-    +-->
-<ul id="tabs">
-<li class="current">
-<a class="selected" href="index.html">Woden</a>
-</li>
-<li>
-<a class="unselected" href="dev/index.html">Development</a>
-</li>
-</ul>
-<!--+
-    |end Tabs
-    +-->
-</div>
-</div>
-<div id="main">
-<div id="publishedStrip">
-<!--+
-    |start Subtabs
-    +-->
-<div id="level2tabs"></div>
-<!--+
-    |end Endtabs
-    +-->
-<script type="text/javascript"><!--
-document.write("Last Published: " + document.lastModified);
-//  --></script>
-</div>
-<!--+
-    |breadtrail
-    +-->
-<div class="breadtrail">
-
-             &nbsp;
-           </div>
-<!--+
-    |start Menu, mainarea
-    +-->
-<!--+
-    |start Menu
-    +-->
-<div id="menu">
-<div onclick="SwitchMenu('menu_1.1', 'skin/')" id="menu_1.1Title" class="menutitle">Woden</div>
-<div id="menu_1.1" class="menuitemgroup">
-<div class="menuitem">
-<a href="index.html" title="Welcome to Woden">Overview</a>
-</div>
-<div class="menuitem">
-<a href="proposal.html" title="Woden Project Proposal">Proposal</a>
-</div>
-<div class="menuitem">
-<a href="mailinglists.html" title="Woden Mailing Lists">Mailing Lists</a>
-</div>
-<div class="menuitem">
-<a href="issue_tracking.html" title="Woden - Issue Tracking">Issue Tracking</a>
-</div>
-<div class="menuitem">
-<a href="version_control.html" title="Woden - Version Control">Version Control</a>
-</div>
-<div class="menuitem">
-<a href="projectteam.html" title="Woden - Project Team">Project Team</a>
-</div>
-<div class="menuitem">
-<a href="projectsusingwoden.html" title="Woden - Projects Using Woden">Projects Using Woden</a>
-</div>
-</div>
-<div onclick="SwitchMenu('menu_1.2', 'skin/')" id="menu_1.2Title" class="menutitle">Downloads</div>
-<div id="menu_1.2" class="menuitemgroup">
-<div class="menuitem">
-<a href="dev/1.0/builds.html" title="Woden - Builds">Builds</a>
-</div>
-</div>
-<div onclick="SwitchMenu('menu_selected_1.3', 'skin/')" id="menu_selected_1.3Title" class="menutitle" style="background-image: url('skin/images/chapter_open.gif');">Documentation</div>
-<div id="menu_selected_1.3" class="selectedmenuitemgroup" style="display: block;">
-<div class="menupage">
-<div class="menupagetitle">User Guide</div>
-</div>
-</div>
-<div id="credit"></div>
-<div id="roundbottom">
-<img style="display: none" class="corner" height="15" width="15" alt="" src="skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
-<!--+
-  |alternative credits
-  +-->
-<div id="credit2"></div>
-</div>
-<!--+
-    |end Menu
-    +-->
-<!--+
-    |start content
-    +-->
-<div id="content">
-<div title="Portable Document Format" class="pdflink">
-<a class="dida" href="userguide.pdf"><img alt="PDF -icon" src="skin/images/pdfdoc.gif" class="skin"><br>
-        PDF</a>
-</div>
-<h1>Woden User Guide</h1>
-<div id="minitoc-area">
-<ul class="minitoc">
-<li>
-<a href="#intro">Introduction</a>
-</li>
-<li>
-<a href="#overview">Woden Overview</a>
-</li>
-<li>
-<a href="#Download+and+Setup">Download and Setup</a>
-</li>
-<li>
-<a href="#Getting+Started">Getting Started</a>
-</li>
-<li>
-<a href="#The+Woden+API">The Woden API</a>
-</li>
-<li>
-<a href="#Woden+URI+Resolver">Woden URI Resolver</a>
-</li>
-<li>
-<a href="#More+topics+to+be+added...">More topics to be added...</a>
-</li>
-</ul>
-</div>
-  
-    <!-- ================================================================ -->
-    
-<a name="N1000E"></a><a name="intro"></a>
-<h2 class="boxed">Introduction</h2>
-<div class="section">
-<p>
-       The purpose of the Woden User Guide is to explain how to use the external interfaces 
-       of Woden. These external interfaces currently consist of the Woden API, but as development
-       progresses they may also include other configuration techniques, command
-       line tools and script-based utilities such as ANT tasks.
-       Woden users are typically developers of other tools and technologies that use Woden 
-       for parsing or manipulating WSDL documents. 
-       </p>
-<p>
-       The Woden User Guide will not discuss the 'internals' of the Woden implementation and
-       it will only touch on the Woden design where it is relevant to this discussion of how 
-       to use Woden. A Woden Developer Guide (not yet written) will discuss the design and
-       implementation.
-       </p>
-<p>
-       The User Guide reflects the current state of Woden's development and will be updated as 
-       new function is added to Woden. See the "Woden Overview" section below for up-to-date
-       details of what function currently exists and what doesn't.
-       </p>
-<p>
-       This Guide should be read in conjunction with the Woden API Javadocs included with the
-       milestone distribution (see the "Download and Setup" section below).
-       Please post any questions or comments to the Woden development mailing list, 
-       <a href="mailto:woden-dev.at.ws.apache.org">woden-dev@ws.apache.org</a>.
-       </p>
-</div>
-    
-    <!-- ================================================================ -->
-    
-<a name="N10027"></a><a name="overview"></a>
-<h2 class="boxed">Woden Overview</h2>
-<div class="section">
-<p>
-       The initial goal of the Woden project is to develop a WSDL 2.0 processor that implements
-       the W3C WSDL 2.0 specification in response to the Working Group's call for implementations.
-       This includes defining an API for Woden separate to its implementation, so that other projects 
-       can modify or replace the Woden implementation while maintaining consistent external interfaces.
-       Further goals include support for high performance XML parsing and support for WSDL 1.1.
-       </p>
-<p>
-       The objectives to achieve these goals are:
-       </p>
-<ul>
-       
-<li>
-       Develop a WSDL 2.0 processor (DOM-based initially) for serializing and deserializing WSDL 2.0 documents.
-       </li>
-       
-<li>
-       Define a WSDL object model that conforms to the W3C WSDL 2.0 spec, including support for 
-       WSDL and type system extensibility.
-       </li>
-       
-<li>
-       Enable WSDL to be created or modified programmatically via this object model.
-       </li>
-       
-<li>
-       Develop Woden as a configurable and extendable framework to support implementation-specific 
-       customization, such as customization of object factories, validation and error handling.
-       </li>
-       
-<li>
-       Develop a framework extension mechanism that allows alternative XML parsers to be used to support different 
-       usage scenarios and performance requirements, then develop a WSDL parser implementation based on an 
-       XML streaming 'pull' parser such as StAX (JSR173).
-       </li>
-       
-<li>
-       Support deserializing WSDL 1.1 documents and optionally converting them into the WSDL 2.0 object model. 
-       </li>
-       
-<li>
-       Support deserializing WSDL 1.1 documents and optionally representing them with the JWSDL object model
-       (i.e. the WSDL 1.1 object model defined by JSR110 "Java APIs for WSDL" and currently implemented by WSDL4J).
-       </li>
-       
-<li>
-       Develop a comprehensive Junit-based test suite that integrates the WSDL test cases 
-       from the W3C WSDL 2.0 test suite and includes Woden-specific tests that cover its API and
-       the features of the Woden framework.
-       </li>
-       
-</ul>
-<p>
-<br>
-       The functionality that currently exists in Woden and is described in this User Guide includes:
-       </p>
-<ul>
-       
-<li>
-       A factory mechanism used to obtain a WSDL reader (or parser) object.
-       </li>
-       
-<li>
-       A DOM implementation of the reader, based on Apache Xerces.
-       </li>
-       
-<li>
-       Configuring WSDL reader features and properties - for example, switching the validation feature on or off.
-       </li>
-       
-<li>
-       Using the reader to parse (deserialize) a WSDL document at a specified URL into the Woden WSDL 2.0 object model.
-       </li>
-       
-<li>
-       Two forms of the WSDL 2.0 object model; one representing the WSDL 2.0 abstract Component model and one 
-       that maps to the XML elements and attributes in the WSDL namespace.
-       </li>
-       
-<li>
-       Parsing of most of the elements and attributes in the WSDL 2.0 namespace 
-       (the 'extends' attribute of Interface is the only outstanding item).
-       </li>
-       
-<li>
-       Partial WSDL validation using the assertions defined in the WSDL 2.0 spec. 
-       Validation currently exists for Types, Interface and Binding.
-       </li>
-       
-<li>
-       Manipulating the WSDL via methods of the WSDL 2.0 object model. 
-       </li>
-       
-<li>
-       Support for extensibility elements and attributes (i.e. for XML elements and 
-       attributes that extend elements in the WSDL 2.0 namespace).
-       </li>
-       
-<li>
-       Use of this extensibility mechanism for the SOAP binding extensions defined in the WSDL 2.0 spec.
-       </li>
-       
-<li>
-       A customizable error handling mechanism for reporting warnings, errors or fatal errors
-       that result from WSDL validation or Woden configuration problems.
-       </li>
-       
-</ul>
-<p>
-<br>
-       Planned functionality that does not yet exist in Woden and is NOT described in this User Guide includes:
-       </p>
-<ul>
-       
-<li>
-       Parsing  of HTTP binding extensions, as defined in the WSDL 2.0 spec.
-       </li>
-       
-<li>
-       WSDL validation of import and include, SOAP and HTTP binding extensions, and Service.
-       </li>
-       
-<li>
-       Resolving URLs with an entity or catalog resolver
-       </li>
-       
-<li>
-       A mechanism for extending Woden to support other XML parsers.
-       </li>
-       
-<li>
-       A StAX implementation of this parser extension mechanism.
-       </li>
-       
-<li>
-       A mechanism for extending Woden to support types systems other than W3C XML Schema
-       (e.g. RelaxNG, DTD). 
-       </li>
-       
-<li>
-       Writing (serializing) the WSDL object model out to a WSDL document.
-       </li>
-       
-<li>
-       Parsing WSDL 1.1 documents and converting them into the WSDL 2.0 object model. 
-       </li>
-       
-<li>
-       Parsing WSDL 1.1 documents and representing them using the JWSDL object model 
-       (i.e. a WSDL 1.1 object model)
-       </li>
-       
-</ul>
-</div>
-    
-    <!-- ================================================================ -->
-    
-<a name="N1009B"></a><a name="Download+and+Setup"></a>
-<h2 class="boxed">Download and Setup</h2>
-<div class="section">
-<p>Obtain the Apache Woden WSDL processor in one of 2 ways:</p>
-<ul>
-       
-<li>extract the source code from the Woden Subversion (SVN) <a href="version_control.html">repository</a> and compile it, or</li>
-       
-<li>obtain the Woden binary distribution from the latest <a href="dev/1.0/builds.html">milestone build</a>.</li>
-       
-</ul>
-<p>
-       Woden's DOM-based XML parsing depends on Apache Xerces 2.7.1.
-       Its XML Schema support it depends on the schema parser and object model implemented by 
-       the Apache Web Services Commons (ws-commons) XmlSchema project.
-       </p>
-<p>
-       The milestone build includes all of the required libraries and these must be on the classpath:
-       </p>
-<ul>
-       
-<li>woden.jar contains the Woden binary code</li>
-       
-<li>xercesImpl.jar and xml-apis.jar contain Apache Xerces 2.7.1</li>
-       
-<li>XmlSchema-SNAPSHOT.jar contains the Apache ws-commons XmlSchema</li>
-       
-</ul>
-<p>
-       If using the Woden source code, rather than the milestone distribution, then the Apache Xerces 2.7.1 
-       distribution can be downloaded from the Apache Xerces project <a href="http://xerces.apache.org/xerces2-j/download.cgi">here</a>.
-       The source code for Apache Web Services ws-commons XmlSchema can be extracted from its
-       Subversion (SVN) <a href="http://svn.apache.org/repos/asf/webservices/commons/modules/XmlSchema/">repository</a>
-       using the logon id "anoncvs".
-       </p>
-<p>
-       Woden requires Java 1.4 or higher.
-       </p>
-</div>
-    
-    <!-- ================================================================ -->
-    
-<a name="N100D8"></a><a name="Getting+Started"></a>
-<h2 class="boxed">Getting Started</h2>
-<div class="section">
-<p>
-       This section contains a few code examples to demonstrate the Woden programming model. See "The Woden API"
-       section below and the Javadocs included with the milestone distribution for more details.
-       </p>
-<p>
-       The following code example shows how to obtain a <span class="codefrag">WSDLFactory</span> object which is then used to obtain
-       a <span class="codefrag">WSDLReader</span> object (the WSDL parser). 
-       WSDL validation is then enabled on the reader, before the <em>readWSDL</em> method reads a WSDL document
-       from the specified URL and returns the WSDL as a <span class="codefrag">Description</span> object. 
-       The <span class="codefrag">Description</span> represents the Description component from the WSDL 2.0
-       Component model. The API declared by <span class="codefrag">Description</span> and its contained objects will be
-       referred to as the <strong>Component</strong> API. 
-       The <em>toElement</em> method on <span class="codefrag">Description</span> returns the WSDL as a 
-       <span class="codefrag">DescriptionElement</span> object, which represents the WSDL &lt;description&gt; element and along with
-       its contained objects, it declares an API that maps to the XML elements and attributes in the 
-       WSDL 2.0 namespace. This will be referred to as the <strong>Element</strong> API.
-       </p>
-<pre class="code">
-       WSDLFactory factory = WSDLFactory.newInstance();
-       WSDLReader reader = factory.newWSDLReader();
-       reader.setFeature(WSDLReader.FEATURE_VALIDATION, true);
-       Description descComp = reader.readWSDL(wsdlurl);        &lt;-- the Description component
-       DescriptionElement descElem = descElem.toComponent();   &lt;-- the &lt;description&gt; element</pre>
-<p>
-       The parameter <span class="codefrag">wsdlurl</span> is the String representation of a URL, e.g.:
-       </p>
-<pre class="code">
-       wsdlurl="http://ws.org.apache/woden/services/Booking.wsdl" 
-       wsdlurl="C:/woden/services/Booking.wsdl"</pre>
-<p>
-       To obtain the top-level WSDL elements from the <span class="codefrag">DescriptionElement</span>:
-       </p>
-<pre class="code">
-       InterfaceElement[] interfaces = descElem.getInterfaceElements();
-       BindingElement[] bindings = descElem.getBindingElements();
-       ServiceElement[] services = descElem.getServiceElements();</pre>
-<p>
-       This example shows how to get the global schema element declaration (represented by the
-       <span class="codefrag">XmlSchemaElement</span> class from Apache ws-commons XmlSchema) which is referred to by 
-       QName in the 'element' attribute of the interface &lt;fault&gt; element:
-       </p>
-<pre class="code">
-       InterfaceElement interfaceElem = interfaces[0];
-       InterfaceFaultElement[] faults = interfaceElem.getInterfaceFaultElements();
-       XmlSchemaElement xsElem = faults[0].getXmlSchemaElement();</pre>
-<p>
-       Where the WSDL is composed of multiple WSDL documents via WSDL &lt;import&gt; and 
-       &lt;include&gt;, you can navigate the WSDL modules using the methods
-       <em>getImportElements</em> and <em>getIncludeElements</em> of <span class="codefrag">DescriptionElement</span>:
-       </p>
-<pre class="code">
-       ImportElement[] imports = descElem.getImportElements();
-       DescriptionElement importedDescElem = imports[0].getDescriptionElement();</pre>
-<p>
-       The <span class="codefrag">Description</span> component also has methods to retrieve the top-level WSDL components, 
-       but unlike those in <span class="codefrag">DescriptionElement</span>, the behaviour here is to 'flatten' the WSDL.
-       That is, to return the top-level components of the initial description and of all imported or 
-       included descriptions as well:
-       </p>
-<pre class="code">
-       Interface[] allInterfaces = descComp.getInterfaces();
-       Binding[] allBindings = descComp.getBindings();
-       Service[] allServices = descComp.getServices();</pre>
-<p>
-       The next example shows how to get all of the <span class="codefrag">ElementDeclaration</span> and <span class="codefrag">TypeDefinition</span>
-       components from the <span class="codefrag">Description</span> component. These represent the global schema element 
-       declarations and type definitions from the XML Schemas defined in-line or imported within the WSDL 
-       &lt;types&gt; element. Once again, this is a 'flattened' view that includes schema components from
-       imported or included WSDL documents (assuming the WSDL 2.0 rules about schema visibility have been followed):
-       </p>
-<pre class="code">
-       ElementDeclaration[] elemDecls = descComp.getElementDeclarations();
-       TypeDefinition[] typeDefs = descComp.getTypeDefinitions();</pre>
-</div>
-    
-    <!-- ================================================================ -->
-    
-<a name="N10150"></a><a name="The+Woden+API"></a>
-<h2 class="boxed">The Woden API</h2>
-<div class="section">
-<p>
-       This section provides an overview of the Woden API.
-       </p>
-<p>
-       The Woden WSDL processor is implemented as a framework with extension points for adding
-       user-defined behaviour. The details of this implementation are 'hidden' by the Woden API.
-       Even the extension points are exposed on the Woden API, either as Java interfaces that can 
-       be re-implemented or as Java classes that can be extended. With the Woden extension and 
-       programming model based on the API, there should be no need to refer to Woden implementation 
-       classes in user code. If you think you have such a need, please post your requirements to
-       the Woden development mailing list. 
-       </p>
-<p>
-       The Woden API contains two 'sub-APIs', introduced previously in the 
-       "Getting Started" section, which represent alternative WSDL 2.0 object models:
-       </p>
-<ul>
-       
-<li>
-       The <strong>Element</strong> API which represents a model of the XML elements and attributes in the 
-       WSDL 2.0 namespace, as described by the XML mappings in the WSDL 2.0 specification.
-       </li>
-       
-<li>
-       The <strong>Component</strong> API which represents the abstract WSDL Component model described by the WSDL 2.0 specification.
-       </li>
-       
-</ul>
-<p>
-       Whereas the Element and Component APIs are concerned solely with WSDL representation and manipulation, the
-       remainder of the Woden API is concerned with how to use, configure and extend the Woden WSDL processor.
-       The term <strong>Woden</strong> API encompasses these more general features of the Woden processor and
-       the WSDL-specific features. However if we need to discuss these WSDL-specific features of the API,
-       we may use the terms Element or Component API to be more specific.
-       </p>
-<p>
-<strong>API Packages</strong>
-</p>
-<p>
-       The Woden API is declared by Java interfaces and a small number of Java classes within
-       package names beginning with <span class="codefrag">org.apache.woden</span>. 
-       Woden implementation package names begin with <span class="codefrag">org.apache.woden.internal</span>
-       to distinguish them from the API packages. All other <span class="codefrag">org.apache.woden</span>
-       packages are part of the Woden API.
-       </p>
-<p>
-       The most important API packages are:
-       </p>
-<p>
-       
-<span class="codefrag">org.apache.woden</span>
-<br>
-       This contains the core components of the Woden WSDL processor - WSDLFactory, WSDLReader,
-       WSDLException, ErrorReporter, ErrorHandler to name a few.
-       </p>
-<p>
-       
-<span class="codefrag">org.apache.woden.schema</span>
-<br>
-       This contains interfaces representing both in-lined and imported XML schemas. These 
-       represent schemas in terms of the &lt;xs:schema&gt; and &lt;xs:import&gt; elements 
-       that can appear directly under the WSDL &lt;types&gt; element.
-       </p>
-<p>
-       
-<span class="codefrag">org.apache.woden.wsdl20.extensions</span>
-<br>
-       This represents the extension architecture to support extension elements and attributes
-       (i.e. those that are not in the WSDL 2.0 namespace). This includes a mechanism for
-       registering user-defined serializers, deserializers and Java mappings for these
-       extensions.
-       </p>
-<p>
-       
-<span class="codefrag">org.apache.woden.wsdl20.extensions.soap</span>
-<br>
-       This contains Java classes that map to the SOAP binding extensions defined in the WSDL 2.0 spec.
-       </p>
-<p>
-       
-<span class="codefrag">org.apache.woden.wsdl20</span>
-<br>
-       Contains the Java interfaces that make up the <strong>Component</strong> API (i.e. the abstract WSDL
-       Component model). 
-       </p>
-<p> 
-       
-<span class="codefrag">org.apache.woden.wsdl20.xml</span>
-<br>
-       Contains the Java interfaces that make up the <strong>Element</strong> API (i.e. the XML mappings 
-       for WSDL elements and attributes).
-       </p>
-<p>
-<strong>Core API Features</strong>
-</p>
-<p>
-       The core features of the Woden API include: 
-       </p>
-<ul>
-       
-<li>
-       The factory mechanism for creating Woden objects such as 
-       </li>
-       
-<li>
-       Configuring Woden behaviour by setting features or properties of the <span class="codefrag">WSDLReader</span>.
-       </li>
-       
-<li>
-       Customizing the error handling behaviour.
-       </li>
-       
-<li>
-       Registering user-defined extensions to support elements and attributes outside of the WSDL 2.0 namespace. 
-       </li>
-       
-<li>
-       Manipulating the XML-based model of WSDL elements and attributes (i.e. via the Element API).
-       </li>
-       
-<li>
-       Manipulating the abstract model of WSDL components (i.e. via the Component API).
-       </li>
-       
-</ul>
-<p>
-       The <span class="codefrag">WSDLFactory</span> class has static methods <em>newInstance()</em> and 
-       <em>newInstance(String className)</em> that return a factory object. 
-       The noarg version adopts a strategy to search for a user-configured factory classname, 
-       defaulting to a Woden-provided factory class if none is found.
-       The factory class name search strategy is to check first for a Java system property, 
-       then check for a property file in the JAVA-HOME/lib directory (we intend also to search for 
-       a property in META-INF/services but this is not implemented yet). 
-       The Javadoc for this class provides details of the system property and property file names. 
-       The <em>newInstance(String className)</em> version allows you to specify the factory class to be instantiated.
-       This factory object is used to create some of the key objects of the Woden programming model such as 
-       <span class="codefrag">WSDLReader</span>, <span class="codefrag">DescriptionElement</span> and <span class="codefrag">ExtensionRegistry</span>.
-       </p>
-<p>
-       The Woden parsing behaviour can be configured by setting features or properties of the 
-       <span class="codefrag">WSDLReader</span> object. Note, these are Woden-specific configuration details, not
-       to be confused with the WSDL Feature and Property components.
-       Reader features are configured via the <em>setFeature</em> method with a feature name and 
-       a boolean value, indicating whether the feature is enabled. The <em>getFeature</em> method
-       is used to query whether a specified feature is enabled. Reader properties are configured
-       via the <em>setProperty</em> method with a property name and an object representing the property.
-       Likewise, a <em>getProperty</em> method returns the property object for a specified property name.
-       The names of the Woden-defined features and properties are specified on the API as 
-       <span class="codefrag">public static final</span> constants on the <span class="codefrag">WSDLReader</span> interface.
-       See the API Javadoc for details.
-       These methods may also be used to configure user-defined, implementation-specific 
-       features and properties. The "Getting Started" section above showed an example of feature
-       configuration - the Woden validation feature was enabled on the reader object by the code:<br>
-       
-<span class="codefrag">reader.setFeature(WSDLReader.FEATURE_VALIDATION, true);</span>
-       
-</p>
-<p>
-       The API provides error handling through four interfaces and the <span class="codefrag">WSDLException</span> class.
-       System configuration errors are typically handled by throwing a <span class="codefrag">WSDLException</span> 
-       containing appropriate error information.
-       WSDL parsing errors are reported by the <span class="codefrag">ErrorReporter</span> which delegates the 
-       reporting style to the <span class="codefrag">ErrorHandler</span>.
-       <span class="codefrag">ErrorHandler</span> recognizes 3 types of error; warnings, errors and fatal errors.
-       A default error handler implementation is provided with Woden which prints all 3 types of  
-       message to <span class="codefrag">System.out</span> and then for fatal errors only, terminates processing with a
-       <span class="codefrag">WSDLException</span>.
-       Users may provide their own implementation of <span class="codefrag">ErrorHandler</span> to change this 
-       behaviour.
-       The <em>setErrorHandler</em> method on <span class="codefrag">ErrorReporter</span> is used to set a
-       user-defined custom error handler.
-       User-defined extensions to Woden may use <span class="codefrag">ErrorReporter</span> to report their errors 
-       via the <span class="codefrag">ErrorHandler</span> or to obtain a formatted error message, 
-       for example to place inside an exception object.
-       Messages are expected to have an error id and some message text, but 
-       users have the option of defining fully formatted messages or using parameterized
-       strings in a Java ResourceBundle.
-       <span class="codefrag">ErrorInfo</span> declares a data object containing the error information
-       passed to the <span class="codefrag">ErrorHandler</span>.
-       This includes the <span class="codefrag">ErrorLocator</span> which specifies the URI of the WSDL source document 
-       and the line and column number where the error occurred (although this feature is not yet implemented). 
-       </p>
-<p>
-       Extension elements and attributes (those outside of the WSDL 2.0 namespace) are handled 
-       by the Woden extension architecture. For each extension element, a user-defined implementation 
-       of the <span class="codefrag">ExtensionDeserializer</span> and <span class="codefrag">ExtensionSerializer</span> interfaces will 
-       map the element to/from some user-defined implementation of <span class="codefrag">ExtensionElement</span>
-       which represents the element.
-       The deserializer, serializer and Java mapping classes are registered in the 
-       <span class="codefrag">ExtensionRegistry</span> so that the <span class="codefrag">WSDLReader</span> (or WSDLWriter when it gets
-       implemented) will know what to do when it encounters this element. 
-       The Woden API includes <span class="codefrag">ExtensionElement</span> implementations to represent the 
-       SOAP binding extensions defined in the WSDL 2.0 spec (and HTTP extensions will follow soon).
-       To handle extension elements that have not been registered, default behaviour is provided by the 
-       <span class="codefrag">UnknownDeserializer</span>, <span class="codefrag">UnknownSerializer</span> and <span class="codefrag">UnknownExtensionElement</span> classes.
-       These Woden-defined extensions (SOAP and Unknown) are pre-registered in the <span class="codefrag">ExtensionRegistry</span>
-       by the Woden implementation.
-       </p>
-<p>
-       The package <span class="codefrag">org.apache.woden.xml</span> contains classes that represent the more common 
-       types of extension attribute values (e.g. string, QName, boolean, etc). These are all subclasses of 
-       <span class="codefrag">XMLAttr</span> which defines the <em>init</em> method for parsing an extension attribute value and the
-       <em>toExternalForm</em> method for representing the value as a string. Users may extend <span class="codefrag">XMLAttr</span>
-       to support other types of values. The <span class="codefrag">XMLAttr</span> subclass must be registered with its parent
-       class name (i.e. its containing element) and the QName of the extension attribute in the 
-       <span class="codefrag">ExtensionRegistry</span>, so that the <span class="codefrag">WSDLReader</span> will have the information necessary
-       to parse it correctly. The extension attributes defined in the WSDL 2.0 spec (i.e. those for the SOAP and
-       HTTP binding extensions) will be pre-registered in the <span class="codefrag">ExtensionRegistry</span> using the 
-       <span class="codefrag">XMLAttr</span> subclasses defined in package <span class="codefrag">org.apache.woden.xml</span>.  
-       </p>
-<p>
-       The Element and Component APIs are discussed below.
-       </p>
-<p>
-<strong>Element API</strong>
-</p>
-<p>
-       The Element API allows you to navigate the nested hierarchy of WSDL elements 
-       that would appear in a WSDL document (as defined by the 
-       <a href="http://www.w3.org/2006/01/wsdl/wsdl20.xsd">WSDL 2.0 Schema</a>). 
-       For example, <span class="codefrag">DescriptionElement</span> 
-       declares methods <em>getInterfaceElements</em>, <em>getBindingElements</em> and 
-       <em>getServiceElements</em> which provide access to the top-level WSDL elements. 
-       <span class="codefrag">InterfaceElement</span> declares the methods <em>getInterfaceFaultElements</em> and
-       <em>getInterfaceOperationElements</em> and so on.  
-       The Element API is described in detail
-       in the Javadocs included in the milestone distribution. 
-       </p>
-<p>
-       Within the <span class="codefrag">org.apache.woden.wsdl20.xml</span> package, each WSDL element is represented
-       by a Java interface.
-       The WSDL attributes present in each WSDL element are represented by appropriate methods on
-       those interfaces. So for example, <span class="codefrag">DescriptionElement</span> has the 
-       method <em>getTargetNamespace</em>. 
-       </p>
-<p>
-       Note that the methods of the Element API do not 'flatten' composite WSDL structures.
-       For example, the <em>getServiceElements</em> method returns the &lt;service&gt; elements
-       defined directly within the containing &lt;description&gt; element, but not 
-       those defined within any imported or included descriptions. To retrieve all of the
-       <span class="codefrag">ServiceElement</span>s from a composite WSDL, you need to navigate the WSDL structure
-       using the <em>getImportElements</em> or <em>getIncludeElements</em> methods on
-       <span class="codefrag">DescriptionElement</span>.
-       </p>
-<p>
-<strong>Component API</strong>
-</p>
-<p>
-       The Component API represents the abstract WSDL Component model described in the WSDL 2.0 spec.
-       This differs from the Element API in that certain aspects of WSDL XML are not represented in the Component model.
-       The &lt;documentation&gt; element is not captured in the Component model. 
-       The &lt;types&gt; element and particular type systems like XML Schema
-       are not represented, however the Component API does contain <span class="codefrag">ElementDeclaration</span>
-       and <span class="codefrag">TypeDefinition</span> which provide a general representation for global 
-       element declarations and type definitions, such as those used in XML Schema.
-       </p>
-<p>
-       The composition of WSDL documents via the &lt;import&gt; and &lt;include&gt; elements is
-       not represented in the Component model. Instead, the Description component 
-       represents the entire, composite WSDL structure and its properties which represent top-level 
-       WSDL components, like Interface, Binding and Service, contain a 'flattened' representation of the WSDL. 
-       For example, the <em>getInterfaces</em> method of <span class="codefrag">Description</span> will return not just the 
-       interfaces defined within the initial description, but those defined within any imported or included 
-       descriptions as well.
-       </p>
-<p>
-       The Component API provides a read-only view of the WSDL Component model 
-       (i.e. it defines accessors but no mutators).
-       The only way to create a <span class="codefrag">Description</span> object is by calling the <em>toComponent</em> method
-       on a <span class="codefrag">DescriptionElement</span> object. Once you have a <span class="codefrag">Description</span> object you can
-       access the rest of the WSDL component model, but you cannot modify it.
-       WSDL can only be created or modified programmatically via the Element API.
-       </p>
-<p>
-<strong>Mapping of WSDL elements to the API</strong>
-</p>
-<pre class="code">
-           WSDL element              Element API                           Component API
-                           
-       &lt;description&gt;           DescriptionElement                    Description
-         &lt;documentation&gt;       DocumentationElement
-         &lt;import&gt;              ImportElement
-         &lt;include&gt;             IncludeElement
-         &lt;types&gt;               TypesElement
-         &lt;interface&gt;           InterfaceElement                      Interface
-           &lt;fault&gt;             InterfaceFaultElement                 InterfaceFault
-           &lt;operation&gt;         InterfaceOperationElement             InterfaceOperation
-             &lt;input&gt;           InterfaceMessageReferenceElement      InterfaceMessageReference
-             &lt;output&gt;          InterfaceMessageReferenceElement      InterfaceMessageReference
-             &lt;infault&gt;         FaultReferenceElement                 InterfaceFaultReference
-             &lt;outfault&gt;        FaultReferenceElement                 InterfaceFaultReference
-         &lt;binding&gt;             BindingElement                        Binding
-           &lt;fault&gt;             BindingFaultElement                   BindingFault
-           &lt;operation&gt;         BindingOperationElement               BindingOperation
-             &lt;input&gt;           BindingMessageReferenceElement        BindingMessageReference
-             &lt;output&gt;          BindingMessageReferenceElement        BindingMessageReference
-             &lt;infault&gt;         FaultReferenceElement                 BindingFaultReference
-             &lt;outfault&gt;        FaultReferenceElement                 BindingFaultReference
-         &lt;service&gt;             ServiceElement                        Service
-           &lt;endpoint&gt;          EndpointElement                       Endpoint
-         &lt;feature&gt;             FeatureElement                        Feature
-         &lt;property&gt;            PropertyElement                       Property
-         
-          XML Schema element
-            
-       &lt;xs:import&gt;             ImportedSchema
-       &lt;xs:schema&gt;             InlinedSchema
-         &lt;xs:element name=".."&gt;                                     ElementDeclaration
-         &lt;xs:complexType name=".."&gt;                                 TypeDefinition
-       </pre>
-</div>
-    
-    <!-- ================================================================ -->
-    
-<a name="N102F1"></a><a name="Woden+URI+Resolver"></a>
-<h2 class="boxed">Woden URI Resolver</h2>
-<div class="section">
-<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 
-        <span class="codefrag">org.apache.woden.resolver.URIResolver</span>.
-        </p>
-<p>	
-        The resolver should be registered with the WSDLReader object before invoking <em>readWSDL()</em> methods.
-        </p>
-<p>Example:</p>
-<pre class="code">
-        URIResolver myResolver = new CustomURIResolver();
-        WSDLFactory factory = WSDLFactory.newInstance();
-        WSDLReader reader = factory.newWSDLReader();
-        reader.setURIResolver(myResolver);
-        ...
-        reader.readWSDL(&hellip;..);
-        </pre>
-<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 <span class="codefrag">SimpleURIResolver</span> is automatically instantiated and 
-       registered with it. In other words the following happens implicitly:</p>
-<pre class="code">
-       reader.setURIResolver(new SimpleURIResolver());
-       </pre>
-<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 
-       <span class="codefrag">&lt;property name&gt;=&lt;property value&gt;</span>, interspersed with comment lines starting with the &ldquo;#&rdquo; character. 
-       However, with catalog notation the meaning of the left and right hand expressions is slightly different:</p>
-<pre class="code">
-       &lt;resolve-from URI&gt;=&lt;resolve-to URI&gt;
-       </pre>
-<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 <span class="codefrag">.catalog</span>, though this is not mandatory.</p>
-<p>Note that the first &ldquo;:&rdquo; in the line of each entry must be escaped. See examples below.</p>
-<p>
-       The schema catalog is read sequentially when a <span class="codefrag">SimpleURIResolver</span> 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>
-<pre class="code">
-       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
-       </pre>
-<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 <span class="codefrag">org.apache.woden.resolver.simpleresolver.baseURIs</span> 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 <span class="codefrag">/wsdl/resources/interface.wsdl</span>,
-       <span class="codefrag">/xsd/resources/schema.xsd</span> and one file <span class="codefrag">/wibble/random.wsdl</span> contained in a JAR called <span class="codefrag">/mydocs.jar</span>. 
-       </p>
-<p>
-       We set the <span class="codefrag">org.apache.woden.resolver.simpleresolver.baseURIs</span> property to the value 
-       <span class="codefrag">file:///wsdl/;file:///xsd/;file:///mydocs.jar</span>. 
-       Note the trailing &ldquo;/&rdquo; 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>
-<pre class="code">
-       http\://test.com/importinterface.wsdl=resources/interface.wsdl
-       http\://test.com/myschema.xsd=resources/schema.xsd
-       http\://test.com/random.wsdl=wibble/random.wsdl
-       </pre>
-<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>
-<pre class="code">
-       http\://test.com/doit.wsdl=jar:file:///wibble/pling.jar!/doit.wsdl
-       </pre>
-<p>
-<strong>2 &ndash; 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&rsquo;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>
-<pre class="code">
-       System.setProperty(&ldquo;org.apache.woden.resolver.simpleresolver.catalog&rdquo;,
-                          &rdquo;file:///myplace/myresolves.catalog&rdquo;);
-       System.setProperty(&ldquo;org.apache.woden.resolver.simpleresolver.baseURIs&rdquo;,
-                          &ldquo;file:///wsdl/;file:///xsd/;file:///mydocs.jar&rdquo;);
-
-       WSDLReader reader = factory.newWSDLReader(); // instantiates the default resolver
-       reader.readWSDL(&ldquo;file:///mydoc.wsdl&rdquo;); // this is also a candidate for the resolver
-       </pre>
-<p>
-<strong>3 &ndash; Automatic schema resolution - schema.catalog</strong>
-</p>
-<p>
-       The Woden <em>schema catalog</em> is a predefined catalog which is loaded automatically when a 
-       <span class="codefrag">SimpleURIResolver</span> 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 <span class="codefrag">meta-inf/schema.catalog</span> in the Woden distribution jar.</p>
-</div> 
- 
-       
-    <!-- ================================================================ -->
-    
-<a name="N103D2"></a><a name="More+topics+to+be+added..."></a>
-<h2 class="boxed">More topics to be added...</h2>
-<div class="section">
-<p>
-       
-<em>
-       This User Guide is a work-in-progress. The content will be expanded and restructured as the
-       development of the Woden project progresses. The following list indicates some topics to be added:
-       </em>
-       
-</p>
-<ul>
-       
-<li>More on WSDLReader and readWSDL options (including URL resolution)</li>
-       
-<li>Types support (XML Schema)</li>
-       
-<li>Extension architecture (extension elements and attributes, extension registry)</li>
-       
-<li>Validation strategy (validation feature, continue-on-error feature)</li>
-       
-<li>Error reporting, error messages, customizing the ErrorHandler</li>
-       
-<li>creating or modifying WSDL programmatically</li>
-       
-<li>serializing WSDL with WSDLWriter</li>
-       
-<li>How to extend the Woden framework (details of extension points)</li>
-       
-</ul>
-</div>
-    
-  
-</div>
-<!--+
-    |end content
-    +-->
-<div class="clearboth">&nbsp;</div>
-</div>
-<div id="footer">
-<!--+
-    |start bottomstrip
-    +-->
-<div class="lastmodified">
-<script type="text/javascript"><!--
-document.write("Last Published: " + document.lastModified);
-//  --></script>
-</div>
-<div class="copyright">
-        Copyright &copy;
-         2005-2007 The Apache Software Foundation</div>
-<div id="feedback">
-    Send feedback about the website to:
-  <a id="feedbackto" href="mailto:woden-dev@ws.apache.org?subject=Woden-SiteFeedbackuserguide.html">woden-dev@ws.apache.org</a>
-</div>
-<!--+
-    |end bottomstrip
-    +-->
-</div>
-</body>
-</html>
+<!DOCTYPE html>
+<!--
+ | Generated by Apache Maven Doxia at 2015-07-05 
+ | Rendered using Apache Maven Fluido Skin 1.4
+-->
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="Date-Revision-yyyymmdd" content="20150705" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>Woden &#x2013; Woden User Guide</title>
+    <link rel="stylesheet" href="./css/apache-maven-fluido-1.4.min.css" />
+    <link rel="stylesheet" href="./css/site.css" />
+    <link rel="stylesheet" href="./css/print.css" media="print" />
+
+      
+    <script type="text/javascript" src="./js/apache-maven-fluido-1.4.min.js"></script>
+
+    
+                  </head>
+        <body class="topBarDisabled">
+          
+        
+    
+        <div class="container-fluid">
+          <div id="banner">
+        <div class="pull-left">
+                                                  <a href="index.html" id="bannerLeft">
+                                                                                                <img src="images/wodentitle.png"  alt="Apache Woden"/>
+                </a>
+                      </div>
+        <div class="pull-right">                                <a href="../" id="bannerRight">
+                                                                                                <img src="../images/project-logo.jpg" />
+                </a>
+      </div>
+        <div class="clear"><hr/></div>
+      </div>
+
+      <div id="breadcrumbs">
+        <ul class="breadcrumb">
+                
+                    
+                              <li class="">
+                    <a href="http://www.apache.org/" class="externalLink" title="Apache">
+        Apache</a>
+                    <span class="divider">/</span>
+      </li>
+            <li class="">
+                    <a href="../" title="Web Services">
+        Web Services</a>
+                    <span class="divider">/</span>
+      </li>
+                <li class="">
+                    <a href="./" title="Woden">
+        Woden</a>
+                    <span class="divider">/</span>
+      </li>
+        <li class="active ">Woden User Guide</li>
+        
+                
+                    
+                  <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2015-07-05</li>
+              <li id="projectVersion" class="pull-right">
+                    Version: 1.0-SNAPSHOT
+        </li>
+            
+                            </ul>
+      </div>
+
+            
+      <div class="row-fluid">
+        <div id="leftColumn" class="span2">
+          <div class="well sidebar-nav">
+                
+                    
+                <ul class="nav nav-list">
+                    <li class="nav-header">Woden</li>
+                              
+      <li>
+  
+                          <a href="index.html" title="Overview">
+          <span class="none"></span>
+        Overview</a>
+            </li>
+                
+      <li>
+  
+                          <a href="proposal.html" title="Proposal">
+          <span class="none"></span>
+        Proposal</a>
+            </li>
+                
+      <li>
+  
+                          <a href="mailinglists.html" title="Mailing Lists">
+          <span class="none"></span>
+        Mailing Lists</a>
+            </li>
+                
+      <li>
+  
+                          <a href="issue_tracking.html" title="Issue Tracking">
+          <span class="none"></span>
+        Issue Tracking</a>
+            </li>
+                
+      <li>
+  
+                          <a href="version_control.html" title="Version Control">
+          <span class="none"></span>
+        Version Control</a>
+            </li>
+                
+      <li>
+  
+                          <a href="projectteam.html" title="Project Team">
+          <span class="none"></span>
+        Project Team</a>
+            </li>
+                
+      <li>
+  
+                          <a href="projectsusingwoden.html" title="Projects Using Woden">
+          <span class="none"></span>
+        Projects Using Woden</a>
+            </li>
+                              <li class="nav-header">Downloads</li>
+                              
+      <li>
+  
+                          <a href="dev/1.0/builds.html" title="Builds">
+          <span class="none"></span>
+        Builds</a>
+            </li>
+                              <li class="nav-header">Documentation</li>
+                              
+      <li class="active">
+  
+            <a href="#"><span class="none"></span>User Guide</a>
+          </li>
+                              <li class="nav-header">Development</li>
+                              
+      <li>
+  
+                          <a href="dev/index.html" title="Woden Development">
+          <span class="none"></span>
+        Woden Development</a>
+            </li>
+                
+      <li>
+  
+                          <a href="dev/devprocess.html" title="Development Processes">
+          <span class="none"></span>
+        Development Processes</a>
+            </li>
+                
+      <li>
+  
+                          <a href="dev/1.0/milestoneplan.html" title="Milestone Plan">
+          <span class="none"></span>
+        Milestone Plan</a>
+            </li>
+                              <li class="nav-header">Apache</li>
+                              
+      <li>
+  
+                          <a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="License">
+          <span class="none"></span>
+        License</a>
+            </li>
+                
+      <li>
+  
+                          <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship">
+          <span class="none"></span>
+        Sponsorship</a>
+            </li>
+                
+      <li>
+  
+                          <a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks">
+          <span class="none"></span>
+        Thanks</a>
+            </li>
+                
+      <li>
+  
+                          <a href="http://www.apache.org/security/" class="externalLink" title="Security">
+          <span class="none"></span>
+        Security</a>
+            </li>
+            </ul>
+                
+                    
+                
+          <hr />
+
+           <div id="poweredBy">
+                            <div class="clear"></div>
+                            <div class="clear"></div>
+                            <div class="clear"></div>
+                            <div class="clear"></div>
+                             <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+        <img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" />
+      </a>
+                  </div>
+          </div>
+        </div>
+        
+                
+        <div id="bodyColumn"  class="span10" >
+                                  
+            <!-- ! Licensed to the Apache Software Foundation (ASF) under one or more
+ ! contributor license agreements.  See the NOTICE file distributed with
+ ! this work for additional information regarding copyright ownership.
+ ! The ASF licenses this file to You under the Apache License, Version 2.0
+ ! (the "License"); you may not use this file except in compliance with
+ ! the License.  You may obtain a copy of the License at
+ !
+ !      http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing, software
+ ! distributed under the License is distributed on an "AS IS" BASIS,
+ ! WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ! See the License for the specific language governing permissions and
+ ! limitations under the License.
+ ! -->
+  
+  
+  
+    <!-- ================================================================ -->
+    <a name="intro"></a>
+<div class="section" id="intro">
+<h2><a name="Introduction"></a>Introduction</h2>
+       
+<p>
+       The purpose of the Woden User Guide is to explain how to use the external interfaces 
+       of Woden. These external interfaces currently consist of the Woden API, but as development
+       progresses they may also include other configuration techniques, command
+       line tools and script-based utilities such as ANT tasks.
+       Woden users are typically developers of other tools and technologies that use Woden 
+       for parsing or manipulating WSDL documents. 
+       </p>
+       
+<p>
+       The Woden User Guide will not discuss the 'internals' of the Woden implementation and
+       it will only touch on the Woden design where it is relevant to this discussion of how 
+       to use Woden. A Woden Developer Guide (not yet written) will discuss the design and
+       implementation.
+       </p>
+       
+<p>
+       The User Guide reflects the current state of Woden's development and will be updated as 
+       new function is added to Woden. See the &quot;Woden Overview&quot; section below for up-to-date
+       details of what function currently exists and what doesn't.
+       </p>
+       
+<p>
+       This Guide should be read in conjunction with the Woden API Javadocs included with the
+       milestone distribution (see the &quot;Download and Setup&quot; section below).
+       Please post any questions or comments to the Woden development mailing list, 
+       <a class="externalLink" href="mailto:woden-dev@ws.apache.org">woden-dev@ws.apache.org</a>.
+       </p>
+
+    </div>
+    
+    <!-- ================================================================ -->
+    <a name="overview"></a>
+<div class="section" id="overview">
+<h2><a name="Woden_Overview"></a>Woden Overview</h2>
+       
+<p>
+       The initial goal of the Woden project is to develop a WSDL 2.0 processor that implements
+       the W3C WSDL 2.0 specification in response to the Working Group's call for implementations.
+       This includes defining an API for Woden separate to its implementation, so that other projects 
+       can modify or replace the Woden implementation while maintaining consistent external interfaces.
+       Further goals include support for high performance XML parsing and support for WSDL 1.1.
+       </p>
+       
+<p>
+       The objectives to achieve these goals are:
+       </p>
+       
+<ul>
+       
+<li>
+       Develop a WSDL 2.0 processor (DOM-based initially) for serializing and deserializing WSDL 2.0 documents.
+       </li>
+       
+<li>
+       Define a WSDL object model that conforms to the W3C WSDL 2.0 spec, including support for 
+       WSDL and type system extensibility.
+       </li>
+       
+<li>
+       Enable WSDL to be created or modified programmatically via this object model.
+       </li>
+       
+<li>
+       Develop Woden as a configurable and extendable framework to support implementation-specific 
+       customization, such as customization of object factories, validation and error handling.
+       </li>
+       
+<li>
+       Develop a framework extension mechanism that allows alternative XML parsers to be used to support different 
+       usage scenarios and performance requirements, then develop a WSDL parser implementation based on an 
+       XML streaming 'pull' parser such as StAX (JSR173).
+       </li>
+       
+<li>
+       Support deserializing WSDL 1.1 documents and optionally converting them into the WSDL 2.0 object model. 
+       </li>
+       
+<li>
+       Support deserializing WSDL 1.1 documents and optionally representing them with the JWSDL object model
+       (i.e. the WSDL 1.1 object model defined by JSR110 &quot;Java APIs for WSDL&quot; and currently implemented by WSDL4J).
+       </li>
+       
+<li>
+       Develop a comprehensive Junit-based test suite that integrates the WSDL test cases 
+       from the W3C WSDL 2.0 test suite and includes Woden-specific tests that cover its API and
+       the features of the Woden framework.
+       </li>
+       </ul>
+       
+       
+<p><br />
+       The functionality that currently exists in Woden and is described in this User Guide includes:
+       </p>
+       
+<ul>
+       
+<li>
+       A factory mechanism used to obtain a WSDL reader (or parser) object.
+       </li>
+       
+<li>
+       A DOM implementation of the reader, based on Apache Xerces.
+       </li>
+       
+<li>
+       Configuring WSDL reader features and properties - for example, switching the validation feature on or off.
+       </li>
+       
+<li>
+       Using the reader to parse (deserialize) a WSDL document at a specified URL into the Woden WSDL 2.0 object model.
+       </li>
+       
+<li>
+       Two forms of the WSDL 2.0 object model; one representing the WSDL 2.0 abstract Component model and one 
+       that maps to the XML elements and attributes in the WSDL namespace.
+       </li>
+       
+<li>
+       Parsing of most of the elements and attributes in the WSDL 2.0 namespace 
+       (the 'extends' attribute of Interface is the only outstanding item).
+       </li>
+       
+<li>
+       Partial WSDL validation using the assertions defined in the WSDL 2.0 spec. 
+       Validation currently exists for Types, Interface and Binding.
+       </li>
+       
+<li>
+       Manipulating the WSDL via methods of the WSDL 2.0 object model. 
+       </li>
+       
+<li>
+       Support for extensibility elements and attributes (i.e. for XML elements and 
+       attributes that extend elements in the WSDL 2.0 namespace).
+       </li>
+       
+<li>
+       Use of this extensibility mechanism for the SOAP binding extensions defined in the WSDL 2.0 spec.
+       </li>
+       
+<li>
+       A customizable error handling mechanism for reporting warnings, errors or fatal errors
+       that result from WSDL validation or Woden configuration problems.
+       </li>
+       </ul>
+       
+       
+<p><br />
+       Planned functionality that does not yet exist in Woden and is NOT described in this User Guide includes:
+       </p>
+       
+<ul>
+       
+<li>
+       Parsing  of HTTP binding extensions, as defined in the WSDL 2.0 spec.
+       </li>
+       
+<li>
+       WSDL validation of import and include, SOAP and HTTP binding extensions, and Service.
+       </li>
+       
+<li>
+       Resolving URLs with an entity or catalog resolver
+       </li>
+       
+<li>
+       A mechanism for extending Woden to support other XML parsers.
+       </li>
+       
+<li>
+       A StAX implementation of this parser extension mechanism.
+       </li>
+       
+<li>
+       A mechanism for extending Woden to support types systems other than W3C XML Schema
+       (e.g. RelaxNG, DTD). 
+       </li>
+       
+<li>
+       Writing (serializing) the WSDL object model out to a WSDL document.
+       </li>
+       
+<li>
+       Parsing WSDL 1.1 documents and converting them into the WSDL 2.0 object model. 
+       </li>
+       
+<li>
+       Parsing WSDL 1.1 documents and representing them using the JWSDL object model 
+       (i.e. a WSDL 1.1 object model)
+       </li>
+       </ul>
+
+    </div>
+    
+    <!-- ================================================================ -->
+    
+<div class="section">
+<h2><a name="Download_and_Setup"></a>Download and Setup</h2>
+       
+<p>Obtain the Apache Woden WSDL processor in one of 2 ways:</p>
+       
+<ul>
+       
+<li>extract the source code from the Woden Subversion (SVN) <a href="version_control.html">repository</a> and compile it, or</li>
+       
+<li>obtain the Woden binary distribution from the latest <a href="dev/1.0/builds.html">milestone build</a>.</li>
+       </ul>
+       
+<p>
+       Woden's DOM-based XML parsing depends on Apache Xerces 2.7.1.
+       Its XML Schema support it depends on the schema parser and object model implemented by 
+       the Apache Web Services Commons (ws-commons) XmlSchema project.
+       </p>
+       
+<p>
+       The milestone build includes all of the required libraries and these must be on the classpath:
+       </p>
+       
+<ul>
+       
+<li>woden.jar contains the Woden binary code</li>
+       
+<li>xercesImpl.jar and xml-apis.jar contain Apache Xerces 2.7.1</li>
+       
+<li>XmlSchema-SNAPSHOT.jar contains the Apache ws-commons XmlSchema</li>
+       </ul>
+       
+<p>
+       If using the Woden source code, rather than the milestone distribution, then the Apache Xerces 2.7.1 
+       distribution can be downloaded from the Apache Xerces project <a class="externalLink" href="http://xerces.apache.org/xerces2-j/download.cgi">here</a>.
+       The source code for Apache Web Services ws-commons XmlSchema can be extracted from its
+       Subversion (SVN) <a class="externalLink" href="http://svn.apache.org/repos/asf/webservices/commons/modules/XmlSchema/">repository</a>
+       using the logon id &quot;anoncvs&quot;.
+       </p>
+       
+<p>
+       Woden requires Java 1.4 or higher.
+       </p>
+       
+    </div>
+    
+    <!-- ================================================================ -->
+    
+<div class="section">
+<h2><a name="Getting_Started"></a>Getting Started</h2>
+       
+<p>
+       This section contains a few code examples to demonstrate the Woden programming model. See &quot;The Woden API&quot;
+       section below and the Javadocs included with the milestone distribution for more details.
+       </p>
+       
+<p>
+       The following code example shows how to obtain a <tt>WSDLFactory</tt> object which is then used to obtain
+       a <tt>WSDLReader</tt> object (the WSDL parser). 
+       WSDL validation is then enabled on the reader, before the <i>readWSDL</i> method reads a WSDL document
+       from the specified URL and returns the WSDL as a <tt>Description</tt> object. 
+       The <tt>Description</tt> represents the Description component from the WSDL 2.0
+       Component model. The API declared by <tt>Description</tt> and its contained objects will be
+       referred to as the <b>Component</b> API. 
+       The <i>toElement</i> method on <tt>Description</tt> returns the WSDL as a 
+       <tt>DescriptionElement</tt> object, which represents the WSDL &lt;description&gt; element and along with
+       its contained objects, it declares an API that maps to the XML elements and attributes in the 
+       WSDL 2.0 namespace. This will be referred to as the <b>Element</b> API.
+       </p>
+<div class="source"><pre class="prettyprint">
+       WSDLFactory factory = WSDLFactory.newInstance();
+       WSDLReader reader = factory.newWSDLReader();
+       reader.setFeature(WSDLReader.FEATURE_VALIDATION, true);
+       Description descComp = reader.readWSDL(wsdlurl);        &lt;-- the Description component
+       DescriptionElement descElem = descElem.toComponent();   &lt;-- the &lt;description&gt; element</pre></div>
+       
+       
+<p>
+       The parameter <tt>wsdlurl</tt> is the String representation of a URL, e.g.:
+       </p>
+<div class="source"><pre class="prettyprint">
+       wsdlurl=&quot;http://ws.org.apache/woden/services/Booking.wsdl&quot; 
+       wsdlurl=&quot;C:/woden/services/Booking.wsdl&quot;</pre></div>
+       
+       
+<p>
+       To obtain the top-level WSDL elements from the <tt>DescriptionElement</tt>:
+       </p>
+<div class="source"><pre class="prettyprint">
+       InterfaceElement[] interfaces = descElem.getInterfaceElements();
+       BindingElement[] bindings = descElem.getBindingElements();
+       ServiceElement[] services = descElem.getServiceElements();</pre></div>
+       
+       
+<p>
+       This example shows how to get the global schema element declaration (represented by the
+       <tt>XmlSchemaElement</tt> class from Apache ws-commons XmlSchema) which is referred to by 
+       QName in the 'element' attribute of the interface &lt;fault&gt; element:
+       </p>
+<div class="source"><pre class="prettyprint">
+       InterfaceElement interfaceElem = interfaces[0];
+       InterfaceFaultElement[] faults = interfaceElem.getInterfaceFaultElements();
+       XmlSchemaElement xsElem = faults[0].getXmlSchemaElement();</pre></div>
+       
+       
+<p>
+       Where the WSDL is composed of multiple WSDL documents via WSDL &lt;import&gt; and 
+       &lt;include&gt;, you can navigate the WSDL modules using the methods
+       <i>getImportElements</i> and <i>getIncludeElements</i> of <tt>DescriptionElement</tt>:
+       </p>
+<div class="source"><pre class="prettyprint">
+       ImportElement[] imports = descElem.getImportElements();
+       DescriptionElement importedDescElem = imports[0].getDescriptionElement();</pre></div>
+       
+       
+<p>
+       The <tt>Description</tt> component also has methods to retrieve the top-level WSDL components, 
+       but unlike those in <tt>DescriptionElement</tt>, the behaviour here is to 'flatten' the WSDL.
+       That is, to return the top-level components of the initial description and of all imported or 
+       included descriptions as well:
+       </p>
+<div class="source"><pre class="prettyprint">
+       Interface[] allInterfaces = descComp.getInterfaces();
+       Binding[] allBindings = descComp.getBindings();
+       Service[] allServices = descComp.getServices();</pre></div>
+
+       
+<p>
+       The next example shows how to get all of the <tt>ElementDeclaration</tt> and <tt>TypeDefinition</tt>
+       components from the <tt>Description</tt> component. These represent the global schema element 
+       declarations and type definitions from the XML Schemas defined in-line or imported within the WSDL 
+       &lt;types&gt; element. Once again, this is a 'flattened' view that includes schema components from
+       imported or included WSDL documents (assuming the WSDL 2.0 rules about schema visibility have been followed):
+       </p>
+<div class="source"><pre class="prettyprint">
+       ElementDeclaration[] elemDecls = descComp.getElementDeclarations();
+       TypeDefinition[] typeDefs = descComp.getTypeDefinitions();</pre></div>
+       
+    </div>
+    
+    <!-- ================================================================ -->
+    
+<div class="section">
+<h2><a name="The_Woden_API"></a>The Woden API</h2>
+       
+       
+<p>
+       This section provides an overview of the Woden API.
+       </p>
+       
+<p>
+       The Woden WSDL processor is implemented as a framework with extension points for adding
+       user-defined behaviour. The details of this implementation are 'hidden' by the Woden API.
+       Even the extension points are exposed on the Woden API, either as Java interfaces that can 
+       be re-implemented or as Java classes that can be extended. With the Woden extension and 
+       programming model based on the API, there should be no need to refer to Woden implementation 
+       classes in user code. If you think you have such a need, please post your requirements to
+       the Woden development mailing list. 
+       </p>
+       
+<p>
+       The Woden API contains two 'sub-APIs', introduced previously in the 
+       &quot;Getting Started&quot; section, which represent alternative WSDL 2.0 object models:
+       </p>
+      
+<ul>
+       
+<li>
+       The <b>Element</b> API which represents a model of the XML elements and attributes in the 
+       WSDL 2.0 namespace, as described by the XML mappings in the WSDL 2.0 specification.
+       </li>
+       
+<li>
+       The <b>Component</b> API which represents the abstract WSDL Component model described by the WSDL 2.0 specification.
+       </li>
+       </ul>
+       
+       
+<p>
+       Whereas the Element and Component APIs are concerned solely with WSDL representation and manipulation, the
+       remainder of the Woden API is concerned with how to use, configure and extend the Woden WSDL processor.
+       The term <b>Woden</b> API encompasses these more general features of the Woden processor and
+       the WSDL-specific features. However if we need to discuss these WSDL-specific features of the API,
+       we may use the terms Element or Component API to be more specific.
+       </p>
+       
+       
+<p><b>API Packages</b></p>
+       
+<p>
+       The Woden API is declared by Java interfaces and a small number of Java classes within
+       package names beginning with <tt>org.apache.woden</tt>. 
+       Woden implementation package names begin with <tt>org.apache.woden.internal</tt>
+       to distinguish them from the API packages. All other <tt>org.apache.woden</tt>
+       packages are part of the Woden API.
+       </p>
+       
+<p>
+       The most important API packages are:
+       </p>
+       
+<p>
+       <tt>org.apache.woden</tt><br />
+       This contains the core components of the Woden WSDL processor - WSDLFactory, WSDLReader,
+       WSDLException, ErrorReporter, ErrorHandler to name a few.
+       </p> 
+       
+       
+<p>
+       <tt>org.apache.woden.schema</tt><br />
+       This contains interfaces representing both in-lined and imported XML schemas. These 
+       represent schemas in terms of the &lt;xs:schema&gt; and &lt;xs:import&gt; elements 
+       that can appear directly under the WSDL &lt;types&gt; element.
+       </p> 
+       
+       
+<p>
+       <tt>org.apache.woden.wsdl20.extensions</tt><br />
+       This represents the extension architecture to support extension elements and attributes
+       (i.e. those that are not in the WSDL 2.0 namespace). This includes a mechanism for
+       registering user-defined serializers, deserializers and Java mappings for these
+       extensions.
+       </p> 
+       
+       
+<p>
+       <tt>org.apache.woden.wsdl20.extensions.soap</tt><br />
+       This contains Java classes that map to the SOAP binding extensions defined in the WSDL 2.0 spec.
+       </p> 
+       
+       
+<p>
+       <tt>org.apache.woden.wsdl20</tt><br />
+       Contains the Java interfaces that make up the <b>Component</b> API (i.e. the abstract WSDL
+       Component model). 
+       </p>
+       
+       
+<p> 
+       <tt>org.apache.woden.wsdl20.xml</tt><br />
+       Contains the Java interfaces that make up the <b>Element</b> API (i.e. the XML mappings 
+       for WSDL elements and attributes).
+       </p>
+       
+       
+<p><b>Core API Features</b></p>
+       
+<p>
+       The core features of the Woden API include: 
+       </p>
+       
+<ul>
+       
+<li>
+       The factory mechanism for creating Woden objects such as 
+       </li>
+       
+<li>
+       Configuring Woden behaviour by setting features or properties of the <tt>WSDLReader</tt>.
+       </li>
+       
+<li>
+       Customizing the error handling behaviour.
+       </li>
+       
+<li>
+       Registering user-defined extensions to support elements and attributes outside of the WSDL 2.0 namespace. 
+       </li>
+       
+<li>
+       Manipulating the XML-based model of WSDL elements and attributes (i.e. via the Element API).
+       </li>
+       
+<li>
+       Manipulating the abstract model of WSDL components (i.e. via the Component API).
+       </li>
+       </ul> 
+       
+       
+<p>
+       The <tt>WSDLFactory</tt> class has static methods <i>newInstance()</i> and 
+       <i>newInstance(String className)</i> that return a factory object. 
+       The noarg version adopts a strategy to search for a user-configured factory classname, 
+       defaulting to a Woden-provided factory class if none is found.
+       The factory class name search strategy is to check first for a Java system property, 
+       then check for a property file in the JAVA-HOME/lib directory (we intend also to search for 
+       a property in META-INF/services but this is not implemented yet). 
+       The Javadoc for this class provides details of the system property and property file names. 
+       The <i>newInstance(String className)</i> version allows you to specify the factory class to be instantiated.
+       This factory object is used to create some of the key objects of the Woden programming model such as 
+       <tt>WSDLReader</tt>, <tt>DescriptionElement</tt> and <tt>ExtensionRegistry</tt>.
+       </p>
+       
+<p>
+       The Woden parsing behaviour can be configured by setting features or properties of the 
+       <tt>WSDLReader</tt> object. Note, these are Woden-specific configuration details, not
+       to be confused with the WSDL Feature and Property components.
+       Reader features are configured via the <i>setFeature</i> method with a feature name and 
+       a boolean value, indicating whether the feature is enabled. The <i>getFeature</i> method
+       is used to query whether a specified feature is enabled. Reader properties are configured
+       via the <i>setProperty</i> method with a property name and an object representing the property.
+       Likewise, a <i>getProperty</i> method returns the property object for a specified property name.
+       The names of the Woden-defined features and properties are specified on the API as 
+       <tt>public static final</tt> constants on the <tt>WSDLReader</tt> interface.
+       See the API Javadoc for details.
+       These methods may also be used to configure user-defined, implementation-specific 
+       features and properties. The &quot;Getting Started&quot; section above showed an example of feature
+       configuration - the Woden validation feature was enabled on the reader object by the code:<br />
+       <tt>reader.setFeature(WSDLReader.FEATURE_VALIDATION, true);</tt>
+       </p>
+       
+<p>
+       The API provides error handling through four interfaces and the <tt>WSDLException</tt> class.
+       System configuration errors are typically handled by throwing a <tt>WSDLException</tt> 
+       containing appropriate error information.
+       WSDL parsing errors are reported by the <tt>ErrorReporter</tt> which delegates the 
+       reporting style to the <tt>ErrorHandler</tt>.
+       <tt>ErrorHandler</tt> recognizes 3 types of error; warnings, errors and fatal errors.
+       A default error handler implementation is provided with Woden which prints all 3 types of  
+       message to <tt>System.out</tt> and then for fatal errors only, terminates processing with a
+       <tt>WSDLException</tt>.
+       Users may provide their own implementation of <tt>ErrorHandler</tt> to change this 
+       behaviour.
+       The <i>setErrorHandler</i> method on <tt>ErrorReporter</tt> is used to set a
+       user-defined custom error handler.
+       User-defined extensions to Woden may use <tt>ErrorReporter</tt> to report their errors 
+       via the <tt>ErrorHandler</tt> or to obtain a formatted error message, 
+       for example to place inside an exception object.
+       Messages are expected to have an error id and some message text, but 
+       users have the option of defining fully formatted messages or using parameterized
+       strings in a Java ResourceBundle.
+       <tt>ErrorInfo</tt> declares a data object containing the error information
+       passed to the <tt>ErrorHandler</tt>.
+       This includes the <tt>ErrorLocator</tt> which specifies the URI of the WSDL source document 
+       and the line and column number where the error occurred (although this feature is not yet implemented). 
+       </p>
+       
+<p>
+       Extension elements and attributes (those outside of the WSDL 2.0 namespace) are handled 
+       by the Woden extension architecture. For each extension element, a user-defined implementation 
+       of the <tt>ExtensionDeserializer</tt> and <tt>ExtensionSerializer</tt> interfaces will 
+       map the element to/from some user-defined implementation of <tt>ExtensionElement</tt>
+       which represents the element.
+       The deserializer, serializer and Java mapping classes are registered in the 
+       <tt>ExtensionRegistry</tt> so that the <tt>WSDLReader</tt> (or WSDLWriter when it gets
+       implemented) will know what to do when it encounters this element. 
+       The Woden API includes <tt>ExtensionElement</tt> implementations to represent the 
+       SOAP binding extensions defined in the WSDL 2.0 spec (and HTTP extensions will follow soon).
+       To handle extension elements that have not been registered, default behaviour is provided by the 
+       <tt>UnknownDeserializer</tt>, <tt>UnknownSerializer</tt> and <tt>UnknownExtensionElement</tt> classes.
+       These Woden-defined extensions (SOAP and Unknown) are pre-registered in the <tt>ExtensionRegistry</tt>
+       by the Woden implementation.
+       </p>
+       
+<p>
+       The package <tt>org.apache.woden.xml</tt> contains classes that represent the more common 
+       types of extension attribute values (e.g. string, QName, boolean, etc). These are all subclasses of 
+       <tt>XMLAttr</tt> which defines the <i>init</i> method for parsing an extension attribute value and the
+       <i>toExternalForm</i> method for representing the value as a string. Users may extend <tt>XMLAttr</tt>
+       to support other types of values. The <tt>XMLAttr</tt> subclass must be registered with its parent
+       class name (i.e. its containing element) and the QName of the extension attribute in the 
+       <tt>ExtensionRegistry</tt>, so that the <tt>WSDLReader</tt> will have the information necessary
+       to parse it correctly. The extension attributes defined in the WSDL 2.0 spec (i.e. those for the SOAP and
+       HTTP binding extensions) will be pre-registered in the <tt>ExtensionRegistry</tt> using the 
+       <tt>XMLAttr</tt> subclasses defined in package <tt>org.apache.woden.xml</tt>.  
+       </p>
+       
+<p>
+       The Element and Component APIs are discussed below.
+       </p>
+
+       
+<p><b>Element API</b></p>
+       
+<p>
+       The Element API allows you to navigate the nested hierarchy of WSDL elements 
+       that would appear in a WSDL document (as defined by the 
+       <a class="externalLink" href="http://www.w3.org/2006/01/wsdl/wsdl20.xsd">WSDL 2.0 Schema</a>). 
+       For example, <tt>DescriptionElement</tt> 
+       declares methods <i>getInterfaceElements</i>, <i>getBindingElements</i> and 
+       <i>getServiceElements</i> which provide access to the top-level WSDL elements. 
+       <tt>InterfaceElement</tt> declares the methods <i>getInterfaceFaultElements</i> and
+       <i>getInterfaceOperationElements</i> and so on.  
+       The Element API is described in detail
+       in the Javadocs included in the milestone distribution. 
+       </p>
+       
+<p>
+       Within the <tt>org.apache.woden.wsdl20.xml</tt> package, each WSDL element is represented
+       by a Java interface.
+       The WSDL attributes present in each WSDL element are represented by appropriate methods on
+       those interfaces. So for example, <tt>DescriptionElement</tt> has the 
+       method <i>getTargetNamespace</i>. 
+       </p>
+       
+<p>
+       Note that the methods of the Element API do not 'flatten' composite WSDL structures.
+       For example, the <i>getServiceElements</i> method returns the &lt;service&gt; elements
+       defined directly within the containing &lt;description&gt; element, but not 
+       those defined within any imported or included descriptions. To retrieve all of the
+       <tt>ServiceElement</tt>s from a composite WSDL, you need to navigate the WSDL structure
+       using the <i>getImportElements</i> or <i>getIncludeElements</i> methods on
+       <tt>DescriptionElement</tt>.
+       </p>
+       
+       
+<p><b>Component API</b></p>
+       
+<p>
+       The Component API represents the abstract WSDL Component model described in the WSDL 2.0 spec.
+       This differs from the Element API in that certain aspects of WSDL XML are not represented in the Component model.
+       The &lt;documentation&gt; element is not captured in the Component model. 
+       The &lt;types&gt; element and particular type systems like XML Schema
+       are not represented, however the Component API does contain <tt>ElementDeclaration</tt>
+       and <tt>TypeDefinition</tt> which provide a general representation for global 
+       element declarations and type definitions, such as those used in XML Schema.
+       </p>
+       
+<p>
+       The composition of WSDL documents via the &lt;import&gt; and &lt;include&gt; elements is
+       not represented in the Component model. Instead, the Description component 
+       represents the entire, composite WSDL structure and its properties which represent top-level 
+       WSDL components, like Interface, Binding and Service, contain a 'flattened' representation of the WSDL. 
+       For example, the <i>getInterfaces</i> method of <tt>Description</tt> will return not just the 
+       interfaces defined within the initial description, but those defined within any imported or included 
+       descriptions as well.
+       </p>
+       
+<p>
+       The Component API provides a read-only view of the WSDL Component model 
+       (i.e. it defines accessors but no mutators).
+       The only way to create a <tt>Description</tt> object is by calling the <i>toComponent</i> method
+       on a <tt>DescriptionElement</tt> object. Once you have a <tt>Description</tt> object you can
+       access the rest of the WSDL component model, but you cannot modify it.
+       WSDL can only be created or modified programmatically via the Element API.
+       </p>
+
+       
+<p><b>Mapping of WSDL elements to the API</b></p>
+       
+<div class="source"><pre class="prettyprint">
+           WSDL element              Element API                           Component API
+                           
+       &lt;description&gt;           DescriptionElement                    Description
+         &lt;documentation&gt;       DocumentationElement
+         &lt;import&gt;              ImportElement
+         &lt;include&gt;             IncludeElement
+         &lt;types&gt;               TypesElement
+         &lt;interface&gt;           InterfaceElement                      Interface
+           &lt;fault&gt;             InterfaceFaultElement                 InterfaceFault
+           &lt;operation&gt;         InterfaceOperationElement             InterfaceOperation
+             &lt;input&gt;           InterfaceMessageReferenceElement      InterfaceMessageReference
+             &lt;output&gt;          InterfaceMessageReferenceElement      InterfaceMessageReference
+             &lt;infault&gt;         FaultReferenceElement                 InterfaceFaultReference
+             &lt;outfault&gt;        FaultReferenceElement                 InterfaceFaultReference
+         &lt;binding&gt;             BindingElement                        Binding
+           &lt;fault&gt;             BindingFaultElement                   BindingFault
+           &lt;operation&gt;         BindingOperationElement               BindingOperation
+             &lt;input&gt;           BindingMessageReferenceElement        BindingMessageReference
+             &lt;output&gt;          BindingMessageReferenceElement        BindingMessageReference
+             &lt;infault&gt;         FaultReferenceElement                 BindingFaultReference
+             &lt;outfault&gt;        FaultReferenceElement                 BindingFaultReference

[... 283 lines stripped ...]


Mime
View raw message