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 jk...@apache.org on 2006/02/01 16:52:24 UTC
svn commit: r374091 - in
/incubator/woden/Site/src/documentation/content/xdocs: site.xml userguide.xml
Author: jkaputin
Date: Wed Feb 1 07:52:17 2006
New Revision: 374091
URL: http://svn.apache.org/viewcvs?rev=374091&view=rev
Log:
Created a User Guide and added a 'Documentation' category
to the Woden navigation bar with a 'User Guide' link.
Added:
incubator/woden/Site/src/documentation/content/xdocs/userguide.xml
Modified:
incubator/woden/Site/src/documentation/content/xdocs/site.xml
Modified: incubator/woden/Site/src/documentation/content/xdocs/site.xml
URL: http://svn.apache.org/viewcvs/incubator/woden/Site/src/documentation/content/xdocs/site.xml?rev=374091&r1=374090&r2=374091&view=diff
==============================================================================
--- incubator/woden/Site/src/documentation/content/xdocs/site.xml (original)
+++ incubator/woden/Site/src/documentation/content/xdocs/site.xml Wed Feb 1 07:52:17 2006
@@ -41,6 +41,9 @@
<downloads label="Downloads" tab="woden">
<releases label="Releases" href="releases.html" description="Woden - Releases"/>
</downloads>
+ <documentation label="Documentation" tab="woden">
+ <userguide label="User Guide" href="userguide.html" description="Woden - User Guide"/>
+ </documentation>
<devgeneral label="General" tab="development">
<wodendev label="Woden Development" href="dev/index.html" description="Woden Development Overview"/>
Added: incubator/woden/Site/src/documentation/content/xdocs/userguide.xml
URL: http://svn.apache.org/viewcvs/incubator/woden/Site/src/documentation/content/xdocs/userguide.xml?rev=374091&view=auto
==============================================================================
--- incubator/woden/Site/src/documentation/content/xdocs/userguide.xml (added)
+++ incubator/woden/Site/src/documentation/content/xdocs/userguide.xml Wed Feb 1 07:52:17 2006
@@ -0,0 +1,612 @@
+<?xml version="1.0"?>
+
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+
+<document>
+
+ <header>
+ <title>Woden User Guide</title>
+ </header>
+
+ <body>
+
+ <!-- ================================================================ -->
+ <section id="intro">
+ <title>Introduction</title>
+ <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@ws.apache.org">woden-dev@ws.apache.org</a>.
+ </p>
+
+ </section>
+
+ <!-- ================================================================ -->
+ <section id="overview">
+ <title>Woden Overview</title>
+ <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>
+
+ </section>
+
+ <!-- ================================================================ -->
+ <section>
+ <title>Download and Setup</title>
+ <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/trunk/XmlSchema/">repository</a>
+ using the logon id "anoncvs".
+ </p>
+ <p>
+ Woden requires Java 1.4 or higher.
+ </p>
+
+ </section>
+
+ <!-- ================================================================ -->
+ <section>
+ <title>Getting Started</title>
+ <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 <code>WSDLFactory</code> object which is then used to obtain
+ a <code>WSDLReader</code> 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 <code>DescriptionElement</code> object.
+ The <code>DescriptionElement</code> represents the WSDL <description> 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.
+ The <em>toComponent</em> method on <code>DescriptionElement</code> returns the WSDL as a
+ <code>Description</code> object, which represents the Description component from the WSDL 2.0
+ Component model. The API declared by <code>Description</code> and its contained objects will be
+ referred to as the <strong>Component</strong> API.
+ </p><source>
+ WSDLFactory factory = WSDLFactory.newInstance();
+ WSDLReader reader = factory.newWSDLReader();
+ reader.setFeature(WSDLReader.FEATURE_VALIDATION, true);
+ DescriptionElement descElem = reader.readWSDL(wsdlurl); <-- the <description> element
+ Description descComp = descElem.toComponent(); <-- the Description component</source>
+
+ <p>
+ The parameter <code>wsdlurl</code> is the String representation of a URL, e.g.:
+ </p><source>
+ wsdlurl="http://ws.org.apache/woden/services/Booking.wsdl"
+ wsdlurl="C:/woden/services/Booking.wsdl"</source>
+
+ <p>
+ To obtain the top-level WSDL elements from the <code>DescriptionElement</code>:
+ </p><source>
+ InterfaceElement[] interfaces = descElem.getInterfaceElements();
+ BindingElement[] bindings = descElem.getBindingElements();
+ ServiceElement[] services = descElem.getServiceElements();</source>
+
+ <p>
+ This example shows how to get the global schema element declaration (represented by the
+ <code>XmlSchemaElement</code> class from Apache ws-commons XmlSchema) which is referred to by
+ QName in the 'element' attribute of the interface <fault> element:
+ </p><source>
+ InterfaceElement interfaceElem = interfaces[0];
+ InterfaceFaultElement[] faults = interfaceElem.getInterfaceFaultElements();
+ XmlSchemaElement xsElem = faults[0].getElement();</source>
+
+ <p>
+ Where the WSDL is composed of multiple WSDL documents via WSDL <import> and
+ <include>, you can navigate the WSDL modules using the methods
+ <em>getImportElements</em> and <em>getIncludeElements</em> of <code>DescriptionElement</code>:
+ </p><source>
+ ImportElement[] imports = descElem.getImportElements();
+ DescriptionElement importedDescElem = imports[0].getDescriptionElement();</source>
+
+ <p>
+ The <code>Description</code> component also has methods to retrieve the top-level WSDL components,
+ but unlike those in <code>DescriptionElement</code>, 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><source>
+ Interface[] allInterfaces = descComp.getInterfaces();
+ Binding[] allBindings = descComp.getBindings();
+ Service[] allServices = descComp.getServices();</source>
+
+ <p>
+ The next example shows how to get all of the <code>ElementDeclaration</code> and <code>TypeDefinition</code>
+ components from the <code>Description</code> component. These represent the global schema element
+ declarations and type definitions from the XML Schemas defined in-line or imported within the WSDL
+ <types> 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><source>
+ ElementDeclaration[] elemDecls = descComp.getElementDeclarations();
+ TypeDefinition[] typeDefs = descComp.getTypeDefinitions();</source>
+
+ </section>
+
+ <!-- ================================================================ -->
+ <section>
+ <title>The Woden API</title>
+
+ <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 <code>org.apache.woden</code>.
+ Woden implementation package names begin with <code>org.apache.woden.internal</code>
+ to distinguish them from the API packages. All other <code>org.apache.woden</code>
+ packages are part of the Woden API.
+ </p>
+ <p>
+ The most important API packages are:
+ </p>
+ <p>
+ <code>org.apache.woden</code><br/>
+ This contains the core components of the Woden WSDL processor - WSDLFactory, WSDLReader,
+ WSDLException, ErrorReporter, ErrorHandler to name a few.
+ </p>
+
+ <p>
+ <code>org.apache.woden.schema</code><br/>
+ This contains interfaces representing both in-lined and imported XML schemas. These
+ represent schemas in terms of the <xs:schema> and <xs:import> elements
+ that can appear directly under the WSDL <types> element.
+ </p>
+
+ <p>
+ <code>org.apache.woden.wsdl20.extensions</code><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>
+ <code>org.apache.woden.wsdl20.extensions.soap</code><br/>
+ This contains Java classes that map to the SOAP binding extensions defined in the WSDL 2.0 spec.
+ </p>
+
+ <p>
+ <code>org.apache.woden.wsdl20</code><br/>
+ Contains the Java interfaces that make up the <strong>Component</strong> API (i.e. the abstract WSDL
+ Component model).
+ </p>
+
+ <p>
+ <code>org.apache.woden.wsdl20.xml</code><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 <code>WSDLReader</code>.
+ </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 <code>WSDLFactory</code> 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
+ <code>WSDLReader</code>, <code>DescriptionElement</code> and <code>ExtensionRegistry</code>.
+ </p>
+ <p>
+ The Woden parsing behaviour can be configured by setting features or properties of the
+ <code>WSDLReader</code> 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
+ <code>public static final</code> constants on the <code>WSDLReader</code> 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/>
+ <code>reader.setFeature(WSDLReader.FEATURE_VALIDATION, true);</code>
+ </p>
+ <p>
+ The API provides error handling through four interfaces and the <code>WSDLException</code> class.
+ System configuration errors are typically handled by throwing a <code>WSDLException</code>
+ containing appropriate error information.
+ WSDL parsing errors are reported by the <code>ErrorReporter</code> which delegates the
+ reporting style to the <code>ErrorHandler</code>.
+ <code>ErrorHandler</code> 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 <code>System.out</code> and then for fatal errors only, terminates processing with a
+ <code>WSDLException</code>.
+ Users may provide their own implementation of <code>ErrorHandler</code> to change this
+ behaviour.
+ The <em>setErrorHandler</em> method on <code>ErrorReporter</code> is used to set a
+ user-defined custom error handler.
+ User-defined extensions to Woden may use <code>ErrorReporter</code> to report their errors
+ via the <code>ErrorHandler</code> 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.
+ <code>ErrorInfo</code> declares a data object containing the error information
+ passed to the <code>ErrorHandler</code>.
+ This includes the <code>ErrorLocator</code> 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 <code>ExtensionDeserializer</code> and <code>ExtensionSerializer</code> interfaces will
+ map the element to/from some user-defined implementation of <code>ExtensionElement</code>
+ which represents the element.
+ The deserializer, serializer and Java mapping classes are registered in the
+ <code>ExtensionRegistry</code> so that the <code>WSDLReader</code> (or WSDLWriter when it gets
+ implemented) will know what to do when it encounters this element.
+ The Woden API includes <code>ExtensionElement</code> 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
+ <code>UnknownDeserializer</code>, <code>UnknownSerializer</code> and <code>UnknownExtensionElement</code> classes.
+ These Woden-defined extensions (SOAP and Unknown) are pre-registered in the <code>ExtensionRegistry</code>
+ by the Woden implementation.
+ </p>
+ <p>
+ The package <code>org.apache.woden.xml</code> contains classes that represent the more common
+ types of extension attribute values (e.g. string, QName, boolean, etc). These are all subclasses of
+ <code>XMLAttr</code> 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 <code>XMLAttr</code>
+ to support other types of values. The <code>XMLAttr</code> subclass must be registered with its parent
+ class name (i.e. its containing element) and the QName of the extension attribute in the
+ <code>ExtensionRegistry</code>, so that the <code>WSDLReader</code> 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 <code>ExtensionRegistry</code> using the
+ <code>XMLAttr</code> subclasses defined in package <code>org.apache.woden.xml</code>.
+ </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, <code>DescriptionElement</code>
+ declares methods <em>getInterfaceElements</em>, <em>getBindingElements</em> and
+ <em>getServiceElements</em> which provide access to the top-level WSDL elements.
+ <code>InterfaceElement</code> 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 <code>org.apache.woden.wsdl20.xml</code> 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, <code>DescriptionElement</code> 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 <service> elements
+ defined directly within the containing <description> element, but not
+ those defined within any imported or included descriptions. To retrieve all of the
+ <code>ServiceElement</code>s from a composite WSDL, you need to navigate the WSDL structure
+ using the <em>getImportElements</em> or <em>getIncludeElements</em> methods on
+ <code>DescriptionElement</code>.
+ </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 <documentation> element is not captured in the Component model.
+ The <types> element and particular type systems like XML Schema
+ are not represented, however the Component API does contain <code>ElementDeclaration</code>
+ and <code>TypeDefinition</code> 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 <import> and <include> 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 <code>Description</code> 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 <code>Description</code> object is by calling the <em>toComponent</em> method
+ on a <code>DescriptionElement</code> object. Once you have a <code>Description</code> 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>
+ <source>
+ WSDL element Element API Component API
+
+ <description> DescriptionElement Description
+ <documentation> DocumentationElement
+ <import> ImportElement
+ <include> IncludeElement
+ <types> TypesElement
+ <interface> InterfaceElement Interface
+ <fault> InterfaceFaultElement InterfaceFault
+ <operation> InterfaceOperationElement InterfaceOperation
+ <input> InterfaceMessageReferenceElement InterfaceMessageReference
+ <output> InterfaceMessageReferenceElement InterfaceMessageReference
+ <infault> FaultReferenceElement InterfaceFaultReference
+ <outfault> FaultReferenceElement InterfaceFaultReference
+ <binding> BindingElement Binding
+ <fault> BindingFaultElement BindingFault
+ <operation> BindingOperationElement BindingOperation
+ <input> BindingMessageReferenceElement BindingMessageReference
+ <output> BindingMessageReferenceElement BindingMessageReference
+ <infault> FaultReferenceElement BindingFaultReference
+ <outfault> FaultReferenceElement BindingFaultReference
+ <service> ServiceElement Service
+ <endpoint> EndpointElement Endpoint
+ <feature> FeatureElement Feature
+ <property> PropertyElement Property
+
+ XML Schema element
+
+ <xs:import> ImportedSchema
+ <xs:schema> InlinedSchema
+ <xs:element name=".."> ElementDeclaration
+ <xs:complexType name=".."> TypeDefinition
+ </source>
+
+ </section>
+
+ <!-- ================================================================ -->
+ <section>
+ <title>More topics to be added...</title>
+ <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>
+
+<!--
+ <p>
+ A custom error handler can also be specified as follows:
+ </p>
+ <source>
+ DescriptionElement desc = reader.readWSDL(wsdlLoc, handler);
+ </source>
+-->
+
+
+ </section>
+
+ </body>
+</document>
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: woden-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: woden-dev-help@ws.apache.org