W3C home > Mailing lists > Public > public-ws-desc-eds@w3.org > April 2005

2002/ws/desc/wsdl20 wsdl20-primer.html,1.49,1.50 wsdl20-primer.xml,1.69,1.70

From: Kevin Liu via cvs-syncmail <cvsmail@w3.org>
Date: Thu, 28 Apr 2005 22:43:09 +0000
To: public-ws-desc-eds@w3.org
Message-Id: <E1DRHiv-0007U4-R7@lionel-hutz.w3.org>

Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv28764/ws/desc/wsdl20

Modified Files:
	wsdl20-primer.html wsdl20-primer.xml 
Log Message:
editorial changes to the basic examples for consistency. minor editings.

Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.69
retrieving revision 1.70
diff -C2 -d -r1.69 -r1.70
*** wsdl20-primer.xml	28 Apr 2005 00:29:32 -0000	1.69
--- wsdl20-primer.xml	28 Apr 2005 22:43:07 -0000	1.70
***************
*** 231,235 ****
      . . . >
  
!   , , ,
  
    <types>
--- 231,235 ----
      . . . >
  
!   ...
  
    <types>
***************
*** 256,260 ****
    . . .
  </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>, eac 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-PART2"/> section  2.2.3 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#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).</p><p>For the GreatH service, we will (initially) define an interface containing a single operation, <code>opCheckAvailability</code>, using  the <code>checkAvilability</code> and <code>checkAvailabilityResponse</code> message types that we defined in the <code>types</code> section.   We'll use the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#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="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-only</xspecref> and <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#out-only">out-only</xspecref> patterns (see <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section  2.2.1 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-only">In-Only</xspecref> and section  2.2.5 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#out-only">Out-Only</xspecref>), but that would just complicate matters for the client,because 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>
  					
--- 256,264 ----
    . . .
  </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="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#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="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#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="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-only</xspecref> and <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#out-only">out-only</xspecref> patterns (see <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section  2.2.1 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-only">In-Only</xspecref> and section  2..5 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#out-only">Out-Only</xspecref>), but that would just complicate matters for the client, because 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>
  					
***************
*** 269,285 ****
    . . .
    <types>
!     <xs:schema 
!         xmlns:xs="http://www.w3.org/2001/XMLSchema"
!         targetNamespace="http://greath.example.com/2004/schemas/resSvc"
!         xmlns="http://greath.example.com/2004/schemas/resSvc">
! 
!       <xs:element name="checkAvailability" type="tCheckAvailability"/>    
!         . . .
!             
!       <xs:element name="checkAvailabilityResponse" type="xs:double"/>    
!     
!       <xs:element name="invalidDataError" type="xs:string"/>    
! 
!     </xs:schema>    
    </types>
    
--- 273,277 ----
    . . .
    <types>
! 	...
    </types>
    
***************
*** 384,396 ****
    
    <interface  name = "reservationInterface" >
! 
!     <fault name = "invalidDataFault"
!             element = "ghns:invalidDataError"/> 
!    
!     <operation name="opCheckAvailability" 
!             pattern="http://www.w3.org/2004/03/wsdl/in-out" >
!        . . .
!     </operation>
! 
    </interface>
  
--- 376,380 ----
    
    <interface  name = "reservationInterface" >
! 	...
    </interface>
  
***************
*** 459,463 ****
                 address ="http://greath.example.com/2004/reservation"/>
          
!   </service>]]></eg>
  				</example><div3 id="example-initial-service-explanation"><head>Explanation of Example</head><glist><gitem><label><code>&lt;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"&gt;</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>&lt;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"/&gt;</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>
  				
--- 443,449 ----
                 address ="http://greath.example.com/2004/reservation"/>
          
!   </service>
!   
! </description>]]></eg>
  				</example><div3 id="example-initial-service-explanation"><head>Explanation of Example</head><glist><gitem><label><code>&lt;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"&gt;</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>&lt;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"/&gt;</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>
  				
***************
*** 474,482 ****
      at http://greath.example.com/2004/reservation-documentation.html
    </documentation>
- 
-   <types>
-     . . .
-   </types>
- 
    . . .  
  </description>]]></eg>
--- 460,463 ----
***************
*** 510,514 ****
  <head>WSDL 2.0 Schema and Element Ordering</head>
  
