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

2002/ws/desc/wsdl20 wsdl20-primer.html,1.84,1.85 wsdl20-primer.xml,1.112,1.113

From: Kevin Liu via cvs-syncmail <cvsmail@w3.org>
Date: Wed, 06 Jul 2005 20:35:29 +0000
To: public-ws-desc-eds@w3.org
Message-Id: <E1DqGcD-0002u0-Cd@lionel-hutz.w3.org>

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

Modified Files:
	wsdl20-primer.html wsdl20-primer.xml 
Log Message:
Removed editorial notes for 
- wsdl schema url, 
- appendix E  (added references alternative schema language support notes)
- http binding extensions (incorporated DavidO suggestions)

Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.112
retrieving revision 1.113
diff -C2 -d -r1.112 -r1.113
*** wsdl20-primer.xml	6 Jul 2005 18:51:07 -0000	1.112
--- wsdl20-primer.xml	6 Jul 2005 20:35:26 -0000	1.113
***************
*** 518,528 ****
  
  <p>The WSDL 2.0 specification supplies a <xspecref href="http://www.w3.org/2005/05/wsdl">normative WSDL 2.0 schema</xspecref>, defined in <bibref ref="XMLSchemaP1"/>, which can be used as an aid in validating WSDL 2.0 documents. We say "as an aid" here because WSDL 2.0 specification <bibref ref="WSDL-PART1"/> often provides further constraints to the WSDL2.0 schema. In addition to being valid with the normative schema, a WSDL 2.0 document must also follow all the constraints defined by the WSDL2.0 specification.   
- <ednote>
- 					<name>KevinL</name>
- 					<date>20050428</date>
- 					<edtext>
- 						ToDo: update link to wsdl2.0 schema when final uri is available						
- 					</edtext>
- 				</ednote>
  </p>
  <div4 id="element-order"><head>WSDL2.0 Element Ordering</head>
--- 518,521 ----
***************
*** 690,695 ****
  <div2 id="more-types"><head>More on Message Types</head>
  		<p>The WSDL 2.0 <code>types</code> element provides a mechanism for enclosing message schemas in a WSDL 2.0 document.  Because WSDL 2.0 directly supports schemas written in XML Schema
! <bibref ref="XMLSchemaP1"/>, we will focus here on the use of XML Schema to define message types.  Schemas written in other type definition languages must be defined using a WSDL 2.0 language extension.  For examples of other schema languages, see WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> Appendix E "<xspecref href="&w3c-designation-part1;#other-schemalang">Examples of Specifications of Extension Elements for Alternative Schema Language Support. (Non-Normative)</xspecref>".  
!  <ednote><name>dbooth</name><date>2005-04-13</date><edtext>ToDo: Update the above reference to appendix E, as the WG decided to move it to a separate document.</edtext></ednote></p>
  					
  <p>There are two ways to indicate XML Schema message definitions using the <code>types</code> element. 
--- 683,687 ----
  <div2 id="more-types"><head>More on Message Types</head>
  		<p>The WSDL 2.0 <code>types</code> element provides a mechanism for enclosing message schemas in a WSDL 2.0 document.  Because WSDL 2.0 directly supports schemas written in XML Schema
! <bibref ref="XMLSchemaP1"/>, we will focus here on the use of XML Schema to define message types.  Schemas written in other type definition languages must be defined using a WSDL 2.0 language extension.  For examples of other schema languages, see the W3C notes on <bibref ref="altschemalangs"/> .  </p>
  					
  <p>There are two ways to indicate XML Schema message definitions using the <code>types</code> element. 
***************
*** 1348,1352 ****
      <endpoint name="reservationEndpoint"
        binding="tns:reservationHTTPBinding"
!       address="http://greath.example.com/2004/"/>
  
    </service>
--- 1340,1344 ----
      <endpoint name="reservationEndpoint"
        binding="tns:reservationHTTPBinding"
!       address="http://greath.example.com/2004/checkAvailability/"/>
  
    </service>
***************
*** 1355,1359 ****
  				</example>
  			<div4><head>Explanation of
! 			Example</head><ednote><name>dbooth</name><date>2005-04-15</date><edtext>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?</edtext></ednote>
  			
  			
--- 1347,1351 ----
  				</example>
  			<div4><head>Explanation of
