- From: Arthur Ryman via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 16 Jun 2005 00:34:49 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv9328/wsdl20
Modified Files:
wsdldefs.xsl wsdl20-primer.xml wsdl20.tex component-table.xml
wsdl20-z-ie.html wsdl20-z.html wsdl20.html
wsdl20-adjuncts.html build.xml wsdl20-primer.html
Added Files:
wsdl20-defs.xml specs2defs.xsl wsdl20-specs.xml
Log Message:
Fixes for my "Comments on Primer Sections 1 - 3"
Index: wsdl20-adjuncts.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-adjuncts.html,v
retrieving revision 1.43
retrieving revision 1.44
diff -C2 -d -r1.43 -r1.44
*** wsdl20-adjuncts.html 14 Jun 2005 18:49:13 -0000 1.43
--- wsdl20-adjuncts.html 16 Jun 2005 00:34:47 -0000 1.44
***************
*** 1,15 ****
! <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
! "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
! <html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
! <head>
! <meta name="generator" content=
! "HTML Tidy for Linux/x86 (vers 1st February 2005), see www.w3.org" />
! <meta http-equiv="Content-Type" content=
! "text/html; charset=utf-8" />
! <title>Web Services Description Language (WSDL) Version 2.0 Part 2:
! Adjuncts</title>
[...12141 lines suppressed...]
! <td rowspan="1" colspan="1">JJM</td>
! <td rowspan="1" colspan="1">Simplified the introduction; referred to Part1 for a longer introduction</td>
! </tr>
! <tr>
! <td rowspan="1" colspan="1">20020221</td>
! <td rowspan="1" colspan="1">JJM</td>
! <td rowspan="1" colspan="1">Renamed to "Part 2: Bindings"</td>
! </tr>
! <tr>
! <td rowspan="1" colspan="1">20020221</td>
! <td rowspan="1" colspan="1">JJM</td>
! <td rowspan="1" colspan="1">Created from http://www.w3.org/TR/2001/NOTE-wsdl-20010315</td>
! </tr>
! </tbody>
! </table><br>
! </div>
! </div>
! </div>
! </body></html>
\ No newline at end of file
Index: build.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/build.xml,v
retrieving revision 1.22
retrieving revision 1.23
diff -C2 -d -r1.22 -r1.23
*** build.xml 10 Jun 2005 13:37:08 -0000 1.22
--- build.xml 16 Jun 2005 00:34:47 -0000 1.23
***************
*** 25,29 ****
<!--
! ChangeLog:
2005-06-10: Arthur Ryman <ryman@ca.ibm.com>
--- 25,33 ----
<!--
! Change Log:
!
! 2005-06-15: Arthur Ryman <ryman@ca.ibm.com>
! - added support for inter-document component
! and property references
2005-06-10: Arthur Ryman <ryman@ca.ibm.com>
***************
*** 97,100 ****
--- 101,105 ----
<target name="clean" description="Deletes generated files.">
<delete file="component-table.xml" />
+ <delete file="wsdl20-defs.xml" />
<delete file="wsdl20.pdf" />
<delete file="wsdl20.tex" />
***************
*** 109,112 ****
--- 114,124 ----
</target>
+ <target name="defs" description="Generates component and property definitions.">
+ <xslt in="wsdl20-specs.xml" out="wsdl20-defs.xml" style="specs2defs.xsl" force="yes"/>
+ <xmlvalidate lenient="true">
+ <fileset dir="." includes="wsdl20-defs.xml" />
+ </xmlvalidate>
+ </target>
+
<target name="component-table" description="Generates component table.">
<touch file="component-table.xml" />
***************
*** 116,120 ****
</xmlvalidate>
</target>
-
<target name="validate" description="Validates all XML and XSL files.">
<xmlvalidate lenient="true">
--- 128,131 ----
***************
*** 122,126 ****
</xmlvalidate>
<xmlvalidate lenient="false">
! <fileset dir="." includes="wsdl20*.xml" />
</xmlvalidate>
</target>
--- 133,137 ----
</xmlvalidate>
<xmlvalidate lenient="false">
! <fileset dir="." includes="wsdl20*.xml" excludes="wsdl20-defs.xml, wsdl20-specs.xml"/>
</xmlvalidate>
</target>
***************
*** 164,168 ****
</target>
! <target name="html" depends="component-table" description="Transforms xml into html.">
<xslt in="wsdl20.xml" out="wsdl20.html" style="xmlspec-wsdl.xsl" />
<xslt in="wsdl20-adjuncts.xml" out="wsdl20-adjuncts.html" style="xmlspec-wsdl.xsl" />
--- 175,179 ----
</target>
! <target name="html" depends="component-table, defs" description="Transforms xml into html.">
<xslt in="wsdl20.xml" out="wsdl20.html" style="xmlspec-wsdl.xsl" />
<xslt in="wsdl20-adjuncts.xml" out="wsdl20-adjuncts.html" style="xmlspec-wsdl.xsl" />
Index: wsdl20-z-ie.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-z-ie.html,v
retrieving revision 1.23
retrieving revision 1.24
diff -C2 -d -r1.23 -r1.24
*** wsdl20-z-ie.html 12 Jun 2005 22:14:42 -0000 1.23
--- wsdl20-z-ie.html 16 Jun 2005 00:34:47 -0000 1.24
***************
*** 68,72 ****
be used to describe Web services based on an abstract model of
what the service offers.
! It also defines criteria for a conformant processor of this language.
</p>
</div><div>
--- 68,72 ----
be used to describe Web services based on an abstract model of
what the service offers.
! It also defines the conformance criteria for documents in this language.
</p>
[...11421 lines suppressed...]
</tr>
<tr>
<td rowspan="1" colspan="1">20030303</td>
<td rowspan="1" colspan="1">MJG</td>
! <td rowspan="1" colspan="1">Skeleton Feature and <a href="wsdl20.html#component-Property">Property</a> components</td>
</tr>
***************
*** 13185,13189 ****
<td rowspan="1" colspan="1">20030118</td>
<td rowspan="1" colspan="1">MJG</td>
! <td rowspan="1" colspan="1">Removed {extension} properties from <a href="#component-Binding">Binding</a> components and
Port components. Added text relating to how extension elements
are expected to annotate the component model.</td>
--- 13044,13048 ----
<td rowspan="1" colspan="1">20030118</td>
<td rowspan="1" colspan="1">MJG</td>
! <td rowspan="1" colspan="1">Removed {extension} properties from <a href="wsdl20.html#component-Binding">Binding</a> components and
Port components. Added text relating to how extension elements
are expected to annotate the component model.</td>
Index: wsdl20.tex
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20.tex,v
retrieving revision 1.55
retrieving revision 1.56
diff -C2 -d -r1.55 -r1.56
*** wsdl20.tex 12 Jun 2005 22:14:42 -0000 1.55
--- wsdl20.tex 16 Jun 2005 00:34:47 -0000 1.56
***************
*** 66,70 ****
be used to describe Web services based on an abstract model of
what the service offers.
! It also defines criteria for a conformant processor of this language.
\end{abstract}
--- 66,70 ----
be used to describe Web services based on an abstract model of
what the service offers.
! It also defines the conformance criteria for documents in this language.
[...2175 lines suppressed...]
Incorporated Paul's words for issue 235
\\ \hline
+
20040727&
***************
*** 14110,14115 ****
20030428&
MJG&
! Various edits to \hyperlink{eii-types}{\textbf{\ref*{eii-types} Types}}, \hyperlink{other-schemalang}{\textbf{\ref*{other-schemalang} Examples of Specifications of Extension Elements for Alternative Schema
! Language Support.}} to accommodate other type systems and
spell out how extensibility elements/attributes play out in such
scenarios.
--- 13959,13964 ----
20030428&
MJG&
! Various edits to \hyperlink{eii-types}{\textbf{\ref*{eii-types} Types}}, other-schemalang
! to accommodate other type systems and
spell out how extensibility elements/attributes play out in such
scenarios.
--- NEW FILE: wsdl20-specs.xml ---
<?xml version="1.0"?>
<!--
This file lists the WSDL 2.0 specifications that contain
component and property definitions. It is used to
generate a list of all definitions to support inter-document
references.
Change Log:
2005-06-15: Arthur Ryman <ryman@ca.ibm.com>
- created
-->
<specs>
<spec src="wsdl20.xml" />
<spec src="wsdl20-adjuncts.xml" />
</specs>
--- NEW FILE: specs2defs.xsl ---
<?xml version="1.0" encoding="UTF-8"?>
<!--
This stylesheet generates a list of component and
property definitions from a list of specifications.
Change Log:
2005-06-15: Arthur Ryman <ryman@ca.ibm.com>
- created
-->
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="xml" version="1.0" encoding="UTF-8" indent="yes"/>
<xsl:template match="/specs">
<defs>
<xsl:apply-templates />
</defs>
</xsl:template>
<xsl:template match="spec">
<spec src="{@src}">
<xsl:apply-templates select="document(@src)//compdef" />
<xsl:apply-templates select="document(@src)//propdef" />
</spec>
</xsl:template>
<xsl:template match="compdef">
<compdef comp="{normalize-space(.)}" />
</xsl:template>
<xsl:template match="propdef">
<propdef comp="{@comp}" prop="{normalize-space(.)}" />
</xsl:template>
</xsl:stylesheet>
Index: component-table.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/component-table.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** component-table.xml 12 Jun 2005 22:14:42 -0000 1.2
--- component-table.xml 16 Jun 2005 00:34:47 -0000 1.3
***************
*** 142,146 ****
</td>
<td>
! <prop comp="Feature">uri</prop>
,
<prop comp="Feature">required</prop>
--- 142,146 ----
</td>
<td>
! <prop comp="Feature">ref</prop>
,
<prop comp="Feature">required</prop>
***************
*** 154,166 ****
</td>
<td>
! <prop comp="Property">uri</prop>
! ,
! <prop comp="Property">value constraint</prop>
! ,
! <prop comp="Property">value</prop>
! ,
! <prop comp="Property">parent</prop>
! ,
! <prop comp="Property">uri</prop>
,
<prop comp="Property">value constraint</prop>
--- 154,158 ----
</td>
<td>
! <prop comp="Property">ref</prop>
,
<prop comp="Property">value constraint</prop>
Index: wsdl20-z.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-z.html,v
retrieving revision 1.43
retrieving revision 1.44
diff -C2 -d -r1.43 -r1.44
*** wsdl20-z.html 15 Jun 2005 22:33:09 -0000 1.43
--- wsdl20-z.html 16 Jun 2005 00:34:47 -0000 1.44
***************
*** 1,13 ****
! <?xml version="1.0" encoding="utf-8"?>
! <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
! <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
! <head><meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="HTML Tidy for Linux/x86 (vers 1st February 2005), see www.w3.org" />
!
! <title>Web Services Description Language (WSDL) Version 2.0 Part 1:
! Core Language</title>
!
! <style type="text/css">
[...28470 lines suppressed...]
! <tr>
! <td rowspan="1" colspan="1">20020620</td>
! <td rowspan="1" colspan="1">SW</td>
! <td rowspan="1" colspan="1">Started adding abstract model</td>
! </tr>
! <tr>
! <td rowspan="1" colspan="1">20020406</td>
! <td rowspan="1" colspan="1">SW</td>
! <td rowspan="1" colspan="1">Created document from WSDL 1.1</td>
! </tr>
! </tbody>
! </table><br>
!
! </div>
! </div>
!
! </div>
!
! </body></html>
\ No newline at end of file
Index: wsdldefs.xsl
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdldefs.xsl,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** wsdldefs.xsl 12 Jun 2005 22:14:42 -0000 1.2
--- wsdldefs.xsl 16 Jun 2005 00:34:46 -0000 1.3
***************
*** 14,17 ****
--- 14,20 ----
Change Log:
+ 2005-06-15: Arthur Ryman <ryman@ca.ibm.com>
+ - added support for inter-document links
+
2005-06-12: Arthur Ryman <ryman@ca.ibm.com>
- normalize space in component and property names
***************
*** 63,81 ****
to:
! <a href="#InterfaceOperation-component">Interface Operation</a>
-->
<xsl:template match="comp">
<xsl:variable name="anchor">
<xsl:call-template name="component-anchor">
! <xsl:with-param name="component" select="." />
</xsl:call-template>
</xsl:variable>
! <a href="#{$anchor}">
! <xsl:value-of select="normalize-space()" />
</a>
</xsl:template>
<xsl:template name="component-anchor">
<xsl:param name="component" />
--- 66,103 ----
to:
! <a href="wsdl20.html#component-InterfaceOperation">Interface Operation</a>
-->
<xsl:template match="comp">
+ <xsl:variable name="component" select="normalize-space()"/>
+ <xsl:variable name="src">
+ <xsl:call-template name="component-src">
+ <xsl:with-param name="component" select="$component"/>
+ </xsl:call-template>
+ </xsl:variable>
<xsl:variable name="anchor">
<xsl:call-template name="component-anchor">
! <xsl:with-param name="component" select="$component" />
</xsl:call-template>
</xsl:variable>
! <a href="{$src}#{$anchor}">
! <xsl:value-of select="$component" />
</a>
</xsl:template>
+ <xsl:template name="component-src">
+ <xsl:param name="component"/>
+ <xsl:variable name="src" select="document('wsdl20-defs.xml')/defs/spec/compdef[@comp=$component]/../@src"/>
+ <xsl:call-template name="map-src">
+ <xsl:with-param name="src" select="$src"/>
+ </xsl:call-template>
+ </xsl:template>
+
+ <xsl:template name="map-src">
+ <xsl:param name="src"/>
+ <xsl:value-of select="concat(substring-before($src,'.xml'),'.html')"/>
+ </xsl:template>
+
<xsl:template name="component-anchor">
<xsl:param name="component" />
***************
*** 138,154 ****
<xsl:template match="prop">
<xsl:variable name="anchor">
<xsl:call-template name="property-anchor">
! <xsl:with-param name="component" select="@comp" />
! <xsl:with-param name="property" select="." />
</xsl:call-template>
</xsl:variable>
<xsl:text>{</xsl:text>
! <a href="#{$anchor}">
! <xsl:value-of select="normalize-space()" />
</a>
<xsl:text>}</xsl:text>
</xsl:template>
<xsl:template name="property-anchor">
<xsl:param name="component" />
--- 160,193 ----
<xsl:template match="prop">
+ <xsl:variable name="property" select="normalize-space()" />
+ <xsl:variable name="component" select="@comp" />
+ <xsl:variable name="src">
+ <xsl:call-template name="property-src">
+ <xsl:with-param name="component" select="$component" />
+ <xsl:with-param name="property" select="$property" />
+ </xsl:call-template>
+ </xsl:variable>
<xsl:variable name="anchor">
<xsl:call-template name="property-anchor">
! <xsl:with-param name="component" select="$component" />
! <xsl:with-param name="property" select="$property" />
</xsl:call-template>
</xsl:variable>
<xsl:text>{</xsl:text>
! <a href="{$src}#{$anchor}">
! <xsl:value-of select="$property" />
</a>
<xsl:text>}</xsl:text>
</xsl:template>
+ <xsl:template name="property-src">
+ <xsl:param name="component" />
+ <xsl:param name="property" />
+ <xsl:variable name="src" select="document('wsdl20-defs.xml')/defs/spec/propdef[@comp=$component][@prop=$property]/../@src"/>
+ <xsl:call-template name="map-src">
+ <xsl:with-param name="src" select="$src"/>
+ </xsl:call-template>
+ </xsl:template>
+
<xsl:template name="property-anchor">
<xsl:param name="component" />
--- NEW FILE: wsdl20-defs.xml ---
<?xml version="1.0" encoding="UTF-8"?>
<defs>
<spec src="wsdl20.xml">
<compdef comp="Element Declaration"/>
<compdef comp="Type Definition"/>
<compdef comp="Description"/>
<compdef comp="Interface"/>
<compdef comp="Interface Fault"/>
<compdef comp="Interface Operation"/>
<compdef comp="Interface Message Reference"/>
<compdef comp="Interface Fault Reference"/>
<compdef comp="Feature"/>
<compdef comp="Property"/>
<compdef comp="Binding"/>
<compdef comp="Binding Fault"/>
<compdef comp="Binding Operation"/>
<compdef comp="Binding Message Reference"/>
<compdef comp="Binding Fault Reference"/>
<compdef comp="Service"/>
<compdef comp="Endpoint"/>
<propdef prop="name" comp="Element Declaration"/>
<propdef prop="name" comp="Type Definition"/>
<propdef prop="parent" comp=""/>
<propdef prop="interfaces" comp="Description"/>
<propdef prop="bindings" comp="Description"/>
<propdef prop="services" comp="Description"/>
<propdef prop="element declarations" comp="Description"/>
<propdef prop="type definitions" comp="Description"/>
<propdef prop="name" comp="Interface"/>
<propdef prop="extended interfaces" comp="Interface"/>
<propdef prop="interface faults" comp="Interface"/>
<propdef prop="interface operations" comp="Interface"/>
<propdef prop="features" comp="Interface"/>
<propdef prop="properties" comp="Interface"/>
<propdef prop="name" comp="Interface Fault"/>
<propdef prop="element declaration" comp="Interface Fault"/>
<propdef prop="features" comp="Interface Fault"/>
<propdef prop="properties" comp="Interface Fault"/>
<propdef prop="parent" comp="Interface Fault"/>
<propdef prop="name" comp="Interface Operation"/>
<propdef prop="message exchange pattern" comp="Interface Operation"/>
<propdef prop="interface message references" comp="Interface Operation"/>
<propdef prop="interface fault references" comp="Interface Operation"/>
<propdef prop="style" comp="Interface Operation"/>
<propdef prop="features" comp="Interface Operation"/>
<propdef prop="properties" comp="Interface Operation"/>
<propdef prop="parent" comp="Interface Operation"/>
<propdef prop="message label" comp="Interface Message Reference"/>
<propdef prop="direction" comp="Interface Message Reference"/>
<propdef prop="message content model" comp="Interface Message Reference"/>
<propdef prop="element declaration" comp="Interface Message Reference"/>
<propdef prop="features" comp="Interface Message Reference"/>
<propdef prop="properties" comp="Interface Message Reference"/>
<propdef prop="parent" comp="Interface Message Reference"/>
<propdef prop="interface fault" comp="Interface Fault Reference"/>
<propdef prop="message label" comp="Interface Fault Reference"/>
<propdef prop="direction" comp="Interface Fault Reference"/>
<propdef prop="features" comp="Interface Fault Reference"/>
<propdef prop="properties" comp="Interface Fault Reference"/>
<propdef prop="parent" comp="Interface Fault Reference"/>
<propdef prop="ref" comp="Feature"/>
<propdef prop="required" comp="Feature"/>
<propdef prop="parent" comp="Feature"/>
<propdef prop="features" comp=""/>
<propdef prop="ref" comp="Property"/>
<propdef prop="value constraint" comp="Property"/>
<propdef prop="value" comp="Property"/>
<propdef prop="parent" comp="Property"/>
<propdef prop="properties" comp=""/>
<propdef prop="name" comp="Binding"/>
<propdef prop="interface" comp="Binding"/>
<propdef prop="type" comp="Binding"/>
<propdef prop="binding faults" comp="Binding"/>
<propdef prop="binding operations" comp="Binding"/>
<propdef prop="features" comp="Binding"/>
<propdef prop="properties" comp="Binding"/>
<propdef prop="interface fault" comp="Binding Fault"/>
<propdef prop="features" comp="Binding Fault"/>
<propdef prop="properties" comp="Binding Fault"/>
<propdef prop="parent" comp="Binding Fault"/>
<propdef prop="interface operation" comp="Binding Operation"/>
<propdef prop="binding message references" comp="Binding Operation"/>
<propdef prop="binding fault references" comp="Binding Operation"/>
<propdef prop="features" comp="Binding Operation"/>
<propdef prop="properties" comp="Binding Operation"/>
<propdef prop="parent" comp="Binding Operation"/>
<propdef prop="interface message reference" comp="Binding Message Reference"/>
<propdef prop="features" comp="Binding Message Reference"/>
<propdef prop="properties" comp="Binding Message Reference"/>
<propdef prop="parent" comp="Binding Message Reference"/>
<propdef prop="interface fault reference" comp="Binding Fault Reference"/>
<propdef prop="features" comp="Binding Fault Reference"/>
<propdef prop="properties" comp="Binding Fault Reference"/>
<propdef prop="parent" comp="Binding Fault Reference"/>
<propdef prop="name" comp="Service"/>
<propdef prop="interface" comp="Service"/>
<propdef prop="endpoints" comp="Service"/>
<propdef prop="features" comp="Service"/>
<propdef prop="properties" comp="Service"/>
<propdef prop="name" comp="Endpoint"/>
<propdef prop="binding" comp="Endpoint"/>
<propdef prop="address" comp="Endpoint"/>
<propdef prop="features" comp="Endpoint"/>
<propdef prop="properties" comp="Endpoint"/>
<propdef prop="parent" comp="Endpoint"/>
<propdef prop="name" comp=""/>
</spec>
<spec src="wsdl20-adjuncts.xml">
<compdef comp="SOAP Module"/>
<compdef comp="SOAP Header Block"/>
<compdef comp="HTTP Header"/>
<propdef prop="safety" comp="Interface Operation"/>
<propdef prop="rpc-signature" comp="Interface Operation"/>
<propdef prop="soap version" comp="Binding"/>
<propdef prop="soap underlying protocol" comp="Binding"/>
<propdef prop="soap fault code" comp="Binding Fault"/>
<propdef prop="soap fault subcodes" comp="Binding Fault"/>
<propdef prop="soap mep" comp="Binding Operation"/>
<propdef prop="soap action" comp="Binding Operation"/>
<propdef prop="soap modules" comp="Binding"/>
<propdef prop="ref" comp="SOAP Module"/>
<propdef prop="required" comp="SOAP Module"/>
<propdef prop="soap headers" comp="Binding Message Reference"/>
<propdef prop="element" comp="SOAP Header Block"/>
<propdef prop="mustUnderstand" comp="SOAP Header Block"/>
<propdef prop="http version" comp="Binding"/>
<propdef prop="http location" comp="Binding Operation"/>
<propdef prop="http method" comp="Binding Operation"/>
<propdef prop="http input serialization" comp="Binding Operation"/>
<propdef prop="http output serialization" comp="Binding Operation"/>
<propdef prop="http fault serialization" comp="Binding Operation"/>
<propdef prop="http query parameter separator" comp="Binding Operation"/>
<propdef prop="http headers" comp="Binding Message Reference"/>
<propdef prop="element" comp="HTTP Header"/>
<propdef prop="http error status code" comp="Binding Fault"/>
<propdef prop="http error reason phrase" comp="Binding Fault"/>
<propdef prop="http transfer coding" comp="Binding Message Reference"/>
<propdef prop="http cookies" comp="Binding"/>
<propdef prop="http authentication scheme" comp="Endpoint"/>
<propdef prop="http authentication realm" comp="Endpoint"/>
</spec>
</defs>
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.95
retrieving revision 1.96
diff -C2 -d -r1.95 -r1.96
*** wsdl20-primer.xml 15 Jun 2005 22:03:06 -0000 1.95
--- wsdl20-primer.xml 16 Jun 2005 00:34:46 -0000 1.96
***************
*** 105,111 ****
</div2><div2 id="notation">
<head>Notational Conventions</head>
- <p>The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
- this document are to be interpreted as described in RFC 2119.</p>
<p>This document uses several XML namespaces, some of which are defined by standards, and some are application-specific. Namespace names of the general form
<attval>http://greath.example.com/...</attval> represent application or
--- 105,108 ----
***************
*** 210,215 ****
! </div2><div2 id="basics-getting-started"><head>Getting Started: Defining a WSDL Target Namespace</head><p>Before writing our WSDL 2.0 document, we need to decide on a <emph>WSDL target namespace</emph> URI for it. The WSDL target namespace is analogous to an XML Schema target namespace. Interface, binding and service names that we define in our WSDL document will be associated with the WSDL target namespace, and thus will be distinguishable from similar names in a different WSDL target namespace. (This will become important if using WSDL 2.0's import or interface inheritance mechanisms.) </p><p>The value of the WSDL target namespace must be an absolute URI. Furthermore, it should be dereferenceable to a WSDL 2.0 document that describes the Web service that the WSDL target namespace is used to describe. For example, the GreatH owners should make the WSDL document available from this URI. (And if a WSDL description is split into multiple documents, then the WSDL target namespace should resolve to a aster document that includes all the WSDL documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable, so a WSDL processor must not depend on it being dereferenceable. </p><p>This recommendation may sound circular, but bear in mind that the client might have obtained the WSDL document from anywhere -- not necessarily an authoritative source. But by dereferencing the WSDL target namespace URI, a user should be able to obtain an authoritative version. Since GreatH will be the owner of the service, the WSDL target namespace URI should refer to a location on the GreatH Web site or otherwise within its control.</p><p>Once we have decided on a WSDL target namespace URI, we can begin our WSDL 2.0 document as the following empty shell.</p><example id="example-empty-shell">
! <head>An Initial Empty WSDL 2.0 Document</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
<description
--- 207,212 ----
! </div2><div2 id="basics-getting-started"><head>Getting Started: Defining a WSDL 2.0 Target Namespace</head><p>Before writing our WSDL 2.0 document, we need to decide on a <emph>WSDL 2.0 target namespace</emph> URI for it. The WSDL 2.0 target namespace is analogous to an XML Schema target namespace. Interface, binding and service names that we define in our WSDL 2.0 document will be associated with the WSDL 2.0 target namespace, and thus will be distinguishable from similar names in a different WSDL 2.0 target namespace. (This will become important if using WSDL 2.0's import or interface inheritance mechanisms.) </p><p>The value of the WSDL 2.0 target namespace must be an absolute URI. Furthermore, it should be dereferenceable to a WSDL 2.0 document that describes the Web service that the WSDL 2.0 target namespace is used to describe. For example, the GreatH owners should make the WSDL 2.0 document available from this URI. (And if a WSDL 2.0 description is split into multiple documents, then the WSL 2.0 target namespace should resolve to a master document that includes all the WSDL 2.0 documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable, so a WSDL 2.0 processor must not depend on it being dereferenceable. </p><p>This recommendation may sound circular, but bear in mind that the client might have obtained the WSDL 2.0 document from anywhere -- not necessarily an authoritative source. But by dereferencing the WSDL 2.0 target namespace URI, a user should be able to obtain an authoritative version. Since GreatH will be the owner of the service, the WSDL 2.0 target namespace URI should refer to a location on the GreatH Web site or otherwise within its control.</p><p>Once we have decided on a WSDL 2.0 target namespace URI, we can begin our WSDL 2.0 2.0 document as the following empty shell.</p><example id="example-empty-shell">
! <head>An Initial Empty WSDL 2.0 2.0 Document</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
<description
***************
*** 221,225 ****
. . .
</description>]]></eg>
! </example><div3 id="example-empty-shell-explanation"><head>Explanation of Example</head><p><glist><gitem><label><code><description</code></label><def><p>Every WSDL 2.0 document has a <code>description</code> element as its top-most element. This merely acts as a container for the rest of the WSDL 2.0 document, and is used to declare namespaces that will be used throughout the document.</p></def></gitem><gitem><label><code>xmlns="http://www.w3.org/2005/05/wsdl"</code></label><def><p>This is the XML namespace for WSDL 2.0 itself. Because we have not defined a prefix for it, any unprefixed elements or attributes are expected to be WSDL 2.0 elements or attributes (such as the <code>description</code> element).</p></def></gitem><gitem><label><code>targetNamespace= "http://greath.example.com/2004/wsdl/resSvc"</code></label><def><p>This defines the WSDL target namespace that we have chosen for the GreatH reservation service, as described above. Note that this is not an actual XML namespace declaration Rather, it is a WSDL 2.0 attribute whose purpose is <emph>analogous</emph> to an XML Schema target namespace.</p></def></gitem><gitem><label><code>xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc"</code></label><def><p>This is an actual XML namespace declaration for use in our GreatH service description. Note that this is the same URI that was specified above as the value of the <att>targetNamespace</att> attribute. This will allow us later to use the <code>tns:</code> prefix in QNames, to refer to the WSDL target namespace of the GreatH service. (For more on QNames see <bibref ref="XMLNS"/> section 3 <xspecref href="http://www.w3.org/TR/1999/REC-xml-names-19990114/#ns-qualnames">Qualified Names</xspecref>.)</p></def></gitem></glist></p><p> Now we can start describing the GreatH service. </p></div3></div2><div2 id="basics-types"><head>Defining Message Types</head><p>We know that the GreatH service will be sending and receiving messages, so a good starting point in describing the service s to define the message types that the service will use. We'll use XML Schema to do so, because WSDL 2.0 WSDL processors are likely to support XML Schema at a minimum. However, WSDL 2.0 does not prohibit the use of some other schema definition language.</p><p>WSDL 2.0 allows message types to be defined directly within the WSDL document, inside the <code>types</code> element, which is a child of the <code>description</code> element. (Later we'll see how we can provide the type definitions in a separate document, using XML Schema's <code>import</code> mechanism.) The following schema defines <code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code> message types that we'll need. </p><p>In WSDL 2.0, all normal and fault message types must be defined as single <emph>elements</emph> at the topmost level (though of course each element may have any amount of substructure inside it). Thus, a message type must not directly consist of a sequence of elements or oher complex type. </p><example id="example-initial-types">
<head>GreatH Message Types</head>
<eg><![CDATA[
--- 218,234 ----
. . .
</description>]]></eg>
! </example><div3 id="example-empty-shell-explanation"><head>Explanation of Example</head><p><glist><gitem><label><code><description</code></label><def><p>Every WSDL 2.0 2.0 document has a <code>description</code> element as its top-most element. This merely acts as a container for the rest of the WSDL 2.0 2.0 document, and is used to declare namespaces that will be used throughout the document.</p></def></gitem><gitem><label><code>xmlns="http://www.w3.org/2005/05/wsdl"</code></label>
! <def>
! <p>
! This is the XML namespace for WSDL 2.0 2.0 itself.
! Because we have not defined a prefix for it, any
! unprefixed elements are expected
! to be WSDL 2.0 2.0 elements (such as
! the
! <code>description</code>
! element).
! </p>
! </def>
! </gitem><gitem><label><code>targetNamespace= "http://greath.example.com/2004/wsdl/resSvc"</code></label><def><p>This defines the WSDL 2.0 target namespace that we have chosen for the GreatH reservation service, as described above. Note that this is not an actual XML namespace declaration. Rather, it is a WSDL 2.0 attribute whose purpose is <emph>analogous</emph> to an XML Schema target namespace.</p></def></gitem><gitem><label><code>xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc"</code></label><def><p>This is an actual XML namespace declaration for use in our GreatH service description. Note that this is the same URI that was specified above as the value of the <att>targetNamespace</att> attribute. This will allow us later to use the <code>tns:</code> prefix in QNames, to refer to the WSDL 2.0 target namespace of the GreatH service. (For more on QNames see <bibref ref="XMLNS"/> section 3 <xspecref href="http://www.w3.org/TR/1999/REC-xml-names-19990114/#ns-qualnames">Qualified Names</xsecref>.)</p></def></gitem></glist></p><p> Now we can start describing the GreatH service. </p></div3></div2><div2 id="basics-types"><head>Defining Message Types</head><p>We know that the GreatH service will be sending and receiving messages, so a good starting point in describing the service is to define the message types that the service will use. We'll use XML Schema to do so, because WSDL 2.0 processors are likely to support XML Schema at a minimum. However, WSDL 2.0 does not prohibit the use of some other schema definition language.</p><p>WSDL 2.0 allows message types to be defined directly within the WSDL 2.0 document, inside the <code>types</code> element, which is a child of the <code>description</code> element. (Later we'll see how we can provide the type definitions in a separate document, using XML Schema's <code>import</code> mechanism.) The following schema defines <code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code> message types thatwe'll need. </p><p>In WSDL 2.0, all normal and fault message types must be defined as single <emph>elements</emph> at the topmost level (though of course each element may have any amount of substructure inside it). Thus, a message type must not directly consist of a sequence of elements or other complex type. </p><example id="example-initial-types">
<head>GreatH Message Types</head>
<eg><![CDATA[
***************
*** 257,265 ****
. . .
</description>]]></eg>
! </example><div3 id="example-initial-types-explanation"><head>Explanation of Example</head><glist><gitem><label><code>xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc"</code></label><def><p>We've added another namespace declaration. The <code>ghns</code> namespace prefix will allow us (later, when defining an interface) to reference the XML Schema target namespace that we define for our message types. Thus, the URI we specify must be the same as the URI that we define as the target namespace of our XML Schema types (below) -- <emph>not</emph> the target namespace of the WSDL document itself.</p></def></gitem><gitem><label><code>targetNamespace="http://greath.example.com/2004/schemas/resSvc"</code></label><def><p>This is the XML Schema target namespace that we've created for use by the GreatH reservation service. The <code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code> element names will be associated with this XML Schema target namespae.</p></def></gitem><gitem><label><code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code></label><def><p>These are the message types that we'll use. Note that these are defined to be XML <emph>elements</emph>, as explained above.</p></def></gitem></glist><p>Although we have defined several types, we have not yet indicated which ones are to be used as message types for a Web service. We'll do that in the next section. </p></div3></div2>
! <div2 id="basics-interface"><head>Defining an Interface</head><p>WSDL 2.0 enables one to separate the description of a Web service's abstract functionality from the concrete details of how and where that functionality is offered. This separation facilitates different levels of reusability and distribution of work in the lifecycle of a Web service and the WSDL document that describes it. </p><p>A WSDL 2.0 <code>interface</code> defines the abstract interface of a Web service as a set of abstract <emph>operations</emph>, each operation representing a simple interaction between the client and the service. Each operation specifies the types of messages that the service can send or receive as part of that operation. Each operation also specifies a message exchange <emph>pattern</emph> that indicates the sequence in which the associated messages are to be transmitted between the parties. For example, the <emph>in-out</emph> pattern (see <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PAT2"/> section 2.2.3 <xspecref href="&w3c-designation-part2;#in-out">In-Out</xspecref>) indicates that if the client sends a message <emph>in</emph> to the service, the service will either send a reply message back <emph>out</emph> to the client (in the normal case) or it will send a fault message back to the client (in the case of an error). We will explain more about message exchange <emph>pattern</emph>s in <specref ref = "more-interfaces-meps"/></p>
! <p>For the GreatH service, we will (initially) define an interface containing a single operation, <code>opCheckAvailability</code>, using the <code>checkAvailability</code> and <code>checkAvailabilityResponse</code> message types that we defined in the <code>types</code> section. We'll use the <xspecref href="&w3c-designation-part2;#in-out">in-out</xspecref> pattern for this operation, because this is the most natural way to represent a simple request-response interaction. We could have instead (for example) defined two separate operations using the <xspecref href="&w3c-designation-part2;#in-out">in-only</xspecref> and <xspecref href="&w3c-designation-part2;#out-only">out-only</xspecref> patterns (see <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.2.1 <xspecref href="&w3c-designation-part2;#in-only">In-Only</xspecref> and section 2.2.5 <xspecref href="&w3c-designation-part2;#out-only">Out-Only</xspecref>), but that would just complicate matters for the client, bcause we would then have to separately indicate to the client developer that the two operations should be used together as a request-response pair.</p><p>In addition to the normal input and output messages, we also need to specify the fault message that we wish to use in the event of an error. WSDL 2.0 permits fault messages to be declared within the <code>interface</code> element in order to facilitate reuse of faults across operations. If a fault occurs, it terminates whatever message sequence was indicated by the message exchange pattern of the operation. </p><p>Let's add these to our WSDL document.</p><example id="example-initial-interface">
<head>GreatH Interface Definition</head>
--- 266,274 ----
. . .
</description>]]></eg>
! </example><div3 id="example-initial-types-explanation"><head>Explanation of Example</head><glist><gitem><label><code>xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc"</code></label><def><p>We've added another namespace declaration. The <code>ghns</code> namespace prefix will allow us (later, when defining an interface) to reference the XML Schema target namespace that we define for our message types. Thus, the URI we specify must be the same as the URI that we define as the target namespace of our XML Schema types (below) -- <emph>not</emph> the target namespace of the WSDL 2.0 document itself.</p></def></gitem><gitem><label><code>targetNamespace="http://greath.example.com/2004/schemas/resSvc"</code></label><def><p>This is the XML Schema target namespace that we've created for use by the GreatH reservation service. The <code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code> element names will be associated with this XML Schema target namspace.</p></def></gitem><gitem><label><code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code></label><def><p>These are the message types that we'll use. Note that these are defined to be XML <emph>elements</emph>, as explained above.</p></def></gitem></glist><p>Although we have defined several types, we have not yet indicated which ones are to be used as message types for a Web service. We'll do that in the next section. </p></div3></div2>
! <div2 id="basics-interface"><head>Defining an Interface</head><p>WSDL 2.0 enables one to separate the description of a Web service's abstract functionality from the concrete details of how and where that functionality is offered. This separation facilitates different levels of reusability and distribution of work in the lifecycle of a Web service and the WSDL 2.0 document that describes it. </p><p>A WSDL 2.0 <code>interface</code> defines the abstract interface of a Web service as a set of abstract <emph>operations</emph>, each operation representing a simple interaction between the client and the service. Each operation specifies the types of messages that the service can send or receive as part of that operation. Each operation also specifies a message exchange <emph>pattern</emph> that indicates the sequence in which the associated messages are to be transmitted between the parties. For example, the <emph>in-out</emph> pattern (see <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSD-PART2"/> section 2.2.3 <xspecref href="&w3c-designation-part2;#in-out">In-Out</xspecref>) indicates that if the client sends a message <emph>in</emph> to the service, the service will either send a reply message back <emph>out</emph> to the client (in the normal case) or it will send a fault message back to the client (in the case of an error). We will explain more about message exchange <emph>pattern</emph>s in <specref ref = "more-interfaces-meps"/></p>
! <p>For the GreatH service, we will (initially) define an interface containing a single operation, <code>opCheckAvailability</code>, using the <code>checkAvailability</code> and <code>checkAvailabilityResponse</code> message types that we defined in the <code>types</code> section. We'll use the <xspecref href="&w3c-designation-part2;#in-out">in-out</xspecref> pattern for this operation, because this is the most natural way to represent a simple request-response interaction. We could have instead (for example) defined two separate operations using the <xspecref href="&w3c-designation-part2;#in-out">in-only</xspecref> and <xspecref href="&w3c-designation-part2;#out-only">out-only</xspecref> patterns (see <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.2.1 <xspecref href="&w3c-designation-part2;#in-only">In-Only</xspecref> and section 2.2.5 <xspecref href="&w3c-designation-part2;#out-only">Out-Only</xspecref>), but that would just complicate matters for the client, bcause we would then have to separately indicate to the client developer that the two operations should be used together as a request-response pair.</p><p>In addition to the normal input and output messages, we also need to specify the fault message that we wish to use in the event of an error. WSDL 2.0 permits fault messages to be declared within the <code>interface</code> element in order to facilitate reuse of faults across operations. If a fault occurs, it terminates whatever message sequence was indicated by the message exchange pattern of the operation. </p><p>Let's add these to our WSDL 2.0 document.</p><example id="example-initial-interface">
<head>GreatH Interface Definition</head>
***************
*** 296,303 ****
. . .
! </description>]]></eg></example><div3 id="example-initial-interface-explanation"><head>Explanation of Example</head><glist><gitem><label><code><interface name = "reservationInterface" ></code></label><def><p>Interfaces are declared directly inside the <code>description</code> element. In this example, we are declaring only one interface, but in general a WSDL 2.0 document may declare more than one interface. Thus, each interface must be given a name that is unique within the set of interfaces defined in this WSDL target namespace. Interface names are tokens that must not contain a space or colon (":").</p></def></gitem><gitem><label><code><fault name = "invalidDataFault"
</code></label><def><p>The <code>name</code> attribute defines a name for this fault. The name is required so that when an operation is defined, it can reference the desired fault by name. Fault names must be unique within an interface.</p></def></gitem><gitem><label><code>element = "ghns:invalidDataError"/></code></label><def><p>The <code>element</code> attribute specifies the schema type of the fault message, as previously defined in the <code>types</code> section. </p></def></gitem><gitem><label><code><operation name="opCheckAvailability"</code></label><def><p>The <code>name</code> attribute defines a name for this operation, so that it can be referenced later when bindings are defined. Operation names must also be unique within an interface. (WSDL 2.0 uses separate symbol spaces for operation and fault names, so operation name "foo" is distinct from fault name "foo".)</p></def></gitem>
! <gitem><label><code>pattern="http://www.w3.org/2005/05/wsdl/in-out" </code></label><def><p>This line specifies that this operation will use the <xspecref href="&w3c-designation-part2;#in-out">in-out</xspecref> pattern as described above. WSDL 2.0 uses URIs to identify message exchange patterns in order to ensure that the identifiers are globally unambiguous, while also permitting future new patterns to be defined by anyone. (However, just because someone defines a new pattern and creates a URI to identify it, that does <emph>not</emph> mean that other WSDL processors will automatically recognize or understand that pattern. As with any other extension, it can only be used among processors that <emph>do</emph> recognize and understand it.)</p></def></gitem>
<gitem><label><code>style="http://www.w3.org/2005/05/wsdl/style/uri" </code></label><def><p>
--- 305,312 ----
. . .
! </description>]]></eg></example><div3 id="example-initial-interface-explanation"><head>Explanation of Example</head><glist><gitem><label><code><interface name = "reservationInterface" ></code></label><def><p>Interfaces are declared directly inside the <code>description</code> element. In this example, we are declaring only one interface, but in general a WSDL 2.0 document may declare more than one interface. Thus, each interface must be given a name that is unique within the set of interfaces defined in this WSDL 2.0 target namespace. Interface names are tokens that must not contain a space or colon (":").</p></def></gitem><gitem><label><code><fault name = "invalidDataFault"
</code></label><def><p>The <code>name</code> attribute defines a name for this fault. The name is required so that when an operation is defined, it can reference the desired fault by name. Fault names must be unique within an interface.</p></def></gitem><gitem><label><code>element = "ghns:invalidDataError"/></code></label><def><p>The <code>element</code> attribute specifies the schema type of the fault message, as previously defined in the <code>types</code> section. </p></def></gitem><gitem><label><code><operation name="opCheckAvailability"</code></label><def><p>The <code>name</code> attribute defines a name for this operation, so that it can be referenced later when bindings are defined. Operation names must also be unique within an interface. (WSDL 2.0 uses separate symbol spaces for operation and fault names, so operation name "foo" is distinct from fault name "foo".)</p></def></gitem>
! <gitem><label><code>pattern="http://www.w3.org/2005/05/wsdl/in-out" </code></label><def><p>This line specifies that this operation will use the <xspecref href="&w3c-designation-part2;#in-out">in-out</xspecref> pattern as described above. WSDL 2.0 uses URIs to identify message exchange patterns in order to ensure that the identifiers are globally unambiguous, while also permitting future new patterns to be defined by anyone. (However, just because someone defines a new pattern and creates a URI to identify it, that does <emph>not</emph> mean that other WSDL 2.0 processors will automatically recognize or understand that pattern. As with any other extension, it can only be used among processors that <emph>do</emph> recognize and understand it.)</p></def></gitem>
<gitem><label><code>style="http://www.w3.org/2005/05/wsdl/style/uri" </code></label><def><p>
***************
*** 356,360 ****
However, other specifications could define new binding
extensions that could also be used to define bindings.
! (As with any extension, other WSDL processors would have
to know about the new constructs in order to make use of
them.)
--- 365,369 ----
However, other specifications could define new binding
extensions that could also be used to define bindings.
! (As with any extension, other WSDL 2.0 processors would have
to know about the new constructs in order to make use of
them.)
***************
*** 395,399 ****
. . .
</description>]]></eg>
! </example><div3 id="example-initial-binding-explanation"><head>Explanation of Example</head><glist><gitem><label><code>xmlns:wsoap= "http://www.w3.org/2005/05/wsdl/soap"</code></label><def><p>We've added two more namespace declarations. This one is the namespace for the SOAP 1.2 binding extension that is defined in WSDL 2.0 Part 3 <bibref ref="SOAP12-PART1"/>. Elements and attributes prefixed with <code>wsoap:</code> are constructs defined there. </p></def></gitem><gitem><label><code>xmlns:soap="http://www.w3.org/2003/05/soap-envelope"</code></label><def><p>This namespace is defined by the SOAP 1.2 specification itself. The SOAP 1.2 specification defines certain terms within this namespace to unambiguously identify particular concepts. Thus, we will use the <code>soap:</code> prefix when we need to refer to one of those terms.</p></def></gitem><gitem><label><code><binding name="reservationSOAPBinding"</code></label><def><p>Bindings are declared directly inside the <code>description</code> eement. The <att>name</att> attribute defines a name for this binding. Each name must be unique among all bindings in this WSDL target namespace, and will be used later when we define a service endpoint that references this binding. WSDL 2.0 uses separate symbol spaces for interfaces, bindings and services, so interface "foo", binding "foo" and service "foo" are all distinct. </p></def></gitem><gitem><label><code>interface="tns:reservationInterface"</code></label><def><p>This is the name of the interface whose message format and transmission protocols we are specifying. As discussed in <specref ref="more-bindings"/>, a reusable binding can be defined by omitting the <att>interface</att> attribute. Note also the use of the <code>tns:</code> prefix, which refers to the previously defined WSDL target namespace for this WSDL document. In this case it may seem silly to have to specify the <code>tns:</code> prefix, but in <specref ref="adv-import-and-authoring"/> we will see how WSDL 2.0's import mechanismcan be used to combine components that are defined in different WSDL target namespaces.</p></def></gitem><gitem><label><code>type="http://www.w3.org/2005/05/wsdl/soap"</code></label><def><p>This specifies what kind of concrete message format to use, in this case SOAP 1.2.</p></def></gitem><gitem><label><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></label><def><p>This attribute is specific to WSDL 2.0's SOAP binding extension (thus it uses the <code>wsoap:</code> prefix). It specifies the underlying transmission protocol that should be used, in this case HTTP. </p></def></gitem><gitem><label><code><operation ref="tns:opCheckAvailability"</code></label><def>
<p>
This is not defining a new operation; rather, it is referencing the
--- 404,408 ----
. . .
</description>]]></eg>
! </example><div3 id="example-initial-binding-explanation"><head>Explanation of Example</head><glist><gitem><label><code>xmlns:wsoap= "http://www.w3.org/2005/05/wsdl/soap"</code></label><def><p>We've added two more namespace declarations. This one is the namespace for the SOAP 1.2 binding extension that is defined in WSDL 2.0 Part 3 <bibref ref="SOAP12-PART1"/>. Elements and attributes prefixed with <code>wsoap:</code> are constructs defined there. </p></def></gitem><gitem><label><code>xmlns:soap="http://www.w3.org/2003/05/soap-envelope"</code></label><def><p>This namespace is defined by the SOAP 1.2 specification itself. The SOAP 1.2 specification defines certain terms within this namespace to unambiguously identify particular concepts. Thus, we will use the <code>soap:</code> prefix when we need to refer to one of those terms.</p></def></gitem><gitem><label><code><binding name="reservationSOAPBinding"</code></label><def><p>Bindings are declared directly inside the <code>description</code> eement. The <att>name</att> attribute defines a name for this binding. Each name must be unique among all bindings in this WSDL 2.0 target namespace, and will be used later when we define a service endpoint that references this binding. WSDL 2.0 uses separate symbol spaces for interfaces, bindings and services, so interface "foo", binding "foo" and service "foo" are all distinct. </p></def></gitem><gitem><label><code>interface="tns:reservationInterface"</code></label><def><p>This is the name of the interface whose message format and transmission protocols we are specifying. As discussed in <specref ref="more-bindings"/>, a reusable binding can be defined by omitting the <att>interface</att> attribute. Note also the use of the <code>tns:</code> prefix, which refers to the previously defined WSDL 2.0 target namespace for this WSDL 2.0 document. In this case it may seem silly to have to specify the <code>tns:</code> prefix, but in <specref ref="adv-import-and-authoring"/> we will see how WSDL 2.0's impot mechanism can be used to combine components that are defined in different WSDL 2.0 target namespaces.</p></def></gitem><gitem><label><code>type="http://www.w3.org/2005/05/wsdl/soap"</code></label><def><p>This specifies what kind of concrete message format to use, in this case SOAP 1.2.</p></def></gitem><gitem><label><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></label><def><p>This attribute is specific to WSDL 2.0's SOAP binding extension (thus it uses the <code>wsoap:</code> prefix). It specifies the underlying transmission protocol that should be used, in this case HTTP. </p></def></gitem><gitem><label><code><operation ref="tns:opCheckAvailability"</code></label><def>
<p>
This is not defining a new operation; rather, it is referencing the
***************
*** 447,453 ****
</description>]]></eg>
! </example><div3 id="example-initial-service-explanation"><head>Explanation of Example</head><glist><gitem><label><code><service name="reservationService"</code></label><def><p>This defines a name for this service, which must be unique among service names in the WSDL target namespace. The name attribute is required. It allows URIs to be created that identify components in WSDL 2.0 description. (See <emph>WSDL 2.0 Core Language</emph> <bibref ref="WSDL-PART1"/> appendix C <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-20040803/#wsdl-uri-references">URI References for WSDL constructs</xspecref>.)</p></def></gitem><gitem><label><code>interface="tns:reservationInterface"></code></label><def><p>This specifies the name of the previously defined interface that these service endpoints will support. </p></def></gitem><gitem><label><code><endpoint name="reservationEndpoint"</code></label><def><p>This defines an endpoint for the service, and a name for this endpoint, which must be unique withinthis service. </p></def></gitem><gitem><label><code>binding="tns:reservationSOAPBinding"</code></label><def><p>This specifies the name of the previously defined binding to be used by this endpoint. </p></def></gitem><gitem><label><code>address ="http://greath.example.com/2004/reservation"/></code></label><def><p>This specifies the physical address at which this service can be accessed using the binding specified by the <att>binding</att> attribute.</p></def></gitem></glist><p>That's it! Well, almost. </p></div3></div2>
! <div2 id="basics-documentation"><head>Documenting the Service</head><p>As we have seen, a WSDL 2.0 document is inherently only a <emph>partial</emph> description of a service. Although it captures the basic mechanics of interacting with the service -- the message types, transmission protocols, service location, etc. -- in general, additional documentation will need to explain other application-level requirements for its use. For example, such documentation should explain the purpose and use of the service, the meanings of all messages, constraints on their use, and the sequence in which operations should be invoked.</p><p>The <code>documentation</code> element allows the WSDL author to include some human-readable documentation inside a WSDL 2.0 document. It is also a convenient place to reference any additional external documentation that a client developer may need in order to use the service. It can appear in a number of places in a WSDL 2.0 document (see <specref ref="wsdl-infoset-diagram"/>) though in this example we have only demonstrated its use at the beginning.</p><example id="example-initial-documentation">
<head>Documenting the GreatH Service</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
--- 456,462 ----
</description>]]></eg>
! </example><div3 id="example-initial-service-explanation"><head>Explanation of Example</head><glist><gitem><label><code><service name="reservationService"</code></label><def><p>This defines a name for this service, which must be unique among service names in the WSDL 2.0 target namespace. The name attribute is required. It allows URIs to be created that identify components in WSDL 2.0 description. (See <emph>WSDL 2.0 Core Language</emph> <bibref ref="WSDL-PART1"/> appendix C <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-20040803/#wsdl-uri-references">URI References for WSDL 2.0 constructs</xspecref>.)</p></def></gitem><gitem><label><code>interface="tns:reservationInterface"></code></label><def><p>This specifies the name of the previously defined interface that these service endpoints will support. </p></def></gitem><gitem><label><code><endpoint name="reservationEndpoint"</code></label><def><p>This defines an endpoint for the service, and a name for this endpoint, which must be uniqu within this service. </p></def></gitem><gitem><label><code>binding="tns:reservationSOAPBinding"</code></label><def><p>This specifies the name of the previously defined binding to be used by this endpoint. </p></def></gitem><gitem><label><code>address ="http://greath.example.com/2004/reservation"/></code></label><def><p>This specifies the physical address at which this service can be accessed using the binding specified by the <att>binding</att> attribute.</p></def></gitem></glist><p>That's it! Well, almost. </p></div3></div2>
! <div2 id="basics-documentation"><head>Documenting the Service</head><p>As we have seen, a WSDL 2.0 document is inherently only a <emph>partial</emph> description of a service. Although it captures the basic mechanics of interacting with the service -- the message types, transmission protocols, service location, etc. -- in general, additional documentation will need to explain other application-level requirements for its use. For example, such documentation should explain the purpose and use of the service, the meanings of all messages, constraints on their use, and the sequence in which operations should be invoked.</p><p>The <code>documentation</code> element allows the WSDL 2.0 author to include some human-readable documentation inside a WSDL 2.0 document. It is also a convenient place to reference any additional external documentation that a client developer may need in order to use the service. It can appear in a number of places in a WSDL 2.0 document (see <specref ref="wsdl-infoset-diagram/>), though in this example we have only demonstrated its use at the beginning.</p><example id="example-initial-documentation">
<head>Documenting the GreatH Service</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
***************
*** 512,518 ****
</eg>
! <p>In other words, the children elements of the <code>description</code> element should be ordered as follows:
! </p>
! <ulist>
<item>
<p>
--- 521,530 ----
</eg>
! <p>
! In other words, the children elements of the
! <code>description</code>
! element should be ordered as follows:
! </p>
! <ulist>
<item>
<p>
***************
*** 521,548 ****
</item>
! <item>
! <p>then comes zero or more elements from among the following, in any
! order:
! </p>
! <ulist>
! <item>
! <p>
! Zero or more <el>include</el>
! </p>
! </item>
! <item>
! <p>
! Zero or more <el>import</el>
! </p>
! </item>
! <item>
! <p>
! Zero or more extensions
! </p>
! </item>
! </ulist>
! </item>
! <item>
<p>
An optional <el>types</el> follows
--- 533,559 ----
</item>
! <item>
! <p>
! then comes zero or more elements from among the
! following, in any order:
! </p>
! <ulist>
! <item>
! <p>
! <el>include</el>
! </p>
! </item>
! <item>
! <p>
! <el>import</el>
! </p>
! </item>
! <item>
! <p>extensions</p>
! </item>
! </ulist>
! </item>
! <item>
<p>
An optional <el>types</el> follows
***************
*** 550,584 ****
</item>
! <item>
! <p>
! Zero or more elements from among the following, in any
! order:
! </p>
! <ulist>
! <item>
! <p>
! <el>interface</el> elements
! </p>
! </item>
! <item>
! <p>
! <el>binding</el> elements
! </p>
! </item>
! <item>
! <p>
! <el>service</el> elements
! </p>
! </item>
! <item>
! <p>
! Zero or more extensions.
! </p>
! </item>
! </ulist>
</item>
!
! </ulist>
<p>Note the term "extension" is used above as a convenient way to refer to namespace-qualified extension elements. The namespace name of such extension elements must not be<attval>&wsdl-ns;</attval>.
--- 561,593 ----
</item>
! <item>
! <p>
! Zero or more elements from among the following, in
! any order:
! </p>
! <ulist>
! <item>
! <p>
! <el>interface</el>
! </p>
! </item>
! <item>
! <p>
! <el>binding</el>
! </p>
! </item>
! <item>
! <p>
! <el>service</el>
! </p>
! </item>
! <item>
! <p>extensions.</p>
! </item>
! </ulist>
</item>
!
! </ulist>
<p>Note the term "extension" is used above as a convenient way to refer to namespace-qualified extension elements. The namespace name of such extension elements must not be<attval>&wsdl-ns;</attval>.
***************
*** 595,599 ****
</p>
! <p>The WSDL 2.0 component model is particularly helpful in defining the meaning of <code>import</code> and <code>include</code>. WSDL 2.0 <code>include</code> allows components from another WSDL 2.0 document having the same targetNamespace to be merged in with the components of the current WSDL 2.0 document, and is transitive (i.e., if the included document also includes a WSDL 2.0 document, then those components will also be merged, and so on). WSDL 2.0 <code>import</code> allows components from another WSDL 2.0 document having a different targetNamespace to be merged in with comonents of the current WSDL 2.0 document, and is not transitive.</p></div2></div1>
--- 604,664 ----
</p>
! <p>
! The WSDL 2.0 component model is particularly helpful in defining
! the meaning of
! <el>import</el>
! and
! <el>include</el>
! elements. The
! <el>include</el>
! element allows you to assemble the contents of a given WSDL 2.0
! namespace from several WSDL 2.0 documents that define components
! for that namespace. The components defined by a given WSDL 2.0
! document consist of those whose definitions are contained in the
! document and those that are defined by any WSDL 2.0 documents
! that are included in it via the
! <el>include</el>
! element. The effect of the
! <el>include</el>
! element is cummulative so that if document A includes document B
! and document B includes document C, then the components defined
! by document A consist of those whose definitions are contained
! in documents A, B, and C.
! </p>
! <p>
! In contrast, the
! <el>import</el>
! element does not define any components. Instead, the
! <el>import</el>
! element declares that the components whose definitions are
! contained in a WSDL 2.0 document for a given WSDL 2.0 namespace
! refer to components that belong to a different WSDL 2.0
! namespace. If a WSDL 2.0 document contains definitions of
! components that refer to other namespaces, then those namespaces
! must be declared via an
! <el>import</el>
! element. The
! <el>import</el>
! element also has an optional
! <att>location</att>
! attribute that is a hint to the processor where the definitions
! of the imported namespace can be found. However, the processor
! may find the definitions by other means, for example, by using a
! catalog.
! </p>
!
! <p>
! After processing any
! <el>include</el>
! elements and locating the components that belong to any imported
! namespaces, the WSDL 2.0 component model for a WSDL 2.0 document
! will contain a set of components that belong to the document's
! WSDL 2.0 namespace and any imported namespaces. These components
! will refer to each other, usually via QName references. A WSDL
! 2.0 document is invalid if any component reference cannot be
! resolved, whether or not the referenced component belongs to the
! same or a different namespace.
! </p>
! </div2></div1>
***************
*** 608,615 ****
<ednote><name>dbooth</name><date>2005-04-13</date><edtext>ToDo: Check the sections below on import and include mechanisms for correctness. (Be sure to check the table also.) I'm not sure I got them all right.</edtext></ednote><p>There are two ways to indicate XML Schema message definitions using the <code>types</code> element.
! One way is to inline schema definitions within <code>xs:schema</code> elements that are children of <code>types</code>, as we have already seen. The other way is to use <code>xs:import</code> directly under <code>types</code>. It is perfectly reasonable to use both ways in one WSDL document.</p>
! <p>A WSDL <code>description</code> must NOT refer to XML Schema components that are neither imported nor
! inlined into that WSDL <code>description</code>. In other words, the use of <code>xs:import</code> and/or <code>xs:schema</code> is a necessary condition for making XML Schema components available to a WSDL Description component. </p>
<p>The following XML syntax for the <code>types</code> element illustrates the use of <code>xs:import</code> and <code>xs:schema</code>:</p>
--- 673,680 ----
<ednote><name>dbooth</name><date>2005-04-13</date><edtext>ToDo: Check the sections below on import and include mechanisms for correctness. (Be sure to check the table also.) I'm not sure I got them all right.</edtext></ednote><p>There are two ways to indicate XML Schema message definitions using the <code>types</code> element.
! One way is to inline schema definitions within <code>xs:schema</code> elements that are children of <code>types</code>, as we have already seen. The other way is to use <code>xs:import</code> directly under <code>types</code>. It is perfectly reasonable to use both ways in one WSDL 2.0 document.</p>
! <p>A WSDL 2.0 <code>description</code> must NOT refer to XML Schema components that are neither imported nor
! inlined into that WSDL 2.0 <code>description</code>. In other words, the use of <code>xs:import</code> and/or <code>xs:schema</code> is a necessary condition for making XML Schema components available to a WSDL 2.0 Description component. </p>
<p>The following XML syntax for the <code>types</code> element illustrates the use of <code>xs:import</code> and <code>xs:schema</code>:</p>
***************
*** 630,639 ****
<p>When XML Schema is inlined directly in a WSDL 2.0 document, it uses the existing top-level <code>xs:schema</code> element defined by XML Schema <bibref ref="XMLSchemaP1"/> to do so, as though the schema had been copied and pasted into the <code>types</code> element.
The schema components defined in the inlined schema are then available to
! WSDL for reference by QName (see WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="&w3c-designation-part1;#qnameres">QName Resolution</xspecref>"). </p>
<p>Although WSDL 2.0 provides a <code>wsdl:import</code> mechanism (described in the next section),
an inlined XML schema may also use XML Schema's native <code>xs:import</code> and <code>xs:include</code>
elements to refer to schemas either in separate files or inlined in the same
WSDL 2.0 document. However, components inlined using <code>xs:import</code> have different visibility from those
! inlined using <code>xs:include</code>: <code>xs:include</code>d components are available to WSDL for reference by QName, but <code>xs:import</code>ed components are not.</p>
--- 695,704 ----
<p>When XML Schema is inlined directly in a WSDL 2.0 document, it uses the existing top-level <code>xs:schema</code> element defined by XML Schema <bibref ref="XMLSchemaP1"/> to do so, as though the schema had been copied and pasted into the <code>types</code> element.
The schema components defined in the inlined schema are then available to
! WSDL 2.0 for reference by QName (see WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="&w3c-designation-part1;#qnameres">QName Resolution</xspecref>"). </p>
<p>Although WSDL 2.0 provides a <code>wsdl:import</code> mechanism (described in the next section),
an inlined XML schema may also use XML Schema's native <code>xs:import</code> and <code>xs:include</code>
elements to refer to schemas either in separate files or inlined in the same
WSDL 2.0 document. However, components inlined using <code>xs:import</code> have different visibility from those
! inlined using <code>xs:include</code>: <code>xs:include</code>d components are available to WSDL 2.0 for reference by QName, but <code>xs:import</code>ed components are not.</p>
***************
*** 648,657 ****
! <p>The <code>xs:import</code> mechanism is not transitive. Only components defined in the imported schema itself and components the schema includes via <code>xs:include</code> are available to the containing WSDL document. Specifically, components that the schema imports via <code>xs:import</code> are NOT available to WSDL. </p>
<ednote><name>dbooth</name><date>2005-04-13</date><edtext>Check this. An issue was recently raised about import not being transitive.</edtext></ednote>
! <p>Here is an example of importing a schema. Assuming the message types in <specref ref="example-initial-types"/> are defined in a separate schema file named "http://greath.example.com/2004/schemas/resSvc.xsd" with a target namespace "http://greath.example.com/2004/schemas/resSvc", the schema definition can then be imported into the WSDL as follows: </p>
<example id="example-schema-import">
<head>Example of Importing Message Definitions</head>
--- 713,722 ----
! <p>The <code>xs:import</code> mechanism is not transitive. Only components defined in the imported schema itself and components the schema includes via <code>xs:include</code> are available to the containing WSDL 2.0 document. Specifically, components that the schema imports via <code>xs:import</code> are NOT available to WSDL 2.0. </p>
<ednote><name>dbooth</name><date>2005-04-13</date><edtext>Check this. An issue was recently raised about import not being transitive.</edtext></ednote>
! <p>Here is an example of importing a schema. Assuming the message types in <specref ref="example-initial-types"/> are defined in a separate schema file named "http://greath.example.com/2004/schemas/resSvc.xsd" with a target namespace "http://greath.example.com/2004/schemas/resSvc", the schema definition can then be imported into the WSDL 2.0 as follows: </p>
<example id="example-schema-import">
<head>Example of Importing Message Definitions</head>
***************
*** 742,746 ****
<div2 id="more-interfaces-inheritance">
<head>Interface Inheritance</head>
! <p>The optional <att>extends</att> attribute allows an interface to extend or inherit from one or more other interfaces. In such cases the interface contains the operations of the interfaces it extends, along with any operations it defines directly. Two things about extending interfaces deserve some attention. </p><p>First, an inheritance loop (or infinite recursion) is prohibited: the interfaces that a given interface extends must NOT themselves extend that interface either directly or indirectly. </p><p>Second, we must explain what happens when operations from two different interfaces have the same target namespace and operation name. There are two cases: either the component models of the operations are the same, or they are different. If the component models are the same (per the component comparison algorithm defined in WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="&w3c-designation-part1;#compequiv">Equivalence of Components</xspecref>") then they are considered to be the same peration, i.e., they are collapsed into a single operation, and the fact that they were included more than once is not considered an error. (For operations, component equivalence basically means that the two operations have the same set of attributes and descendents.) In the second case, if two operations have the same name in the same WSDL target namespace but are not equivalent, then it is an error. For the above reason, it is considered good practice to ensure that all operations within the same target namespace are named uniquely. </p><p>Finally, since faults, features and properties can also be defined as children of the <code>interface</code> element (as described in the following sections), the same name-collision rules apply to those constructs. </p>
<p>Let's say the GreatH hotel wants to maintain a a standard message log operation for all received messages. It wants this operation to be reusable across the whole reservation system, so each service will send out, for potential use of a logging service,
--- 807,811 ----
<div2 id="more-interfaces-inheritance">
<head>Interface Inheritance</head>
! <p>The optional <att>extends</att> attribute allows an interface to extend or inherit from one or more other interfaces. In such cases the interface contains the operations of the interfaces it extends, along with any operations it defines directly. Two things about extending interfaces deserve some attention. </p><p>First, an inheritance loop (or infinite recursion) is prohibited: the interfaces that a given interface extends must NOT themselves extend that interface either directly or indirectly. </p><p>Second, we must explain what happens when operations from two different interfaces have the same target namespace and operation name. There are two cases: either the component models of the operations are the same, or they are different. If the component models are the same (per the component comparison algorithm defined in WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="&w3c-designation-part1;#compequiv">Equivalence of Components</xspecref>") then they are considered to be the same peration, i.e., they are collapsed into a single operation, and the fact that they were included more than once is not considered an error. (For operations, component equivalence basically means that the two operations have the same set of attributes and descendents.) In the second case, if two operations have the same name in the same WSDL 2.0 target namespace but are not equivalent, then it is an error. For the above reason, it is considered good practice to ensure that all operations within the same target namespace are named uniquely. </p><p>Finally, since faults, features and properties can also be defined as children of the <code>interface</code> element (as described in the following sections), the same name-collision rules apply to those constructs. </p>
<p>Let's say the GreatH hotel wants to maintain a a standard message log operation for all received messages. It wants this operation to be reusable across the whole reservation system, so each service will send out, for potential use of a logging service,
***************
*** 789,793 ****
<p>Faults are very similar to messages and can be viewed as a special kind of
message. Both faults and messages may carry a payload that is normally described
! by an element declaration. However, WSDL treats faults and messages slightly
differently. The messages of an operation directly refer to their element
declaration, however the faults of an operation indirectly refer to their
--- 854,858 ----
<p>Faults are very similar to messages and can be viewed as a special kind of
message. Both faults and messages may carry a payload that is normally described
! by an element declaration. However, WSDL 2.0 treats faults and messages slightly
differently. The messages of an operation directly refer to their element
declaration, however the faults of an operation indirectly refer to their
***************
*** 802,806 ****
them, thereby ensuring consistency across all operations that use the faults </p>
! <p>The <code>fault</code> element has a required <att>name</att> attribute that must be unique within the WSDL document's target namespace, and permits it to be referenced from operation declarations. The optional <att>element</att> attribute can be used to indicate a schema for the content or payload of the fault message. Its value should be the QName of a global element defined in the <code>types</code> section. Please note that when other type systems are used to define the schema for a fault message, additional attributes may need to be defined via WSDL's attribute extension mechanism to allow the schema to be associated with the fault.</p>
--- 867,871 ----
them, thereby ensuring consistency across all operations that use the faults </p>
! <p>The <code>fault</code> element has a required <att>name</att> attribute that must be unique within the WSDL 2.0 document's target namespace, and permits it to be referenced from operation declarations. The optional <att>element</att> attribute can be used to indicate a schema for the content or payload of the fault message. Its value should be the QName of a global element defined in the <code>types</code> section. Please note that when other type systems are used to define the schema for a fault message, additional attributes may need to be defined via WSDL 2.0's attribute extension mechanism to allow the schema to be associated with the fault.</p>
***************
*** 844,855 ****
<head>Understanding Message Exchange Patterns (MEPs)</head>
<p>WSDL 2.0 message exchange patterns (MEPs) are used to define the sequence and cardinality of the abstract messages in an operation. By design, WSDL 2.0 MEPs are abstract. First of all, they abstract out specific message types. MEPs identify placeholders for messages, and placeholders are associated with specific message types when an operation is defined, which includes specifying which MEP to use for that operation. Secondly, unless explicitly stated otherwise, MEPs also abstract out binding-specific information like timing between messages, whether the pattern is synchronous or asynchronous, and whether the messages are sent over a single or multiple channels.</p>
! <p>It's worth pointing out that WSDL MEPs do not exhaustively describe the set of messages that may be exchanged between a service and other nodes. By some prior agreement, another node and/or the service may send other messages (to each other or to other nodes) that are not described by the
MEP. For instance, even though an MEP may define a single message sent
from a service to one other node, a service defined by that MEP may multicast that message to
! other nodes. To maximize reuse, WSDL message exchange patterns identify a minimal contract between other parties and Web Services, and contain only information that is relevant to both the Web service and the client that engages that service.</p>
<p>A total of eight MEPs are defined in <bibref ref="WSDL-PART2"/>. These MEPs should cover the most common use cases, but they are not meant to be an exhaustive list of MEPs that can ever be used by operations. More MEPs can be defined for particular application needs by interested parties. (See <specref ref="more-interfaces-meps"/> )</p>
<p>For the eight MEPs defined by WSDL 2.0, some of them are variations of others based on how faults may be generated. For example, the In-Only pattern ("http://www.w3.org/2005/05/wsdl/in-only") consists of exactly one message received by a service from some other node. No fault can be generated. As a variation of In-Only, Robust In-Only pattern ("http://www.w3.org/2005/05/wsdl/robust-in-only") also consists of exactly one message received by a service, but in this case faults can be triggered by the message and must be delivered to the originator of the message. If there is no path to this node, the fault must be discarded. For details about the common fault generation models used by the eight WSDL 2.0 MEPs, see <bibref ref="WSDL-PART2"/>. </p>
! <p>Depending on how the first message in the MEP is initiated, the eight WSDL MEPs may be grouped into two groups: in-bound MEPs, for which the service receives the first message in the exchange, and out-bound MEPs, for which the service sends out the first message in the exchange. (Such grouping is not provided in the WSDL 2.0 specification and is presented here only for the purpose of easy reference in this primer).</p>
<p> A frequently asked question about out-bound MEPs is how a service knows where to send the message. Services using out-bound MEPs are typically part of large scale integration systems that rely on mapping and routing facilities. In such systems, out-bound MEPs are useful for specifying the functionality of a service abstractly, including its requirements for potential customers, while endpoint address information can be provided at deployment or runtime by the underlying integration infrastructure. For example, the GreatH hotel reservation system may require that every time a customer interacts with the system to check availability, data about the customer must be logged by a CRM system. At design time, it's unknown which particular CRM system would be used together with the reservation system. To address this requirement, we may change the "reservationInterface" in <specref ref="example-initial"/> to include an out-bound logInquiry operation. This <code>logInquiry</code> operation advertises to ptential service clients that customer data will be made available by the reservation service at run time. When the reservation service is deployed to GreatH's IT landscape, appropriate configuration time and run time infrastructure will help determine which CRM system will get the customer data and log it appropriately. It's worth noting that in addition to being used by a CRM system for customer management purpose, the same data may also be used by a system performance analysis tool for different purpose. Providing an out-bound operation in the reservation service enables loose coupling and so improves the overall GreatH IT landscape's flexibility and scalability. </p>
--- 909,920 ----
<head>Understanding Message Exchange Patterns (MEPs)</head>
<p>WSDL 2.0 message exchange patterns (MEPs) are used to define the sequence and cardinality of the abstract messages in an operation. By design, WSDL 2.0 MEPs are abstract. First of all, they abstract out specific message types. MEPs identify placeholders for messages, and placeholders are associated with specific message types when an operation is defined, which includes specifying which MEP to use for that operation. Secondly, unless explicitly stated otherwise, MEPs also abstract out binding-specific information like timing between messages, whether the pattern is synchronous or asynchronous, and whether the messages are sent over a single or multiple channels.</p>
! <p>It's worth pointing out that WSDL 2.0 MEPs do not exhaustively describe the set of messages that may be exchanged between a service and other nodes. By some prior agreement, another node and/or the service may send other messages (to each other or to other nodes) that are not described by the
MEP. For instance, even though an MEP may define a single message sent
from a service to one other node, a service defined by that MEP may multicast that message to
! other nodes. To maximize reuse, WSDL 2.0 message exchange patterns identify a minimal contract between other parties and Web Services, and contain only information that is relevant to both the Web service and the client that engages that service.</p>
<p>A total of eight MEPs are defined in <bibref ref="WSDL-PART2"/>. These MEPs should cover the most common use cases, but they are not meant to be an exhaustive list of MEPs that can ever be used by operations. More MEPs can be defined for particular application needs by interested parties. (See <specref ref="more-interfaces-meps"/> )</p>
<p>For the eight MEPs defined by WSDL 2.0, some of them are variations of others based on how faults may be generated. For example, the In-Only pattern ("http://www.w3.org/2005/05/wsdl/in-only") consists of exactly one message received by a service from some other node. No fault can be generated. As a variation of In-Only, Robust In-Only pattern ("http://www.w3.org/2005/05/wsdl/robust-in-only") also consists of exactly one message received by a service, but in this case faults can be triggered by the message and must be delivered to the originator of the message. If there is no path to this node, the fault must be discarded. For details about the common fault generation models used by the eight WSDL 2.0 MEPs, see <bibref ref="WSDL-PART2"/>. </p>
! <p>Depending on how the first message in the MEP is initiated, the eight WSDL 2.0 MEPs may be grouped into two groups: in-bound MEPs, for which the service receives the first message in the exchange, and out-bound MEPs, for which the service sends out the first message in the exchange. (Such grouping is not provided in the WSDL 2.0 specification and is presented here only for the purpose of easy reference in this primer).</p>
<p> A frequently asked question about out-bound MEPs is how a service knows where to send the message. Services using out-bound MEPs are typically part of large scale integration systems that rely on mapping and routing facilities. In such systems, out-bound MEPs are useful for specifying the functionality of a service abstractly, including its requirements for potential customers, while endpoint address information can be provided at deployment or runtime by the underlying integration infrastructure. For example, the GreatH hotel reservation system may require that every time a customer interacts with the system to check availability, data about the customer must be logged by a CRM system. At design time, it's unknown which particular CRM system would be used together with the reservation system. To address this requirement, we may change the "reservationInterface" in <specref ref="example-initial"/> to include an out-bound logInquiry operation. This <code>logInquiry</code> operation advertises to ptential service clients that customer data will be made available by the reservation service at run time. When the reservation service is deployed to GreatH's IT landscape, appropriate configuration time and run time infrastructure will help determine which CRM system will get the customer data and log it appropriately. It's worth noting that in addition to being used by a CRM system for customer management purpose, the same data may also be used by a system performance analysis tool for different purpose. Providing an out-bound operation in the reservation service enables loose coupling and so improves the overall GreatH IT landscape's flexibility and scalability. </p>
***************
*** 929,933 ****
<p>A binding <code>operation</code> describes a concrete binding of an interface
operation to a concrete message format. An interface
! operation is uniquely identified by the WSDL target namespace of the
interface and the name of the operation within that interface, via the required <att>ref</att> attribute of binding <code>operation</code>. As with faults, for each <code>operation</code> within a <code>binding</code>, the value of the <att>ref</att> attribute must be unique.</p>
--- 994,998 ----
<p>A binding <code>operation</code> describes a concrete binding of an interface
operation to a concrete message format. An interface
! operation is uniquely identified by the WSDL 2.0 target namespace of the
interface and the name of the operation within that interface, via the required <att>ref</att> attribute of binding <code>operation</code>. As with faults, for each <code>operation</code> within a <code>binding</code>, the value of the <att>ref</att> attribute must be unique.</p>
***************
*** 1086,1090 ****
<div2 id="adv-extensibility">
<head>Extensibility</head>
! <p>WSDL 2.0 provides two extensibility mechanisms: an open content model, which allows XML elements and attributes from other (non-WSDL 2.0) XML namespaces to be interspersed in a WSDL 2.0 document; and <xspecref href="&w3c-designation-part1;#Feature">Features</xspecref> and <xspecref href="&w3c-designation-part1;#Property">Properties</xspecref>. Both mechanisms use URIs to identify the semantics of the extensions. For extension XML elements and attributes, the namespace URI of the extension element or attribute acts as an unambiguous name for the semantics of that extension. For Features and Properties, the Feature or Property is named by a URI.</p><p>In either case, the URI that identifies the semantics of an extension should be dereferenceable to a document that describes the semantics of that extension. As of this writing, there is no generally accepted standard for what kind of document that should be. However, the <loc href="http://www.w3.org/2001/tag/">W3C TAG</loc> has been discussing th issue (see TAG issue <loc href="http://www.w3.org/2001/tag/issues.html?type=1#namespaceDocument-8">namespaceDocument-8</loc>) and is likely to provide guidance at some point.</p><div3 id="adv-optional-versus-required"><head>Optional Versus Required Extensions</head><p>Extensions can either be required or optional.</p><p>An <emph>optional</emph> extension is one that the client may either engage or ignore, entirely at its discretion, and is signaled by attribute <code>wsdl:required="false"</code> or the absence of the <code>wsdl:required</code> attribute (because it defaults to false). Thus, a WSDL processor, acting on behalf of the client, that encounters an unknown optional extension can safely ignore it and continue to process the WSDL 2.0 document. However, it is important to stress that optional extensions are only optional to the <emph>client</emph> -- not the service. A service must support all optional and required extensions that it advertises in its WSDL 2.0 document. </p><p>A <emph>required/emph> extension is one that must be supported and engaged by the client in order for the interaction to procede properly, and is signaled by attribute <code>wsdl:required="true"</code>. If a WSDL processor, acting on behalf of the client, encounters a required extension that it does not recognize or does not support, then it cannot safely continue to process the WSDL 2.0 document. In most practical cases, this is likely to mean that the processor will require manual intervention to deal with the extension. For example, a client developer might manually provide an implementation for the required extension to the WSDL processor. </p></div3>
<!-- removed per minutes 5-12-2005 AI div3 id="adv-scope-of-wsdl-required"><head>Scoping of the wsdl:required Attribute</head><ednote><name>dbooth</name><date>2005-04-15</date><edtext>ToDo: Need to check the scoping rules to see if this is correct.</edtext></ednote><p>As a convenience mechanism, the <code>wsdl:required</code> attribute need not be specified on every extension element. If it is omitted from an extension element, its effective value is inherited from the smallest enclosing scope that explicitly sets its value. If there is no enclosing scope that explicitly sets its value, then its value defaults to <code>false</code>. </p><p>Because portions of a Web service description can be written in different physical documents by different people, one should be cautious about setting <code>wsdl:required="false"</code> when an outer scope, written by someone else, had set <code>wsdl:required="true"</code>.</p></div3 -->
--- 1151,1155 ----
<div2 id="adv-extensibility">
<head>Extensibility</head>
! <p>WSDL 2.0 provides two extensibility mechanisms: an open content model, which allows XML elements and attributes from other (non-WSDL 2.0) XML namespaces to be interspersed in a WSDL 2.0 document; and <xspecref href="&w3c-designation-part1;#Feature">Features</xspecref> and <xspecref href="&w3c-designation-part1;#Property">Properties</xspecref>. Both mechanisms use URIs to identify the semantics of the extensions. For extension XML elements and attributes, the namespace URI of the extension element or attribute acts as an unambiguous name for the semantics of that extension. For Features and Properties, the Feature or Property is named by a URI.</p><p>In either case, the URI that identifies the semantics of an extension should be dereferenceable to a document that describes the semantics of that extension. As of this writing, there is no generally accepted standard for what kind of document that should be. However, the <loc href="http://www.w3.org/2001/tag/">W3C TAG</loc> has been discussing th issue (see TAG issue <loc href="http://www.w3.org/2001/tag/issues.html?type=1#namespaceDocument-8">namespaceDocument-8</loc>) and is likely to provide guidance at some point.</p><div3 id="adv-optional-versus-required"><head>Optional Versus Required Extensions</head><p>Extensions can either be required or optional.</p><p>An <emph>optional</emph> extension is one that the client may either engage or ignore, entirely at its discretion, and is signaled by attribute <code>wsdl:required="false"</code> or the absence of the <code>wsdl:required</code> attribute (because it defaults to false). Thus, a WSDL 2.0 processor, acting on behalf of the client, that encounters an unknown optional extension can safely ignore it and continue to process the WSDL 2.0 document. However, it is important to stress that optional extensions are only optional to the <emph>client</emph> -- not the service. A service must support all optional and required extensions that it advertises in its WSDL 2.0 document. </p><p>A <emph>requred</emph> extension is one that must be supported and engaged by the client in order for the interaction to procede properly, and is signaled by attribute <code>wsdl:required="true"</code>. If a WSDL 2.0 processor, acting on behalf of the client, encounters a required extension that it does not recognize or does not support, then it cannot safely continue to process the WSDL 2.0 document. In most practical cases, this is likely to mean that the processor will require manual intervention to deal with the extension. For example, a client developer might manually provide an implementation for the required extension to the WSDL 2.0 processor. </p></div3>
<!-- removed per minutes 5-12-2005 AI div3 id="adv-scope-of-wsdl-required"><head>Scoping of the wsdl:required Attribute</head><ednote><name>dbooth</name><date>2005-04-15</date><edtext>ToDo: Need to check the scoping rules to see if this is correct.</edtext></ednote><p>As a convenience mechanism, the <code>wsdl:required</code> attribute need not be specified on every extension element. If it is omitted from an extension element, its effective value is inherited from the smallest enclosing scope that explicitly sets its value. If there is no enclosing scope that explicitly sets its value, then its value defaults to <code>false</code>. </p><p>Because portions of a Web service description can be written in different physical documents by different people, one should be cautious about setting <code>wsdl:required="false"</code> when an outer scope, written by someone else, had set <code>wsdl:required="true"</code>.</p></div3 -->
***************
*** 1196,1200 ****
<head>Defining New MEPs</head>
! <p>As we mentioned in <specref ref= "more-interfaces-meps"/>, even though the 8 MEPs defined by WSDL2.0 are intented to cover most of the common use cases, there are situations that require new MEPs to be defined. In this section, we will explain how new MEPs can be defined to address special business requirements.</p>
<p>Following the wild success of its reservation service, GreatH discovered
--- 1261,1265 ----
<head>Defining New MEPs</head>
! <p>As we mentioned in <specref ref= "more-interfaces-meps"/>, even though the 8 MEPs defined by WSDL 2.0 are intented to cover most of the common use cases, there are situations that require new MEPs to be defined. In this section, we will explain how new MEPs can be defined to address special business requirements.</p>
<p>Following the wild success of its reservation service, GreatH discovered
***************
*** 1216,1220 ****
application would only examine those emails that contained Subject headers
associated with the service). This required development of a binding to
! email, which is out of scope for this example, but the resulting WSDL was
otherwise quite straightforward.</p>
--- 1281,1285 ----
application would only examine those emails that contained Subject headers
associated with the service). This required development of a binding to
! email, which is out of scope for this example, but the resulting WSDL 2.0 was
otherwise quite straightforward.</p>
***************
*** 1532,1536 ****
<head>Multiple Interfaces for the Same Service</head>
<p>Suppose a Web service wishes to expose two different interfaces: a customer interface for its regular users, and a management interface for its operator. A <code>wsdl:service</code> specifies only one wsdl:interface, so to achieve the desired effect the service provider would somehow need to indicate a relationship between two services. How can a service provider indicate a relationship between services? Potential strategies include:<ulist><item><p><b>Declare both interfaces in the same wsdl:description element.</b> Although WSDL 2.0 does not ascribe any particular significance to the fact that two wsdl:services are declared within the same wsdl:description, an application or toolkit could interpret this to mean that they are related in some way.</p></item><item><p><b>Declare both interfaces in the same wsdl:targetNamespace.</b> Again, although WSDL 2.0 does not ascribe any particular significance to the fact that two wsdl:services are declared within the same wsdl:targetNamespace, an appliction or toolkit could interpret this to mean that they are related in some way.
! </p></item><item><p><b>Add an extension to WSDL 2.0</b> that links together all services that are related in this way. WSDL 2.0's open content model permits extension elements from other namespaces to appear in a WSDL 2.0 document.</p></item><item><p><b>Declare them in completely separate WSDL documents, but use the same endpoint address for both.</b> I.e., declare a <code>wsdl:interface</code> and <code>wsdl:service</code> for the customer interface in one WSDL document, and a <code>wsdl:interface</code> and <code>wsdl:service</code> for the management interface in a different WSDL document, but use the same endpoint address for both. (By "different WSDL document" we mean that both documents are never included or imported into the same WSDL 2.0 descriptions component.) Although this approach may work in some circumstances, it means that the same endpoint address would be used for two different purposes, which is apt to cause confusion or ambiguity. Furthermore, it is contrary to the Web architectura principle that different URIs should be used to identify different Web resources. (See the Web Architecture <bibref ref="webarch"/> section on <xspecref href="http://www.w3.org/TR/webarch/#URI-collision">URI collision</xspecref>.)</p></item><item><p><b>Use inheritance to combine the customer interface and management interface</b> into a single, larger wsdl:interface. Of course, this reduces modularity and means that the management interface becomes exposed to the customers, which is not good. </p></item></ulist></p><p>Bear in mind that since the above strategies step outside of the WSDL 2.0 language specifies (and are therefore neither endorsed nor forbidden by the WSDL 2.0 specification) the WSDL 2.0 specification cannot define or standardize their semantics. </p><p>The desire to express relationships between services is also relevant to Web service versioning, discussed next.</p>
</div2><div2 id="adv-versioning">
<head>Web Service Versioning</head>
--- 1597,1601 ----
<head>Multiple Interfaces for the Same Service</head>
<p>Suppose a Web service wishes to expose two different interfaces: a customer interface for its regular users, and a management interface for its operator. A <code>wsdl:service</code> specifies only one wsdl:interface, so to achieve the desired effect the service provider would somehow need to indicate a relationship between two services. How can a service provider indicate a relationship between services? Potential strategies include:<ulist><item><p><b>Declare both interfaces in the same wsdl:description element.</b> Although WSDL 2.0 does not ascribe any particular significance to the fact that two wsdl:services are declared within the same wsdl:description, an application or toolkit could interpret this to mean that they are related in some way.</p></item><item><p><b>Declare both interfaces in the same wsdl:targetNamespace.</b> Again, although WSDL 2.0 does not ascribe any particular significance to the fact that two wsdl:services are declared within the same wsdl:targetNamespace, an appliction or toolkit could interpret this to mean that they are related in some way.
! </p></item><item><p><b>Add an extension to WSDL 2.0</b> that links together all services that are related in this way. WSDL 2.0's open content model permits extension elements from other namespaces to appear in a WSDL 2.0 document.</p></item><item><p><b>Declare them in completely separate WSDL 2.0 documents, but use the same endpoint address for both.</b> I.e., declare a <code>wsdl:interface</code> and <code>wsdl:service</code> for the customer interface in one WSDL 2.0 document, and a <code>wsdl:interface</code> and <code>wsdl:service</code> for the management interface in a different WSDL 2.0 document, but use the same endpoint address for both. (By "different WSDL 2.0 document" we mean that both documents are never included or imported into the same WSDL 2.0 descriptions component.) Although this approach may work in some circumstances, it means that the same endpoint address would be used for two different purposes, which is apt to cause confusion or ambiguity. Furthermore, it is contrary to the eb architectural principle that different URIs should be used to identify different Web resources. (See the Web Architecture <bibref ref="webarch"/> section on <xspecref href="http://www.w3.org/TR/webarch/#URI-collision">URI collision</xspecref>.)</p></item><item><p><b>Use inheritance to combine the customer interface and management interface</b> into a single, larger wsdl:interface. Of course, this reduces modularity and means that the management interface becomes exposed to the customers, which is not good. </p></item></ulist></p><p>Bear in mind that since the above strategies step outside of the WSDL 2.0 language specifies (and are therefore neither endorsed nor forbidden by the WSDL 2.0 specification) the WSDL 2.0 specification cannot define or standardize their semantics. </p><p>The desire to express relationships between services is also relevant to Web service versioning, discussed next.</p>
</div2><div2 id="adv-versioning">
<head>Web Service Versioning</head>
***************
*** 1574,1578 ****
evolution of messages.</p></item>
<item><p>The protocol used to exchange messages may provide mechanisms for exchanging
! data outside of the message body. In the case of SOAP, the WSDL binding
provides the ability to describe application data to be exchanged as headers. The
SOAP processing model has a very good extensibility model with unknown headers
--- 1639,1643 ----
evolution of messages.</p></item>
<item><p>The protocol used to exchange messages may provide mechanisms for exchanging
! data outside of the message body. In the case of SOAP, the WSDL 2.0 binding
provides the ability to describe application data to be exchanged as headers. The
SOAP processing model has a very good extensibility model with unknown headers
***************
*** 1760,1764 ****
<head>RPC Style</head>
<p>Section <specref ref="more-interfaces-op-attr"/> mentioned that the (optional) <code>style</code> attribute of an interface operation is used to indicate that the operation conforms to a particular pre-defined operation style, or set of constraints. Actually, if desired the <code>style</code> attribute can hold a list of URIs, indicating that the operation simultaneously conforms to multiple styles.</p><p>Operation styles are named using URIs, in order to be unambiguous while still permitted new styles to be defined without requiring updates to the WSDL 2.0 language. WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/> defines three such operation styles; one of these is the RPC Style (<xspecref href="http://www.w3.org/2002/ws/desc/wsdl20-adjuncts#RPCStyle">RPC Style</xspecref>).</p><p>The <emph>RPC Style</emph> is designed to facilitate programming language
! bindings to WSDL 2.0 constructs. It allows a WSDL 2.0 interface
operation to be easily mapped to a method or function signature, such as a method signature in
Java(TM) or C#. RPC Style is restricted to operations that use the In-Out or In-Only MEPs (see <specref ref="more-interfaces-meps"/>).</p><p>A WSDL 2.0 document makes use of the RPC Style in an interface operation by first defining the operation in conformance with all of the RPC Style rules, and then setting that operation's <code>style</code> attribute to include the URI that identifies the RPC Style, thus asserting that the operation does indeed conform to the RPC Style. These rules permit the input and output message schemas to map conveniently to inputs and outputs of a method signature. Roughly, input elements map to input parameters, output elements map to output parameters, and elements that appear both in the input and output message schemas map to input/output parameters. WSDL 2.0 Part 2 section "<xspecref href="http://www.w3.org/2002/ws/desc/wsdl20-adjuncts#RPCStyle">RPC Style</xspecref>" provides full details of the mapping rules and requirements.</p><p>The RPC Style also permits the ful signature of the intended mapping to be indicated explicitly, using the <code>wrpc:signature</code> attribute defined in WSDL 2.0 Part 2 section "<xspecref href="http://www.w3.org/2002/ws/desc/wsdl20-adjuncts">wrpc:signature Extension</xspecref>". This is an (optional) extension to the WSDL 2.0 language whose value designates how input and output message schema elements map to input and output parameters in the method signature. </p><p>The example below illustrates how RPC Style may be used to designate a
--- 1825,1829 ----
<head>RPC Style</head>
<p>Section <specref ref="more-interfaces-op-attr"/> mentioned that the (optional) <code>style</code> attribute of an interface operation is used to indicate that the operation conforms to a particular pre-defined operation style, or set of constraints. Actually, if desired the <code>style</code> attribute can hold a list of URIs, indicating that the operation simultaneously conforms to multiple styles.</p><p>Operation styles are named using URIs, in order to be unambiguous while still permitted new styles to be defined without requiring updates to the WSDL 2.0 language. WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/> defines three such operation styles; one of these is the RPC Style (<xspecref href="http://www.w3.org/2002/ws/desc/wsdl20-adjuncts#RPCStyle">RPC Style</xspecref>).</p><p>The <emph>RPC Style</emph> is designed to facilitate programming language
! bindings to WSDL 2.0 constructs. It allows a WSDL 2.0 interface
operation to be easily mapped to a method or function signature, such as a method signature in
Java(TM) or C#. RPC Style is restricted to operations that use the In-Out or In-Only MEPs (see <specref ref="more-interfaces-meps"/>).</p><p>A WSDL 2.0 document makes use of the RPC Style in an interface operation by first defining the operation in conformance with all of the RPC Style rules, and then setting that operation's <code>style</code> attribute to include the URI that identifies the RPC Style, thus asserting that the operation does indeed conform to the RPC Style. These rules permit the input and output message schemas to map conveniently to inputs and outputs of a method signature. Roughly, input elements map to input parameters, output elements map to output parameters, and elements that appear both in the input and output message schemas map to input/output parameters. WSDL 2.0 Part 2 section "<xspecref href="http://www.w3.org/2002/ws/desc/wsdl20-adjuncts#RPCStyle">RPC Style</xspecref>" provides full details of the mapping rules and requirements.</p><p>The RPC Style also permits the ful signature of the intended mapping to be indicated explicitly, using the <code>wrpc:signature</code> attribute defined in WSDL 2.0 Part 2 section "<xspecref href="http://www.w3.org/2002/ws/desc/wsdl20-adjuncts">wrpc:signature Extension</xspecref>". This is an (optional) extension to the WSDL 2.0 language whose value designates how input and output message schema elements map to input and output parameters in the method signature. </p><p>The example below illustrates how RPC Style may be used to designate a
***************
*** 1841,1845 ****
<head>Enabling Easy Message Dispatch</head>
<p>Suppose a WSDL 2.0 document has two input-output operations and uses the same input message schema for both. When the service receives the input message, how will the service know which operation is supposed to be invoked? Although the data contained in a runtime message may be sufficient to distinguish between the operations, this can be a problem for WSDL 2.0 toolkits that are looking only at the message schema, rather than the actual messages. (For example, the toolkit may be operating at design time, without access to the runtime messages.) This is the problem of <emph>dispatch</emph>. How can a WSDL 2.0 document be written to ensure easy message dispatch? Strategies include:</p>
! <ulist><item><p><b>Use unique top-level elements</b>, i.e., ensure that the top-level elements declared in the message schemas are different for different operations. This is probably the most general solution, since it is guaranteed to provide a way to perform dispatch, without preventing toolkits from potentially using other dispatch techniques.</p></item><item><p><b>Include a required extension</b> that enables a particular dispatching convention. This approach makes the dispatching convention explicit, although it may not be supported by every WSDL toolkit. However, as explained in <specref ref="adv-optional-versus-required"/>, toolkits that do not natively support the extension could seek manual input, thus permitting a client developer to supply an appropriate module that implements the necessary extension. This strategy has thus permits future WSDL toolkits to support and process the extension automatically, while also ensuring that the extension will be handled properly by toolkits that re not yet able to process it automatically.</p></item></ulist>
<p>To ensure that client and service implementations can easily determine the interface operation under which a received message was sent (even though not every client or service may need to make such a determination), it is considered good practice to follow one of the above strategies when authoring WSDL 2.0 documents.</p>
</div2>
--- 1906,1910 ----
<head>Enabling Easy Message Dispatch</head>
<p>Suppose a WSDL 2.0 document has two input-output operations and uses the same input message schema for both. When the service receives the input message, how will the service know which operation is supposed to be invoked? Although the data contained in a runtime message may be sufficient to distinguish between the operations, this can be a problem for WSDL 2.0 toolkits that are looking only at the message schema, rather than the actual messages. (For example, the toolkit may be operating at design time, without access to the runtime messages.) This is the problem of <emph>dispatch</emph>. How can a WSDL 2.0 document be written to ensure easy message dispatch? Strategies include:</p>
! <ulist><item><p><b>Use unique top-level elements</b>, i.e., ensure that the top-level elements declared in the message schemas are different for different operations. This is probably the most general solution, since it is guaranteed to provide a way to perform dispatch, without preventing toolkits from potentially using other dispatch techniques.</p></item><item><p><b>Include a required extension</b> that enables a particular dispatching convention. This approach makes the dispatching convention explicit, although it may not be supported by every WSDL 2.0 toolkit. However, as explained in <specref ref="adv-optional-versus-required"/>, toolkits that do not natively support the extension could seek manual input, thus permitting a client developer to supply an appropriate module that implements the necessary extension. This strategy has thus permits future WSDL 2.0 toolkits to support and process the extension automatically, while also ensuring that the extension will be handled properly by toolkis that are not yet able to process it automatically.</p></item></ulist>
<p>To ensure that client and service implementations can easily determine the interface operation under which a received message was sent (even though not every client or service may need to make such a determination), it is considered good practice to follow one of the above strategies when authoring WSDL 2.0 documents.</p>
</div2>
***************
*** 2083,2087 ****
operations. In addition, the schema defines two
<emph>restrictions</emph>
! of WSDL complex types. The
<code>ReservationDetailsEndpointType</code>
complex type restricts the
--- 2148,2152 ----
operations. In addition, the schema defines two
<emph>restrictions</emph>
! of WSDL 2.0 complex types. The
<code>ReservationDetailsEndpointType</code>
complex type restricts the
***************
*** 2158,2162 ****
reservations are made and cancelled, the
Reservation Detail endpoints are not described
! in a fixed WSDL document. Instead they are
returned as endpoint references in response to
requests made on a Reservation List Web service.
--- 2223,2227 ----
reservations are made and cancelled, the
Reservation Detail endpoints are not described
! in a fixed WSDL 2.0 document. Instead they are
returned as endpoint references in response to
requests made on a Reservation List Web service.
***************
*** 2539,2544 ****
</element>]]>
</eg>
! </example><p>The WSDL service that offers this type serialized as a parameter would look like this:</p><example id="example_reservationList_HTTP_GET_single_wsdl">
! <head>WSDL for Using a Single Query Type</head>
<eg>
<![CDATA[. . .
--- 2604,2609 ----
</element>]]>
</eg>
! </example><p>The WSDL 2.0 service that offers this type serialized as a parameter would look like this:</p><example id="example_reservationList_HTTP_GET_single_wsdl">
! <head>WSDL 2.0 for Using a Single Query Type</head>
<eg>
<![CDATA[. . .
***************
*** 2609,2613 ****
<code>updateDetails.wsdl</code>
WSDL 2.0 document which imports the first document
! and refers to both WSDL and schema definitions
contained in the imported document.
</p>
--- 2674,2678 ----
<code>updateDetails.wsdl</code>
WSDL 2.0 document which imports the first document
! and refers to both WSDL 2.0 and schema definitions
contained in the imported document.
</p>
***************
*** 2732,2738 ****
element has been omitted. The
<code>schemaLocation</code>
! attribute is a hint to the WSDL processor that tells it where to
look for the imported schema namespace.
! However, the WSDL processor has already
processed the
<code>retrieveDetails.wsdl</code>
--- 2797,2803 ----
element has been omitted. The
<code>schemaLocation</code>
! attribute is a hint to the WSDL 2.0 processor that tells it where to
look for the imported schema namespace.
! However, the WSDL 2.0 processor has already
processed the
<code>retrieveDetails.wsdl</code>
***************
*** 2823,2828 ****
<code>schemaLocation</code>
attribute is not required in this case since the
! WSDL processor knows the location of each schema
! by virtue of having processed the enclosing WSDL
document.
</p>
--- 2888,2893 ----
<code>schemaLocation</code>
attribute is not required in this case since the
! WSDL 2.0 processor knows the location of each schema
! by virtue of having processed the enclosing WSDL 2.0
document.
</p>
***************
*** 2931,2936 ****
<specref ref="updateDetails.wsdl"/> shows how one WSDL 2.0 document imports a schema defined in another, i.e. <specref ref="retrieveDetails.wsdl"/>.
Similarly, <specref ref="retrieveItems.wsdl"/> shows how one schema in a WSDL 2.0 document imports another schema defined in the same document.
! In both of these examples, the <code>schemaLocation</code> attribute was omitted since the WSDL processor was assumed to know how to locate the imported
! schemas because they were part of the WSDL documents being processed. The <code>schemaLocation</code> attribute can be used to give the processor a URI reference
that explicitly locates the schemas. A URI reference is a URI plus an optional fragment identifier that indicates part of the resource. For schemas, the fragment should identify
the <code>schema</code> element. The simplest way to accomplish this is to use the <code>id</code> attribute, however XPointer (see <bibref ref="XPTR"/>) can also be used.
--- 2996,3001 ----
<specref ref="updateDetails.wsdl"/> shows how one WSDL 2.0 document imports a schema defined in another, i.e. <specref ref="retrieveDetails.wsdl"/>.
Similarly, <specref ref="retrieveItems.wsdl"/> shows how one schema in a WSDL 2.0 document imports another schema defined in the same document.
! In both of these examples, the <code>schemaLocation</code> attribute was omitted since the WSDL 2.0 processor was assumed to know how to locate the imported
! schemas because they were part of the WSDL 2.0 documents being processed. The <code>schemaLocation</code> attribute can be used to give the processor a URI reference
that explicitly locates the schemas. A URI reference is a URI plus an optional fragment identifier that indicates part of the resource. For schemas, the fragment should identify
the <code>schema</code> element. The simplest way to accomplish this is to use the <code>id</code> attribute, however XPointer (see <bibref ref="XPTR"/>) can also be used.
***************
*** 3032,3036 ****
in different targetNamespaces to be merged into a single (physical) XML document. </p></item><item><p>The ability to extend XML languages with other XML languages depends on the
languages again. WSDL 2.0 is extremely extensible, but the meaning
! of every single extension in WSDL must be defined explicitly. Putting a
piece of XMI (XML format for UML) into a WSDL 2.0 document may have
different meaning from putting it into an XHTML document.
--- 3097,3101 ----
in different targetNamespaces to be merged into a single (physical) XML document. </p></item><item><p>The ability to extend XML languages with other XML languages depends on the
languages again. WSDL 2.0 is extremely extensible, but the meaning
! of every single extension in WSDL 2.0 must be defined explicitly. Putting a
piece of XMI (XML format for UML) into a WSDL 2.0 document may have
different meaning from putting it into an XHTML document.
***************
*** 3076,3080 ****
There can be multiple schemas associated with a particular
namespace, and it is up to a processor of XML to determine
! which one to use in a particular processing context. The WSDL
specification provides the processing context here via the
<att>import</att> mechanism, which is based on XML
--- 3141,3145 ----
There can be multiple schemas associated with a particular
namespace, and it is up to a processor of XML to determine
! which one to use in a particular processing context. The WSDL 2.0
specification provides the processing context here via the
<att>import</att> mechanism, which is based on XML
***************
*** 3166,3170 ****
"RFC 3023: XML Media Types", M. Murata, S. St. Laurent, D. Kohn, July
1998.</bibl>
! <bibl key="WSDL MediaType" id="wsdl-media-type">IETF Internet Draft "The 'application/wsdl+xml' media type",
@@@. (Work to be done once we have consensus on the media type).</bibl>
<!--
--- 3231,3235 ----
"RFC 3023: XML Media Types", M. Murata, S. St. Laurent, D. Kohn, July
1998.</bibl>
! <bibl key="WSDL 2.0 MediaType" id="wsdl-media-type">IETF Internet Draft "The 'application/wsdl+xml' media type",
@@@. (Work to be done once we have consensus on the media type).</bibl>
<!--
Index: wsdl20.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20.html,v
retrieving revision 1.201
retrieving revision 1.202
diff -C2 -d -r1.201 -r1.202
*** wsdl20.html 15 Jun 2005 22:33:09 -0000 1.201
--- wsdl20.html 16 Jun 2005 00:34:47 -0000 1.202
***************
*** 1,15 ****
! <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
! "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
! <html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
! <head>
! <meta name="generator" content=
! "HTML Tidy for Linux/x86 (vers 1st February 2005), see www.w3.org" />
! <meta http-equiv="Content-Type" content=
! "text/html; charset=utf-8" />
! <title>Web Services Description Language (WSDL) Version 2.0 Part 1:
! Core Language</title>
[...21541 lines suppressed...]
! <tr>
! <td rowspan="1" colspan="1">20020620</td>
! <td rowspan="1" colspan="1">SW</td>
! <td rowspan="1" colspan="1">Started adding abstract model</td>
! </tr>
! <tr>
! <td rowspan="1" colspan="1">20020406</td>
! <td rowspan="1" colspan="1">SW</td>
! <td rowspan="1" colspan="1">Created document from WSDL 1.1</td>
! </tr>
! </tbody>
! </table><br>
!
! </div>
! </div>
!
! </div>
!
! </body></html>
\ No newline at end of file
Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.66
retrieving revision 1.67
diff -C2 -d -r1.66 -r1.67
*** wsdl20-primer.html 14 Jun 2005 22:39:19 -0000 1.66
--- wsdl20-primer.html 16 Jun 2005 00:34:47 -0000 1.67
***************
*** 1,3 ****
! <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Web Services Description Language (WSDL) Version 2.0 Part 0: Primer</title><style type="text/css">
code { font-family: monospace; }
--- 1,3 ----
! <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Web Services Description Language (WSDL) Version 2.0 Part 0: Primer</title><style type="text/css">
code { font-family: monospace; }
***************
*** 45,49 ****
div.exampleHeader { font-weight: bold;
[...1369 lines suppressed...]
<code>import</code> mechanism, which is based on XML
--- 3225,3229 ----
There can be multiple schemas associated with a particular
namespace, and it is up to a processor of XML to determine
! which one to use in a particular processing context. The WSDL 2.0
specification provides the processing context here via the
<code>import</code> mechanism, which is based on XML
***************
*** 3254,3258 ****
"RFC 3023: XML Media Types", M. Murata, S. St. Laurent, D. Kohn, July
1998. (See <cite><a href="http://www.ietf.org/rfc/rfc3023.txt">http://www.ietf.org/rfc/rfc3023.txt</a></cite>.)</dd>
! <dt class="label"><a name="wsdl-media-type"></a>[WSDL MediaType] </dt><dd>IETF Internet Draft "The 'application/wsdl+xml' media type",
@@@. (Work to be done once we have consensus on the media type).</dd>
--- 3319,3323 ----
"RFC 3023: XML Media Types", M. Murata, S. St. Laurent, D. Kohn, July
1998. (See <cite><a href="http://www.ietf.org/rfc/rfc3023.txt">http://www.ietf.org/rfc/rfc3023.txt</a></cite>.)</dd>
! <dt class="label"><a name="wsdl-media-type"></a>[WSDL 2.0 MediaType] </dt><dd>IETF Internet Draft "The 'application/wsdl+xml' media type",
@@@. (Work to be done once we have consensus on the media type).</dd>
Received on Thursday, 16 June 2005 00:35:09 UTC