! <p>The WSDL 2.0 specification supplies a normative WSDL 2.0 schema @@ToDo: Add reference@@, defined in XML Schema <bibref ref="XMLSchemaP1"/> <bibref ref="XMLSchemaP2"/>, which can be used as an aid in validating WSDL 2.0 documents.  Although the WSDL 2.0 schema does not indicate the required ordering of elements, the WSDL 2.0 specification (WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="http://www.w3.org/TR/wsdl20-primer#Description_XMLRep">XML Representation of Description Component</xspecref>") clearly states a set of constraints about how the children elements of the <code>description</code> element should be ordered. Thus, the order of the WSDL 2.0 elements matters, in spite of what the WSDL 2.0 schema says. </p><p>The following is a pseudo-content model of <code>description</code>.</p>
  
  <eg xml:space="preserve">
--- 491,495 ----
  <head>WSDL 2.0 Schema and Element Ordering</head>
  
! <p>The WSDL 2.0 specification supplies a normative WSDL 2.0 schema  @@ToDo: add reference to wsdl schema when publish@@, defined in XML Schema <bibref ref="XMLSchemaP1"/> <bibref ref="XMLSchemaP2"/>, which can be used as an aid in validating WSDL 2.0 documents.  Although the WSDL 2.0 schema does not indicate the required ordering of elements, the WSDL 2.0 specification (WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="http://www.w3.org/TR/wsdl20-primer#Description_XMLRep">XML Representation of Description Component</xspecref>") clearly states a set of constraints about how the children elements of the <code>description</code> element should be ordered. Thus, the order of the WSDL 2.0 elements matters, in spite of what the WSDL 2.0 schema says. </p><p>The following is a pseudo-content model of <code>description</code>.</p>
  
  <eg xml:space="preserve">

Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.49
retrieving revision 1.50
diff -C2 -d -r1.49 -r1.50
*** wsdl20-primer.html	28 Apr 2005 00:29:32 -0000	1.49
--- wsdl20-primer.html	28 Apr 2005 22:43:07 -0000	1.50
***************
*** 94,99 ****
  	<hr><div class="toc">
  <h2><a name="shortcontents">Short Table of Contents</a></h2><p class="toc">1. <a href="#Introduction">Introduction</a><br>2. <a href="#basics">WSDL 2.0 Basics</a><br>3. <a href="#wsdl-xml-representation">WSDL 2.0 Infoset, Schema and Component Model</a><br>4. <a href="#more-types">More on Message Types</a><br>5. <a href="#more-interfaces">More on Interfaces</a><br>6. <a href="#more-bindings">More on Bindings</a><br>7. <a href="#advanced-topic_ii">Advanced Topics</a><br>8. <a href="#References">References</a><br></p></div><hr><div class="toc">
! <h2><a name="contents">Table of Contents</a></h2><p class="toc">1. <a href="#Introduction">Introduction</a><br>&nbsp;&nbsp;&nbsp;&nbsp;1.1 <a href="#Prerequisites">Prerequisites</a><br>&nbsp;&nbsp;&nbsp;&nbsp;1.2 <a href="#PrimerStructure">Structure of this Primer</a><br>&nbsp;&nbsp;&nbsp;&nbsp;1.3 <a href="#notation">Notational Conventions</a><br>2. <a href="#basics">WSDL 2.0 Basics</a><br>&nbsp;&nbsp;&nbsp;&nbsp;2.1 <a href="#basics-greath-scenario">Example Scenario: The GreatH Hotel Reservation Service</a><br>&nbsp;&nbsp;&nbsp;&nbsp;2.2 <a href="#basics-getting-started">Getting Started: Defining a WSDL Target Namespace</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2.2.1 <a href="#example-empty-shell-explanation">Explanation of Example</a><br>&nbsp;&nbsp;&nbsp;&nbsp;2.3 <a href="#basics-types">Defining Message Types</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2.3.1 <a href="#example-initial-types-explanation">Explanation of Example</a><br>&nbsp;&nbsp;&nbsp;&nbsp;2.4 <a href="#basics-nterface">Defining an Interface</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2.4.1 <a href="#example-initial-interface-explanation">Explanation of Example</a><br>&nbsp;&nbsp;&nbsp;&nbsp;2.5 <a href="#basics-binding">Defining a Binding</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2.5.1 <a href="#example-initial-binding-explanation">Explanation of Example</a><br>&nbsp;&nbsp;&nbsp;&nbsp;2.6 <a href="#basics-service">Defining a Service</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2.6.1 <a href="#example-initial-service-explanation">Explanation of Example</a><br>&nbsp;&nbsp;&nbsp;&nbsp;2.7 <a href="#basics-documentation">Documenting the Service</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2.7.1 <a href="#example-initial-documentation-explanation">Explanation of Example</a><br>3. <a href="#wsdl-xml-representation">WSDL 2.0 Infoset, Schema and Component Model</a><br>&nbsp;&nbsp;&nbsp;&nbsp;3.1 <a href="#wsdl-infoset-diagram">WSDL 2.0 Infoset</a><br>&nbsp;&nbsp;&nbsp;&nbsp;3. <a href="#wsdl-schema">WSDL 2.0 Schema and Element Ordering</a><br>&nbsp;&nbsp;&nbsp;&nbsp;3.3 <a href="#component-model">WSDL 2.0 Component Model</a><br>4. <a href="#more-types">More on Message Types</a><br>&nbsp;&nbsp;&nbsp;&nbsp;4.1 <a href="#more-types-schema-embed">Embedding XML Schema</a><br>&nbsp;&nbsp;&nbsp;&nbsp;4.2 <a href="#more-types-schema-import">Importing XML Schema</a><br>&nbsp;&nbsp;&nbsp;&nbsp;4.3 <a href="#more-types-import-include-summary">Summary of Import and Include Mechanisms</a><br>5. <a href="#more-interfaces">More on Interfaces</a><br>&nbsp;&nbsp;&nbsp;&nbsp;5.1 <a href="#more-interfaces-interfaces">Interface Syntax </a><br>&nbsp;&nbsp;&nbsp;&nbsp;5.2 <a href="#more-interfaces-inheritance">Interface Inheritance</a><br>&nbsp;&nbsp;&nbsp;&nbsp;5.3 <a href="#more-interfaces-faults">Interface Faults</a><br>&nbsp;&nbsp;&nbsp;&nbsp;5.4 <a href="#more-interfaces-operations">Interface Operations</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.4.1 <a href="#more-interfaces-op-att">Operation Attributes</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.4.2 <a href="#N1089B">Operation Message References</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.4.2.1 <a href="#N108B8">The messageLabel Attribute</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.4.2.2 <a href="#N108CC">The element Attribute</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.4.2.3 <a href="#N108F3">Multiple infault or outfault Elements</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.4.3 <a href="#more-interfaces-meps">Understanding Message Exchange Patterns (MEPs)</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.4.4 <a href="#more-interfaces-defining-meps">Defining New Message Exchange Patterns (MEPs)</a><br>6. <a href="#more-bindings">More on Bindings</a><br>&nbsp;&nbsp;&nbsp;&nbsp;6.1 <a href="#more-bindings-wsdl">Syntax Summary for Bindings</a><br>&nbsp;&nbsp;&nbsp;&nbsp;6.2 <a href="#more-bindins-reusable">Reusable Bindings</a><br>&nbsp;&nbsp;&nbsp;&nbsp;6.3 <a href="#more-bindings-faults">Binding Faults</a><br>&nbsp;&nbsp;&nbsp;&nbsp;6.4 <a href="#bindingOperations">Binding Operations</a><br>&nbsp;&nbsp;&nbsp;&nbsp;6.5 <a href="#more-bindings-soap">The SOAP Binding Extension</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;6.5.1 <a href="#more-bindings-soap-example-explanation">Explanation of Example</a><br>&nbsp;&nbsp;&nbsp;&nbsp;6.6 <a href="#more-bindings-http">The HTTP Binding Extension</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;6.6.1 <a href="#N10AB7">Explanation of
! 			Example</a><br>&nbsp;&nbsp;&nbsp;&nbsp;6.7 <a href="#adv-get-vs-post">HTTP GET Versus POST: Which to Use?</a><br>7. <a href="#advanced-topic_ii">Advanced Topics</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.1 <a href="#adv-extensibility">Extensibility</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.1.1 <a href="#adv-optional-versus-required">Optional Versus Required Extensions</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.1.2 <a href="#adv-scope-of-wsdl-required">Scoping of the wsdl:required Attribute</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.2 <a href="#adv-FP">Features and Properties</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.2.1 <a href="#adv-FP-soap-modules">SOAP Modules</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.2.2 <a href="#adv-FP-abstract-features">Abstract Features</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.2.3 <a href="#adv-fp-properties">Properties</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.3 <a href="#adv-import-and-authoring">Import mechanism and authoring stye</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.4 <a href="#adv-multiple-docs-describing-same-service">Multiple Interfaces for the Same Service</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.5 <a href="#adv-versioning">Web Service Versioning</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.5.1 <a href="#adv-versioning-compatible-evolution">Compatible Evolution</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.5.2 <a href="#adv-versioning-big-bang">Big Bang</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.5.3 <a href="#adv-versioning-combined">Combined Approaches</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.6 <a href="#adv-MTOM">MTOM Support</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.7 <a href="#adv-RPCstyle">RPC Style</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.8 <a href="#adv-message-dispatch">Enabling Easy Message Dispatch</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.9 <a href="#adv-service-references">Service References</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.9.1 <a href="#reservationDetails">The Reservation Details Web Service</a><br>nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.9.2 <a href="#reservationList">The Reservation List Web Service</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.9.3 <a href="#reservationDetails_HTTP">Reservation Details Web Service Using HTTP Transfer</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.9.4 <a href="#reservationList_HTTP_GET">Reservation List Web Service Using HTTP GET</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.10 <a href="#adv-multiple-inline-schemas">Importing Schemas</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.10.1 <a href="#N10FC7">Schemas in Imported Documents</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.10.2 <a href="#N11052">Multiple Inline Schemas in One Document</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.10.3 <a href="#adv-schema-location">The schemaLocation Attribute</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.10.3.1 <a href="#N110AF">Using the id Attribute to Identify Inline
  						Schemas</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.11 <a href="#adv-rdf-mapping">Mapping to RDF and Semantic Web</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.11.1 <a href="#adv-rdf-rep-wsdl">RDF Representation of WSDL 2.0</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.12 <a href="#adv-notes-on-uris">Notes on URIs</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.12.1 <a href="#adv-namespaces-and-schema-locations">XML Namespaces and Schema Locations</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.12.2 <a href="#adv-relative-uris">Relative URIs</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.12.3 <a href="#adv-generating-uris">Generating Temporary URIs</a><br>8. <a href="#References">References</a><br>&nbsp;&nbsp;&nbsp;&nbsp;8.1 <a href="#Normative-References">Normative References</a><br>&nbsp;&nbsp;&nbsp;&nbsp;8.2 <a href="#Informative-References">Informative References</a><br></p></div><hr><div class="body">
  		
--- 94,99 ----
  	<hr><div class="toc">
  <h2><a name="shortcontents">Short Table of Contents</a></h2><p class="toc">1. <a href="#Introduction">Introduction</a><br>2. <a href="#basics">WSDL 2.0 Basics</a><br>3. <a href="#wsdl-xml-representation">WSDL 2.0 Infoset, Schema and Component Model</a><br>4. <a href="#more-types">More on Message Types</a><br>5. <a href="#more-interfaces">More on Interfaces</a><br>6. <a href="#more-bindings">More on Bindings</a><br>7. <a href="#advanced-topic_ii">Advanced Topics</a><br>8. <a href="#References">References</a><br></p></div><hr><div class="toc">
! <h2><a name="contents">Table of Contents</a></h2><p class="toc">1. <a href="#Introduction">Introduction</a><br>&nbsp;&nbsp;&nbsp;&nbsp;1.1 <a href="#Prerequisites">Prerequisites</a><br>&nbsp;&nbsp;&nbsp;&nbsp;1.2 <a href="#PrimerStructure">Structure of this Primer</a><br>&nbsp;&nbsp;&nbsp;&nbsp;1.3 <a href="#notation">Notational Conventions</a><br>2. <a href="#basics">WSDL 2.0 Basics</a><br>&nbsp;&nbsp;&nbsp;&nbsp;2.1 <a href="#basics-greath-scenario">Example Scenario: The GreatH Hotel Reservation Service</a><br>&nbsp;&nbsp;&nbsp;&nbsp;2.2 <a href="#basics-getting-started">Getting Started: Defining a WSDL Target Namespace</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2.2.1 <a href="#example-empty-shell-explanation">Explanation of Example</a><br>&nbsp;&nbsp;&nbsp;&nbsp;2.3 <a href="#basics-types">Defining Message Types</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2.3.1 <a href="#example-initial-types-explanation">Explanation of Example</a><br>&nbsp;&nbsp;&nbsp;&nbsp;2.4 <a href="#basics-nterface">Defining an Interface</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2.4.1 <a href="#example-initial-interface-explanation">Explanation of Example</a><br>&nbsp;&nbsp;&nbsp;&nbsp;2.5 <a href="#basics-binding">Defining a Binding</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2.5.1 <a href="#example-initial-binding-explanation">Explanation of Example</a><br>&nbsp;&nbsp;&nbsp;&nbsp;2.6 <a href="#basics-service">Defining a Service</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2.6.1 <a href="#example-initial-service-explanation">Explanation of Example</a><br>&nbsp;&nbsp;&nbsp;&nbsp;2.7 <a href="#basics-documentation">Documenting the Service</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2.7.1 <a href="#example-initial-documentation-explanation">Explanation of Example</a><br>3. <a href="#wsdl-xml-representation">WSDL 2.0 Infoset, Schema and Component Model</a><br>&nbsp;&nbsp;&nbsp;&nbsp;3.1 <a href="#wsdl-infoset-diagram">WSDL 2.0 Infoset</a><br>&nbsp;&nbsp;&nbsp;&nbsp;3. <a href="#wsdl-schema">WSDL 2.0 Schema and Element Ordering</a><br>&nbsp;&nbsp;&nbsp;&nbsp;3.3 <a href="#component-model">WSDL 2.0 Component Model</a><br>4. <a href="#more-types">More on Message Types</a><br>&nbsp;&nbsp;&nbsp;&nbsp;4.1 <a href="#more-types-schema-embed">Embedding XML Schema</a><br>&nbsp;&nbsp;&nbsp;&nbsp;4.2 <a href="#more-types-schema-import">Importing XML Schema</a><br>&nbsp;&nbsp;&nbsp;&nbsp;4.3 <a href="#more-types-import-include-summary">Summary of Import and Include Mechanisms</a><br>5. <a href="#more-interfaces">More on Interfaces</a><br>&nbsp;&nbsp;&nbsp;&nbsp;5.1 <a href="#more-interfaces-interfaces">Interface Syntax </a><br>&nbsp;&nbsp;&nbsp;&nbsp;5.2 <a href="#more-interfaces-inheritance">Interface Inheritance</a><br>&nbsp;&nbsp;&nbsp;&nbsp;5.3 <a href="#more-interfaces-faults">Interface Faults</a><br>&nbsp;&nbsp;&nbsp;&nbsp;5.4 <a href="#more-interfaces-operations">Interface Operations</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.4.1 <a href="#more-interfaces-op-att">Operation Attributes</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.4.2 <a href="#N108A2">Operation Message References</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.4.2.1 <a href="#N108BF">The messageLabel Attribute</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.4.2.2 <a href="#N108D3">The element Attribute</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.4.2.3 <a href="#N108FA">Multiple infault or outfault Elements</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.4.3 <a href="#more-interfaces-meps">Understanding Message Exchange Patterns (MEPs)</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.4.4 <a href="#more-interfaces-defining-meps">Defining New Message Exchange Patterns (MEPs)</a><br>6. <a href="#more-bindings">More on Bindings</a><br>&nbsp;&nbsp;&nbsp;&nbsp;6.1 <a href="#more-bindings-wsdl">Syntax Summary for Bindings</a><br>&nbsp;&nbsp;&nbsp;&nbsp;6.2 <a href="#more-bindins-reusable">Reusable Bindings</a><br>&nbsp;&nbsp;&nbsp;&nbsp;6.3 <a href="#more-bindings-faults">Binding Faults</a><br>&nbsp;&nbsp;&nbsp;&nbsp;6.4 <a href="#bindingOperations">Binding Operations</a><br>&nbsp;&nbsp;&nbsp;&nbsp;6.5 <a href="#more-bindings-soap">The SOAP Binding Extension</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;6.5.1 <a href="#more-bindings-soap-example-explanation">Explanation of Example</a><br>&nbsp;&nbsp;&nbsp;&nbsp;6.6 <a href="#more-bindings-http">The HTTP Binding Extension</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;6.6.1 <a href="#N10ABE">Explanation of
! 			Example</a><br>&nbsp;&nbsp;&nbsp;&nbsp;6.7 <a href="#adv-get-vs-post">HTTP GET Versus POST: Which to Use?</a><br>7. <a href="#advanced-topic_ii">Advanced Topics</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.1 <a href="#adv-extensibility">Extensibility</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.1.1 <a href="#adv-optional-versus-required">Optional Versus Required Extensions</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.1.2 <a href="#adv-scope-of-wsdl-required">Scoping of the wsdl:required Attribute</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.2 <a href="#adv-FP">Features and Properties</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.2.1 <a href="#adv-FP-soap-modules">SOAP Modules</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.2.2 <a href="#adv-FP-abstract-features">Abstract Features</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.2.3 <a href="#adv-fp-properties">Properties</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.3 <a href="#adv-import-and-authoring">Import mechanism and authoring stye</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.4 <a href="#adv-multiple-docs-describing-same-service">Multiple Interfaces for the Same Service</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.5 <a href="#adv-versioning">Web Service Versioning</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.5.1 <a href="#adv-versioning-compatible-evolution">Compatible Evolution</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.5.2 <a href="#adv-versioning-big-bang">Big Bang</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.5.3 <a href="#adv-versioning-combined">Combined Approaches</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.6 <a href="#adv-MTOM">MTOM Support</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.7 <a href="#adv-RPCstyle">RPC Style</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.8 <a href="#adv-message-dispatch">Enabling Easy Message Dispatch</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.9 <a href="#adv-service-references">Service References</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.9.1 <a href="#reservationDetails">The Reservation Details Web Service</a><br>nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.9.2 <a href="#reservationList">The Reservation List Web Service</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.9.3 <a href="#reservationDetails_HTTP">Reservation Details Web Service Using HTTP Transfer</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.9.4 <a href="#reservationList_HTTP_GET">Reservation List Web Service Using HTTP GET</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.10 <a href="#adv-multiple-inline-schemas">Importing Schemas</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.10.1 <a href="#N10FCE">Schemas in Imported Documents</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.10.2 <a href="#N11059">Multiple Inline Schemas in One Document</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.10.3 <a href="#adv-schema-location">The schemaLocation Attribute</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.10.3.1 <a href="#N110B6">Using the id Attribute to Identify Inline
  						Schemas</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.11 <a href="#adv-rdf-mapping">Mapping to RDF and Semantic Web</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.11.1 <a href="#adv-rdf-rep-wsdl">RDF Representation of WSDL 2.0</a><br>&nbsp;&nbsp;&nbsp;&nbsp;7.12 <a href="#adv-notes-on-uris">Notes on URIs</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.12.1 <a href="#adv-namespaces-and-schema-locations">XML Namespaces and Schema Locations</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.12.2 <a href="#adv-relative-uris">Relative URIs</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7.12.3 <a href="#adv-generating-uris">Generating Temporary URIs</a><br>8. <a href="#References">References</a><br>&nbsp;&nbsp;&nbsp;&nbsp;8.1 <a href="#Normative-References">Normative References</a><br>&nbsp;&nbsp;&nbsp;&nbsp;8.2 <a href="#Informative-References">Informative References</a><br></p></div><hr><div class="body">
  		
***************
*** 256,260 ****
      . . . &gt;
  
!   , , ,
  
    &lt;types&gt;
--- 256,260 ----
      . . . &gt;
  
!   ...
  
    &lt;types&gt;
***************
*** 282,287 ****
  &lt;/description&gt;</pre></div>
  				</div><div class="div3">
! <h4><a name="example-initial-types-explanation"></a>2.3.1 Explanation of Example</h4><dl><dt class="label"><code>xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc"</code></dt><dd><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) -- <em>not</em> the target namespace of the WSDL document itself.</p></dd><dt class="label"><code>targetNamespace="http://greath.example.com/2004/schemas/resSvc"</code></dt><dd><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 namespace.</p></dd><dt class="lael"><code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code></dt><dd><p>These are the message types that we'll use.  Note that these are defined to be XML <em>elements</em>, as explained above.</p></dd></dl><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></div></div><div class="div2">
! <h3><a name="basics-interface"></a>2.4 Defining an Interface</h3><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 <em>operations</em>, 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 <em>pattern</em> that indicates the sequence in which the associated messages are to be transmitted between the parties.   For example, the <em>in-out</em> pattern (see <em>WSDL 2.0 Predefined Extensions</em> [<cite><a href="#WSDL-PART2">WSDL 2.0Adjuncts</a></cite>] section  2.2.3 <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">In-Out</a>) indicates that if the client sends a message <em>in</em> to the service, the service will either send a reply message back <em>out</em> to the client (in the normal case) or it will send a fault message back to the client (in the case of an error).</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 <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</a> 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 <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-ut">in-only</a> and <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#out-only">out-only</a> patterns (see <em>WSDL 2.0 Predefined Extensions</em> [<cite><a href="#WSDL-PART2">WSDL 2.0 Adjuncts</a></cite>] section  2.2.1 <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-only">In-Only</a> and section  2.2.5 <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#out-only">Out-Only</a>), but that would just complicate matters for the client, because 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 messag exchange pattern of the operation.  </p><p>Let's add these to our WSDL document.</p><div class="exampleOuter">
  					<p class="exampleHead" style="text-align: left"><a name="example-initial-interface"></a><i><span>Example 2-4. </span>GreatH Interface Definition</i></p>
  					
--- 282,291 ----
  &lt;/description&gt;</pre></div>
  				</div><div class="div3">
! <h4><a name="example-initial-types-explanation"></a>2.3.1 Explanation of Example</h4><dl><dt class="label"><code>xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc"</code></dt><dd><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) -- <em>not</em> the target namespace of the WSDL document itself.</p></dd><dt class="label"><code>targetNamespace="http://greath.example.com/2004/schemas/resSvc"</code></dt><dd><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 namespace.</p></dd><dt class="lael"><code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code></dt><dd><p>These are the message types that we'll use.  Note that these are defined to be XML <em>elements</em>, as explained above.</p></dd></dl><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></div></div>
! 				
! 				<div class="div2">
! <h3><a name="basics-interface"></a>2.4 Defining an Interface</h3><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 <em>operations</em>, 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 <em>pattern</em> that indicates the sequence in which the associated messages are to be transmitted between the parties.   For example, the <em>in-out</em> pattern (see <em>WSDL 2.0 Predefined Extensions</em> [<cite><a href="#WSDL-PART2">WSDL 2.0Adjuncts</a></cite>] section  2.2.3 <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">In-Out</a>) indicates that if the client sends a message <em>in</em> to the service, the service will either send a reply message back <em>out</em> 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 <em>pattern</em>s in <a href="#more-interfaces-meps"><b>5.4.3 Understanding Message Exchange Patterns (MEPs)</b></a></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 <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</a> 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 <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-only</a> and <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#out-only">out-only</a> patterns (see <em>WSDL 2.0 Predefined Extensions</em> [<cite><a href="#WSDL-PART2">WSDL 2.0 Adjuncts</a></cite>] section  2.2.1 <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-only">In-Only</a> and section  2.2.5 <a href="http://www.w3.og/TR/2004/WD-wsdl20-extensions-20040803/#out-only">Out-Only</a>), but that would just complicate matters for the client, because 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><div class="exampleOuter">
  					<p class="exampleHead" style="text-align: left"><a name="example-initial-interface"></a><i><span>Example 2-4. </span>GreatH Interface Definition</i></p>
  					
***************
*** 296,312 ****
    . . .
    &lt;types&gt;
!     &lt;xs:schema 
!         xmlns:xs="http://www.w3.org/2001/XMLSchema"
!         targetNamespace="http://greath.example.com/2004/schemas/resSvc"
!         xmlns="http://greath.example.com/2004/schemas/resSvc"&gt;
! 
!       &lt;xs:element name="checkAvailability" type="tCheckAvailability"/&gt;    
!         . . .
!             
!       &lt;xs:element name="checkAvailabilityResponse" type="xs:double"/&gt;    
!     
!       &lt;xs:element name="invalidDataError" type="xs:string"/&gt;    
! 
!     &lt;/xs:schema&gt;    
    &lt;/types&gt;
    
--- 300,304 ----
    . . .
    &lt;types&gt;
! 	...
    &lt;/types&gt;
    
***************
*** 413,425 ****
    
    &lt;interface  name = "reservationInterface" &gt;
! 
!     &lt;fault name = "invalidDataFault"
!             element = "ghns:invalidDataError"/&gt; 
!    
!     &lt;operation name="opCheckAvailability" 
!             pattern="http://www.w3.org/2004/03/wsdl/in-out" &gt;
!        . . .
!     &lt;/operation&gt;
! 
    &lt;/interface&gt;
  
--- 405,409 ----
    
    &lt;interface  name = "reservationInterface" &gt;
! 	...
    &lt;/interface&gt;
  
***************
*** 490,494 ****
                 address ="http://greath.example.com/2004/reservation"/&gt;
          
!   &lt;/service&gt;</pre></div>
  				</div><div class="div3">
  <h4><a name="example-initial-service-explanation"></a>2.6.1 Explanation of Example</h4><dl><dt class="label"><code>&lt;service name="reservationService"</code></dt><dd><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 <em>WSDL 2.0 Core Language</em> [<cite><a href="#WSDL-PART1">WSDL 2.0 Core Language</a></cite>] appendix C <a href="http://www.w3.org/TR/2004/WD-wsdl20-20040803/#wsdl-uri-references">URI References for WSDL constructs</a>.)</p></dd><dt class="label"><code>interface="tns:reservationInterface"&gt;</code></dt><dd><p>This specifies the name of the previously defined interface that these service endpoints will support.  </p></dd><dt class="label"><code>&lt;endpoint name="reservationEndpoint"</code></dt><dd><p>This defines an endpoint for the service, and a name for this endpoint, which must be unique within this servie.  </p></dd><dt class="label"><code>binding="tns:reservationSOAPBinding"</code></dt><dd><p>This specifies the name of the previously defined binding to be used by this endpoint.  </p></dd><dt class="label"><code>address ="http://greath.example.com/2004/reservation"/&gt;</code></dt><dd><p>This specifies the physical address at which this service can be accessed using the binding specified by the <code>binding</code>  attribute.</p></dd></dl><p>That's it!  Well, almost.  </p></div></div>
--- 474,480 ----
                 address ="http://greath.example.com/2004/reservation"/&gt;
          
!   &lt;/service&gt;
!   
! &lt;/description&gt;</pre></div>
  				</div><div class="div3">
  <h4><a name="example-initial-service-explanation"></a>2.6.1 Explanation of Example</h4><dl><dt class="label"><code>&lt;service name="reservationService"</code></dt><dd><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 <em>WSDL 2.0 Core Language</em> [<cite><a href="#WSDL-PART1">WSDL 2.0 Core Language</a></cite>] appendix C <a href="http://www.w3.org/TR/2004/WD-wsdl20-20040803/#wsdl-uri-references">URI References for WSDL constructs</a>.)</p></dd><dt class="label"><code>interface="tns:reservationInterface"&gt;</code></dt><dd><p>This specifies the name of the previously defined interface that these service endpoints will support.  </p></dd><dt class="label"><code>&lt;endpoint name="reservationEndpoint"</code></dt><dd><p>This defines an endpoint for the service, and a name for this endpoint, which must be unique within this servie.  </p></dd><dt class="label"><code>binding="tns:reservationSOAPBinding"</code></dt><dd><p>This specifies the name of the previously defined binding to be used by this endpoint.  </p></dd><dt class="label"><code>address ="http://greath.example.com/2004/reservation"/&gt;</code></dt><dd><p>This specifies the physical address at which this service can be accessed using the binding specified by the <code>binding</code>  attribute.</p></dd></dl><p>That's it!  Well, almost.  </p></div></div>
***************
*** 507,515 ****
      at http://greath.example.com/2004/reservation-documentation.html
    &lt;/documentation&gt;
- 
-   &lt;types&gt;
-     . . .
-   &lt;/types&gt;
- 
    . . .  
  &lt;/description&gt;</pre></div>
--- 493,496 ----
***************
*** 547,551 ****
  <h3><a name="wsdl-schema"></a>3.2 WSDL 2.0 Schema and Element Ordering</h3>
  
! <p>The WSDL 2.0 specification supplies a normative WSDL 2.0 schema @@ToDo: Add reference@@, defined in XML Schema [<cite><a href="#XMLSchemaP1">XML Schema: Structures</a></cite>] [<cite><a href="#XMLSchemaP2">XML Schema: Datatypes</a></cite>], which can be used as an aid in validating WSDL 2.0 documents.  Although the WSDL 2.0 schema does not indicate the required ordering of elements, the WSDL 2.0 specification (WSDL 2.0 Part 1 [<cite><a href="#WSDL-PART1">WSDL 2.0 Core Language</a></cite>] "<a href="http://www.w3.org/TR/wsdl20-primer#Description_XMLRep">XML Representation of Description Component</a>") clearly states a set of constraints about how the children elements of the <code>description</code> element should be ordered. Thus, the order of the WSDL 2.0 elements matters, in spite of what the WSDL 2.0 schema says. </p><p>The following is a pseudo-content model of <code>description</code>.</p>
  
  <div class="exampleInner"><pre>
--- 528,532 ----
  <h3><a name="wsdl-schema"></a>3.2 WSDL 2.0 Schema and Element Ordering</h3>
  
! <p>The WSDL 2.0 specification supplies a normative WSDL 2.0 schema  @@ToDo: add reference to wsdl schema when publish@@, defined in XML Schema [<cite><a href="#XMLSchemaP1">XML Schema: Structures</a></cite>] [<cite><a href="#XMLSchemaP2">XML Schema: Datatypes</a></cite>], which can be used as an aid in validating WSDL 2.0 documents.  Although the WSDL 2.0 schema does not indicate the required ordering of elements, the WSDL 2.0 specification (WSDL 2.0 Part 1 [<cite><a href="#WSDL-PART1">WSDL 2.0 Core Language</a></cite>] "<a href="http://www.w3.org/TR/wsdl20-primer#Description_XMLRep">XML Representation of Description Component</a>") clearly states a set of constraints about how the children elements of the <code>description</code> element should be ordered. Thus, the order of the WSDL 2.0 elements matters, in spite of what the WSDL 2.0 schema says. </p><p>The following is a pseudo-content model of <code>description</code>.</p>
  
  <div class="exampleInner"><pre>
***************
*** 874,882 ****
  					</li>
  				</ul></div><div class="div3">
! <h4><a name="N1089B"></a>5.4.2 Operation Message References</h4><p>An <code>operation</code> will also have <code>input</code>, <code>output</code>,<code>infault</code>, and/or <code>outfault</code> element children that specify the ordinary and fault message types to be used by that operation.  The MEP specified by the <code>pattern</code> attribute determines which of these  elements should be included, since each MEP has placeholders for the message types involved in its pattern.     </p><p>Since operations were already discussed in <a href="#basics-interface"><b>2.4 Defining an Interface</b></a>, this section will merely comment on additional capabilities that were not previously explained.</p>
  				<div class="div4">
! <h5><a name="N108B8"></a>5.4.2.1 The messageLabel Attribute</h5><p>The <code>messageLabel</code>  attribute of  the <code>input</code> and <code>output</code> elements is optional: it is not necessary to explicitly set the <code>messageLabel</code> when the MEP in use is one of the eight MEPs predefined in WSDL 2.0 Part 2 [<cite><a href="#WSDL-PART2">WSDL 2.0 Adjuncts</a></cite>] and it has only one message with a given direction. </p></div><div class="div4">
! <h5><a name="N108CC"></a>5.4.2.2 The element Attribute</h5><p>The <code>element</code>  attribute of the <code>input</code> and <code>output</code> elements is used to specify the message content schema (a/k/a payload schema) when the content model is defined using XML Schema.  As we have seen already, it can specify the QName of an element schema that was defined in the <code>types</code> section.  However, alternatively it can specify one of the following tokens: </p><dl><dt class="label"><code>#any</code></dt><dd><p>The message content is any single element.</p></dd><dt class="label"><code>#none</code></dt><dd><p>There is no message content, i.e., the message payload is empty.</p></dd></dl><p>The <code>element</code> attribute is also optional.  If it is not specified, then @@@@. <table border="1" summary="Editorial note"><tr><td width="50%" valign="top" align="left"><b>Editorial note</b></td><td width="50%" valign="top" align="right">&nbsp;</td></tr><tr><td valign="top" align="left" colspan="2">ToDo: ay what happens if the element attribute is not specified, after issue LC99 is resolved.  See http://www.w3.org/2002/ws/desc/4/lc-issues/issues.html#LC99 </td></tr></table></p></div><div class="div4">
! <h5><a name="N108F3"></a>5.4.2.3 Multiple infault or outfault Elements</h5><p>When <code>infault</code> and/or <code>outfault</code> occur multiple times within an <code>operation</code>, they define alternative fault messages. </p></div></div>
  			
  			
--- 855,863 ----
  					</li>
  				</ul></div><div class="div3">
! <h4><a name="N108A2"></a>5.4.2 Operation Message References</h4><p>An <code>operation</code> will also have <code>input</code>, <code>output</code>,<code>infault</code>, and/or <code>outfault</code> element children that specify the ordinary and fault message types to be used by that operation.  The MEP specified by the <code>pattern</code> attribute determines which of these  elements should be included, since each MEP has placeholders for the message types involved in its pattern.     </p><p>Since operations were already discussed in <a href="#basics-interface"><b>2.4 Defining an Interface</b></a>, this section will merely comment on additional capabilities that were not previously explained.</p>
  				<div class="div4">
! <h5><a name="N108BF"></a>5.4.2.1 The messageLabel Attribute</h5><p>The <code>messageLabel</code>  attribute of  the <code>input</code> and <code>output</code> elements is optional: it is not necessary to explicitly set the <code>messageLabel</code> when the MEP in use is one of the eight MEPs predefined in WSDL 2.0 Part 2 [<cite><a href="#WSDL-PART2">WSDL 2.0 Adjuncts</a></cite>] and it has only one message with a given direction. </p></div><div class="div4">
! <h5><a name="N108D3"></a>5.4.2.2 The element Attribute</h5><p>The <code>element</code>  attribute of the <code>input</code> and <code>output</code> elements is used to specify the message content schema (a/k/a payload schema) when the content model is defined using XML Schema.  As we have seen already, it can specify the QName of an element schema that was defined in the <code>types</code> section.  However, alternatively it can specify one of the following tokens: </p><dl><dt class="label"><code>#any</code></dt><dd><p>The message content is any single element.</p></dd><dt class="label"><code>#none</code></dt><dd><p>There is no message content, i.e., the message payload is empty.</p></dd></dl><p>The <code>element</code> attribute is also optional.  If it is not specified, then @@@@. <table border="1" summary="Editorial note"><tr><td width="50%" valign="top" align="left"><b>Editorial note</b></td><td width="50%" valign="top" align="right">&nbsp;</td></tr><tr><td valign="top" align="left" colspan="2">ToDo: ay what happens if the element attribute is not specified, after issue LC99 is resolved.  See http://www.w3.org/2002/ws/desc/4/lc-issues/issues.html#LC99 </td></tr></table></p></div><div class="div4">
! <h5><a name="N108FA"></a>5.4.2.3 Multiple infault or outfault Elements</h5><p>When <code>infault</code> and/or <code>outfault</code> occur multiple times within an <code>operation</code>, they define alternative fault messages. </p></div></div>
  			
  			
***************
*** 1116,1120 ****
  				</div>
  			<div class="div3">
! <h4><a name="N10AB7"></a>6.6.1 Explanation of
  			Example</h4><table border="1" summary="Editorial note: dbooth"><tr><td width="50%" valign="top" align="left"><b>Editorial note: dbooth</b></td><td width="50%" valign="top" align="right">2005-04-15</td></tr><tr><td valign="top" align="left" colspan="2">ToDo: Check this section.  I'm not sure I got it all right, particularly regarding whttp:location.  Is the first sample request URI correct? Shouldn't instance data for tCheckAvailability be in the path component?  What happens if a non-leaf element type is specified, such as tCheckAvailability?</td></tr></table><p></p><dl>
  <dt class="label"><code>type="http://www.w3.org/@@@@/@@/wsdl/http"</code></dt>
--- 1097,1101 ----
  				</div>
  			<div class="div3">
! <h4><a name="N10ABE"></a>6.6.1 Explanation of
  			Example</h4><table border="1" summary="Editorial note: dbooth"><tr><td width="50%" valign="top" align="left"><b>Editorial note: dbooth</b></td><td width="50%" valign="top" align="right">2005-04-15</td></tr><tr><td valign="top" align="left" colspan="2">ToDo: Check this section.  I'm not sure I got it all right, particularly regarding whttp:location.  Is the first sample request URI correct? Shouldn't instance data for tCheckAvailability be in the path component?  What happens if a non-leaf element type is specified, such as tCheckAvailability?</td></tr></table><p></p><dl>
  <dt class="label"><code>type="http://www.w3.org/@@@@/@@/wsdl/http"</code></dt>
***************
*** 2339,2343 ****
  				<div class="div3">
  					
! <h4><a name="N10FC7"></a>7.10.1 Schemas in Imported Documents</h4>
  					<p>
  						In this example, we consider some GreatH Hotel
--- 2320,2324 ----
  				<div class="div3">
  					
! <h4><a name="N10FCE"></a>7.10.1 Schemas in Imported Documents</h4>
  					<p>
  						In this example, we consider some GreatH Hotel
***************
*** 2546,2550 ****
  				<div class="div3">
  					
! <h4><a name="N11052"></a>7.10.2 Multiple Inline Schemas in One Document</h4>
  					<p>
  						A WSDL 2.0 document may define multiple inline
--- 2527,2531 ----
  				<div class="div3">
  					
! <h4><a name="N11059"></a>7.10.2 Multiple Inline Schemas in One Document</h4>
  					<p>
  						A WSDL 2.0 document may define multiple inline
***************
*** 2680,2684 ****
  the <code>schema</code> element. The simplest way to accomplish this is to use the <code>id</code> attribute, however XPointer can also be used.
  </p><div class="div4">
! <h5><a name="N110AF"></a>7.10.3.1 Using the id Attribute to Identify Inline
  						Schemas</h5><p>
  						<a href="#schemaIds.wsdl">Example 7-26</a>
--- 2661,2665 ----
  the <code>schema</code> element. The simplest way to accomplish this is to use the <code>id</code> attribute, however XPointer can also be used.
  </p><div class="div4">
! <h5><a name="N110B6"></a>7.10.3.1 Using the id Attribute to Identify Inline
  						Schemas</h5><p>
  						<a href="#schemaIds.wsdl">Example 7-26</a>
Received on Thursday, 28 April 2005 22:43:18 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 19:31:34 UTC