! 			Example</head>
  			
  			
***************
*** 1375,1379 ****
  <gitem><label><code>whttp:methodDefault="GET"&gt;</code></label><def><p>The default method for operations in this interface will be HTTP GET.</p></def></gitem><gitem><label><code>whttp:location="{checkInDate}"  &gt;</code></label><def><p>The <code>whttp:location</code> attribute specifies a pattern for serializing input message instance data into the path component of the  request URI.   The default binding rules for HTTP specify that the default input
  serialization for GET is <code>application/x-www-form-urlencoded</code>.  Curly braces are used to specify the name of a schema type in the input message schema, which determines what input instance data will be inserted into the path component of the request URI.    The curly brace-enclosed name will be replaced with instance data in constructing the path component.  Remaining input instance data (not specified by <code>whttp:location</code>) will either be serialized into the query string portion of the URI or into the message body, as follows:  if a "/" is appended to a curly brace-enclosed type name, then any remaining input message instance data will be serialized into the message body. Otherwise it will be serialized into query parameters.</p><p>Thus, in this example, each of the elements in the <code>tCheckAvailability</code> type will be serialized into the query parameters. A sample resulting URI would therefore be
! <code>http://greath.example.com/2004/5-5-5?checkOutDate=6-6-5&amp;roomType=foo</code>. </p></def></gitem></glist></p>
  
  <p>Here is an alternate example that appends "/" to the type name in order to serialize the remaining instance data into the message body:</p><example id="example-bindings-http-path-subsset">
--- 1367,1371 ----
  <gitem><label><code>whttp:methodDefault="GET"&gt;</code></label><def><p>The default method for operations in this interface will be HTTP GET.</p></def></gitem><gitem><label><code>whttp:location="{checkInDate}"  &gt;</code></label><def><p>The <code>whttp:location</code> attribute specifies a pattern for serializing input message instance data into the path component of the  request URI.   The default binding rules for HTTP specify that the default input
  serialization for GET is <code>application/x-www-form-urlencoded</code>.  Curly braces are used to specify the name of a schema type in the input message schema, which determines what input instance data will be inserted into the path component of the request URI.    The curly brace-enclosed name will be replaced with instance data in constructing the path component.  Remaining input instance data (not specified by <code>whttp:location</code>) will either be serialized into the query string portion of the URI or into the message body, as follows:  if a "/" is appended to a curly brace-enclosed type name, then any remaining input message instance data will be serialized into the message body. Otherwise it will be serialized into query parameters.</p><p>Thus, in this example, each of the elements in the <code>tCheckAvailability</code> type will be serialized into the query parameters. A sample resulting URI would therefore be
! <code>http://greath.example.com/2004/checkAvailability/5-5-5?checkOutDate=6-6-5&amp;roomType=foo</code>. </p></def></gitem></glist></p>
  
  <p>Here is an alternate example that appends "/" to the type name in order to serialize the remaining instance data into the message body:</p><example id="example-bindings-http-path-subsset">
***************
*** 1388,1392 ****
  				</example><p>
  
! This would instead serialize to a request URI such as: <code>http://greath.example.com/2004/bycheckInDate/5-5-5</code>. The rest of the message content would go to the HTTP message body.</p></div4></div3>
  		<div3 id="adv-get-vs-post"><head>HTTP GET Versus POST: Which to Use?</head>
  				<p> When a binding using HTTP  is specified for an operation, the WSDL 2.0 author must decide which HTTP method is appropriate to use -- usually a choice between GET and POST.  In the  context of the Web as a whole (rather than specifically Web services), the W3C Technical Architecture Group (TAG) has addressed the question of when it is appropriate to use GET, versus when to use POST, in a finding entitled <emph>URIs, Addressability, and the use of HTTP GET and POST</emph>  (<bibref ref="TAG-whenToUseGET"/>).   From the abstract:</p><p><quote><emph>. . . designers should adopt [GET] for safe operations such as simple queries. POST is appropriate for other types of applications where a user request has the potential to change the state of the resource (or of related resources). The finding explains how to choose between HTTP GET and POST for an application taking into account architectural, security, and practical considerations.</emph></quote></p><p>Recall that the concept of a safe operation was discussed in <specref ref="more-interfaces-op-attr"/>.  (Briefly, a safe operation is one that does not cause the invoker to incur new obligations.) Although the <code>wsdlx:safe</code> attribute of an interface operation indicates that the abstract operation is safe, it does not automatically cause GET to be used at the HTTP level when the binding is specified.   The choice of GET or POST is determined at the binding level: </p>
--- 1380,1384 ----
  				</example><p>
  
! This would instead serialize to a request URI such as: <code>http://greath.example.com/2004/checkAvailability/bycheckInDate/5-5-5</code>. The rest of the message content would go to the HTTP message body.</p></div4></div3>
  		<div3 id="adv-get-vs-post"><head>HTTP GET Versus POST: Which to Use?</head>
  				<p> When a binding using HTTP  is specified for an operation, the WSDL 2.0 author must decide which HTTP method is appropriate to use -- usually a choice between GET and POST.  In the  context of the Web as a whole (rather than specifically Web services), the W3C Technical Architecture Group (TAG) has addressed the question of when it is appropriate to use GET, versus when to use POST, in a finding entitled <emph>URIs, Addressability, and the use of HTTP GET and POST</emph>  (<bibref ref="TAG-whenToUseGET"/>).   From the abstract:</p><p><quote><emph>. . . designers should adopt [GET] for safe operations such as simple queries. POST is appropriate for other types of applications where a user request has the potential to change the state of the resource (or of related resources). The finding explains how to choose between HTTP GET and POST for an application taking into account architectural, security, and practical considerations.</emph></quote></p><p>Recall that the concept of a safe operation was discussed in <specref ref="more-interfaces-op-attr"/>.  (Briefly, a safe operation is one that does not cause the invoker to incur new obligations.) Although the <code>wsdlx:safe</code> attribute of an interface operation indicates that the abstract operation is safe, it does not automatically cause GET to be used at the HTTP level when the binding is specified.   The choice of GET or POST is determined at the binding level: </p>
***************
*** 4051,4054 ****
--- 4043,4051 ----
  						<titleref>OWL Web Ontology Language Reference</titleref>, Mike Dean,Guus Schreiber, Editors. W3C Recommendation 10 February 2004 . Available at http://www.w3.org/TR/owl-ref/
  	  </bibl>
+ 
+ 	  					<bibl key="Alternative Schema Languages Support" href="http://dev.w3.org/cvsweb/~checkout~/2002/ws/desc/wsdl20/altschemalangs.html" id="altschemalangs">
+ 						<titleref>Web Services Description Language (WSDL): Alternative Schema Languages Support</titleref>, Bijan Parsia,..., Editors. W3C Notes . Available at http://dev.w3.org/cvsweb/~checkout~/2002/ws/desc/wsdl20/altschemalangs.html
+ 	  </bibl>
+ 
  				</blist>
  			</div2>

Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.84
retrieving revision 1.85
diff -C2 -d -r1.84 -r1.85
*** wsdl20-primer.html	6 Jul 2005 18:51:07 -0000	1.84
--- wsdl20-primer.html	6 Jul 2005 20:35:26 -0000	1.85
***************
*** 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 Mac OS X (vers 12 April 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 0:
! Primer</title>
[...9003 lines suppressed...]
! 	(Electronic Data Systems), Yaron Goland
! 	(BEA Systems, Inc.), &Uuml;mit Yal&ccedil;─▒nalp
! 	(Oracle Corporation), Peter Madziak
! 	(Agfa-Gevaert N. V.), Jeffrey Schlimmer
! 	(Microsoft Corporation), Hao He
! 	(The Thomson Corporation), Erik Ackerman
! 	(Lexmark), Jerry Thrasher
! 	(Lexmark), Prasad Yendluri
! 	(webMethods, Inc.), William Vambenepe
! 	(Hewlett-Packard Company), David Booth
! 	(W3C), Sanjiva Weerawarana
! 	(IBM).</p>
!   <p>The people who have contributed to <a href="http://lists.w3.org/Archives/Public/www-ws-desc/">discussions
!       on www-ws-desc@w3.org</a> are also gratefully
!       acknowledged.</p>
  </div>
! 
! 	</div>
! </body></html>
\ No newline at end of file
Received on Wednesday, 6 July 2005 20:35:33 GMT

This archive was generated by hypermail 2.2.0 + w3c-0.30 : Wednesday, 6 July 2005 20:35:33 GMT