- From: David Booth via cvs-syncmail <cvsmail@w3.org>
- Date: Sun, 17 Apr 2005 18:42:50 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv27482
Modified Files:
wsdl20-primer.xml wsdl20-primer.html
Log Message:
Finished editing/updating through sec 7.6 (MTOM).
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.52
retrieving revision 1.53
diff -C2 -d -r1.52 -r1.53
*** wsdl20-primer.xml 17 Apr 2005 16:56:59 -0000 1.52
--- wsdl20-primer.xml 17 Apr 2005 18:42:48 -0000 1.53
***************
*** 790,794 ****
! <div3><head>Operation Attributes</head><p>An <code>operation</code> has two required and two optional attributes:</p>
<ulist>
<item>
--- 790,794 ----
! <div3 id="more-interfaces-op-attr"><head>Operation Attributes</head><p>An <code>operation</code> has two required and two optional attributes:</p>
<ulist>
<item>
***************
*** 801,805 ****
</item>
<item>
! <p>An optional <att>style</att> attribute whose value is a a list of absolute URIs. Each URI identifies a certain set of rules that were used to construct the message type definitions used by the <code>operation</code>. It is an error if a particular style is indicated, but the associated rules are not followed. See <specref ref="adv-RPCstyle"/> for an example of using the <code>style</code> attribute.</p>
<ednote><edtext>ToDo: add a list of predefined style URIs here, with a sentence for each one, explaining its purpose.</edtext></ednote>
--- 801,805 ----
</item>
<item>
! <p>An optional <att>style</att> attribute whose value is a list of absolute URIs. Each URI identifies a certain set of rules that were followed in defining this <code>operation</code>. It is an error if a particular style is indicated, but the associated rules are not followed. See <specref ref="adv-RPCstyle"/> for an example of using the <code>style</code> attribute.</p>
<ednote><edtext>ToDo: add a list of predefined style URIs here, with a sentence for each one, explaining its purpose.</edtext></ednote>
***************
*** 1433,1562 ****
<div2 id="adv-MTOM"><head>MTOM Support</head>
! <ednote>
! <name>KevinL</name>
! <date>20050310</date>
! <edtext>Incoporated contribution from Jonathan. Need to check back this section for integration with rest of document.
! </edtext>
! </ednote>
<!-- =============== -->
<p>This section shows how theSOAP Message Transmission Optimization Mechanism (MTOM) <bibref ref="SOAP-MTOM"/> may be engaged in the WSDL 2.0 SOAP binding extension.</p>
! <p>We will modify the CheckAvailability operation of the GreatH Hotel Reservation Service (<specref ref="example-initial"/>) to return not only the room rate, but images of the room and the floorplan. This will involve modifying the checkAvailabilityResponse data structure to include binary data representing these two images, indicated by <code>xs:base64Binary</code> data type:</p>
<example id="example-MTOM-schema">
! <head>An example XML Schema that contains optimizable elements </head>
!
! <eg><![CDATA[
!
! <xs:element name="checkAvailabilityResponse">
!
! <xs:sequence>
!
! <xs:element name="rate" type="xs:double"/>
!
! <xs:element name="photo" type = "xmime:base64Binary" xmime:expectedContentType="image/jpeg image/png" />
!
! <xs:element name="floorplan" xmime:expectedContentType="image/svg">
!
! <xs:simpleContent>
! <xs:restriction base="xs:base64Binary">
! <xs:attribute ref="xmime:contentType" fixed="image/svg" />
! </xs:restriction>
! </xs:simpleContent>
! </xs:element>
! </xs:sequence>
! </xs:element>
]]></eg></example>
! <p>Note the use of the xmime:expectedContentType and xmime:contentType attributes to declare the expected media type of the encoded data and to allow the client to indicate the type at runtime, respectively. These attributes are defined in Describing Media Content of Binary Data in XML [ref].</p>
! <p>A Response message conforming to this schema might look like this:</p>
<example id="example-MTOM-soap-message">
! <head>An example of non-optimized soap message that contains embedded binary data </head>
<eg><![CDATA[
<soap:Envelope
-
xmlns:soap='http://www.w3.org/2003/05/soap-envelope'
-
xmlns:xmime='http://www.w3.org/@@@@/@@/xmlmime'>
<soap:Body>
-
<g:checkAvailabilityResponse
-
xmlns:g="http://greath.example.com/2004/schemas/resSvc">
<g:rate>129.95</g:rate>
-
<g:photo xmime:contentType='image/png'>/aWKKapGGyQ=</g:photo>
-
<g:floorplan xmime:contentType="image/svg">Faa7vROi2VQ=</g:floorplan>
</g:checkAvailabilityResponse>
-
</soap:Body>
! </soap:Envelope>
!
! ]]></eg></example>
! <p>While this (non-optimized) message satisfies the schema definition, a service may choose to allow or require that the binary data be sent in an optimized format using the Message Transmission and Optimization feature. The use of this feature by the SOAP binding extension is indicated as follows:</p>
<example id="example-MTOM-soap-binding">
! <head>Indicating the use of MTOM in wsdl binding</head>
<eg><![CDATA[
! <binding name="reservationSOAPBinding"
!
! interface="tns:reservationInterface"
!
! type="http://www.w3.org/2004/08/wsdl/soap12"
!
! wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP">
!
!
!
! <operation ref="tns:opCheckAvailability"
wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response">
!
!
! <input name="checkAvailability" />
!
! <output name="checkAvailabilityRespone">
!
! <feature uri="http://www.w3.org/2003/06/soap/features/http-optimization"
!
! required="true"/>
!
! </output>
!
!
!
! </operation>
!
! ...
!
! </binding>
! ]]></eg></example>
! <p>The HTTP Message Transmission Optimization feature is engaged using the <code>feature</code> element. Note that the attribute required=”true” on the feature declaration indicates that the message must be encoded using the HTTP Optimization feature. If the attribute were required=”false” (or this attribute were absent), it would indicate that the service accepts either MTOM-encoded messages, or the embedded base64Binary data directly in the Body, and the client is free to send either form of message. </p>
--- 1433,1531 ----
<div2 id="adv-MTOM"><head>MTOM Support</head>
!
<!-- =============== -->
<p>This section shows how theSOAP Message Transmission Optimization Mechanism (MTOM) <bibref ref="SOAP-MTOM"/> may be engaged in the WSDL 2.0 SOAP binding extension.</p>
! <p>We will modify the CheckAvailability operation of the GreatH Hotel Reservation Service (<specref ref="example-initial"/>) to return not only the room rate, but images of the room and the floorplan. This will involve modifying the checkAvailabilityResponse data structure to include binary data representing these two images, indicated by the <code>xs:base64Binary</code> data type. Here is an example:</p>
<example id="example-MTOM-schema">
! <head>XML Schema with Optimizable Elements </head>
! <eg><![CDATA[. . .
! <xs:element name="checkAvailabilityResponse">
! <xs:sequence>
! <xs:element name="rate" type="xs:double"/>
! <xs:element name="photo"
! type="xmime:base64Binary"
! xmime:expectedContentType="image/jpeg image/png" />
! <xs:element name="floorplan"
! xmime:expectedContentType="image/svg">
! <xs:simpleContent>
! <xs:restriction base="xs:base64Binary">
! <xs:attribute ref="xmime:contentType"
! fixed="image/svg" />
! </xs:restriction>
! </xs:simpleContent>
! </xs:element>
! </xs:sequence>
! </xs:element>
! . . .
]]></eg></example>
! <p>Note the use of the <code>xmime:expectedContentType</code> and <code>xmime:contentType</code> attributes to declare the expected media type of the encoded data and to allow the client to indicate the type at runtime, respectively. These attributes are defined in Describing Media Content of Binary Data in XML [ref].</p>
! <p>A checkAvailabilityResponse message conforming to this schema might look like this:</p>
<example id="example-MTOM-soap-message">
! <head>Non-optimized SOAP Message with Embedded Binary Data </head>
<eg><![CDATA[
<soap:Envelope
xmlns:soap='http://www.w3.org/2003/05/soap-envelope'
xmlns:xmime='http://www.w3.org/@@@@/@@/xmlmime'>
<soap:Body>
<g:checkAvailabilityResponse
xmlns:g="http://greath.example.com/2004/schemas/resSvc">
<g:rate>129.95</g:rate>
<g:photo xmime:contentType='image/png'>/aWKKapGGyQ=</g:photo>
<g:floorplan xmime:contentType="image/svg">Faa7vROi2VQ=</g:floorplan>
</g:checkAvailabilityResponse>
</soap:Body>
! </soap:Envelope>]]></eg></example>
! <p>While this (non-optimized) message satisfies the schema definition, a service may choose to allow or require that the binary data be sent in an optimized format using the Message Transmission and Optimization Mechanism (MTOM). The use of this feature by the WSDL 2.0 SOAP binding extension is indicated as follows:</p>
<example id="example-MTOM-soap-binding">
! <head>Specifying MTOM in a WSDL 2.0 Binding</head>
<eg><![CDATA[
! . . .
! <binding name="reservationSOAPBinding"
! interface="tns:reservationInterface"
! type="http://www.w3.org/2004/08/wsdl/soap12"
! wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP">
+ <operation ref="tns:opCheckAvailability"
wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response">
! <input name="checkAvailability" />
! <output name="checkAvailabilityResponse">
! <feature
! uri="http://www.w3.org/2003/06/soap/features/http-optimization"
! required="true" />
! </output>
! </operation>
! . . .
! </binding>
! . . .]]></eg></example>
! <p>The HTTP Message Transmission Optimization (MTOM) feature is engaged using the <code>feature</code> element. Note that the attribute required=”true” on the feature declaration indicates that the message must be encoded using the HTTP Optimization feature. If the attribute were required=”false” (or this attribute were absent), it would indicate that the use of MTOM is optional for this service: the service accepts either MTOM-encoded messages, or the embedded base64Binary data directly in the Body, and the client is free to send either form of message. </p>
***************
*** 1566,1584 ****
! <!-- =============== -->
- <p>This section shows how Features and Properties can be used to indicate the use of MTOM. @@ Example from GlenD: http://lists.w3.org/Archives/Public/www-ws-desc/2004May/0076.html @@</p>
! </div2>
! <div2 id="adv-security">
! <head>Security Considerations</head>
</div2>
<div2 id="adv-RPCstyle">
! <head>Operation Style and RPC</head>
! </div2>
<div2 id="adv-message-dispatch">
--- 1535,1572 ----
!
!
</div2>
+
<div2 id="adv-RPCstyle">
! <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. Operation styles are named using URIs, in order to be unambigous while still permitted new styles to be defined. WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/> defines three such operation styles; one of these is the <emph>RPC Style</emph> (<xspecref href="http://www.w3.org/2002/ws/desc/wsdl20-adjuncts#RPCStyle">RPC Style</xspecref>).</p><p>The RPC Style 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#. 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 (detailed in section "<xspecref href="http://www.w3.org/2002/ws/desc/wsdl20-adjuncts#RPCStyle">RPC Style</xspecref>"), 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. If desired, the <code>style</code> attribute can actually be set to a list of URIs, indicating that the operation simultaneously conforms to multiple styles.</p><p> detail conventions for defining </p><p>The RPC Style </p><p>An interface operation that uses the In-Out MEP (see WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/> section "<xspecref href="http://www.w3.org/2002/ws/desc/wsdl20-adjuncts#in-out">In-Out</xspecref>") can be mapped easily
! to a method signature in the target language. The method signature corresponds to an
! RPC call by following the constraints that are specified in Section
! 3.1 [1]. These rules define the relationship between XML Schema
! elements that constitute the input and ouput messages. Since the
! interface operation designates a single method signature, the
! relationship between the input and output elements is significant. In
! order to provide a meaningful signature for language bindings,
! parameters in a method signature that are inputs, outputs, or those
! that are both input and outputs as well as return value(s) in a
! signature should be easily determinable. The rules in Section 3.1.1
! determine how the content of the input and output elements map to the
! parameters. For example, a local element that occurs both as the first
! child of the input element and the output element designates an in-out
! parameter for the method signature. Elements that occur only as
! local element children of the input element are considered to
! represent input parameters of the method signature. Similarly,
! elements that occur only as local element children of the output
! element represent output parameters.</p></div2>
<div2 id="adv-message-dispatch">
Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.33
retrieving revision 1.34
diff -C2 -d -r1.33 -r1.34
*** wsdl20-primer.html 17 Apr 2005 16:56:59 -0000 1.33
--- wsdl20-primer.html 17 Apr 2005 18:42:48 -0000 1.34
***************
*** 365,375 ****
Schemas</a><br />
        7.13.1 <a
! href="#id5212666">Schemas in Imported Documents</a><br />
        7.13.2 <a
! href="#id5212969">Multiple Inline Schemas on One Document</a><br />
    7.14 <a href="#adv-schema-location">The
schemaLocation Attribute</a><br />
        7.14.1 <a
! href="#id5213277">Using the id Attribute to Identify Inline
Schemas</a><br />
    7.15 <a href="#adv-rdf-mapping">Mapping to
--- 365,375 ----
Schemas</a><br />
        7.13.1 <a
! href="#id5212651">Schemas in Imported Documents</a><br />
        7.13.2 <a
! href="#id5212955">Multiple Inline Schemas on One Document</a><br />
    7.14 <a href="#adv-schema-location">The
schemaLocation Attribute</a><br />
        7.14.1 <a
! href="#id5213262">Using the id Attribute to Identify Inline
Schemas</a><br />
    7.15 <a href="#adv-rdf-mapping">Mapping to
***************
*** 4103,4120 ****
<h3><a id="adv-MTOM" name="adv-MTOM"></a>7.6 MTOM Support</h3>
- <table border="1" summary="Editorial note: KevinL">
- <tr>
- <td align="left" valign="top" width="50%"><b>Editorial note:
- KevinL</b></td>
- <td align="right" valign="top" width="50%">20050310</td>
- </tr>
-
- <tr>
- <td colspan="2" align="left" valign="top">Incoporated contribution
- from Jonathan. Need to check back this section for integration with
- rest of document.</td>
- </tr>
- </table>
-
<p>This section shows how theSOAP Message Transmission Optimization
Mechanism (MTOM) [<cite><a href="#SOAP-MTOM">SOAP MTOM</a></cite>]
--- 4103,4106 ----
***************
*** 4126,4165 ****
and the floorplan. This will involve modifying the
checkAvailabilityResponse data structure to include binary data
! representing these two images, indicated by
! <code>xs:base64Binary</code> data type:</p>
<div class="exampleOuter">
<p style="text-align: left" class="exampleHead"><a
id="example-MTOM-schema"
! name="example-MTOM-schema"></a><i><span>Example 7-8.</span> An
! example XML Schema that contains optimizable elements</i></p>
<div class="exampleInner">
<pre>
! <xs:element name="checkAvailabilityResponse">
!
! <xs:sequence>
!
! <xs:element name="rate" type="xs:double"/>
!
! <xs:element name="photo" type = "xmime:base64Binary" xmime:expectedContentType="image/jpeg image/png" />
!
! <xs:element name="floorplan" xmime:expectedContentType="image/svg">
!
! <xs:simpleContent>
!
! <xs:restriction base="xs:base64Binary">
! <xs:attribute ref="xmime:contentType" fixed="image/svg" />
! </xs:restriction>
! </xs:simpleContent>
! </xs:element>
! </xs:sequence>
! </xs:element>
</pre>
--- 4112,4151 ----
and the floorplan. This will involve modifying the
checkAvailabilityResponse data structure to include binary data
! representing these two images, indicated by the
! <code>xs:base64Binary</code> data type. Here is an example:</p>
<div class="exampleOuter">
<p style="text-align: left" class="exampleHead"><a
id="example-MTOM-schema"
! name="example-MTOM-schema"></a><i><span>Example 7-8.</span> XML
! Schema with Optimizable Elements</i></p>
<div class="exampleInner">
<pre>
! . . .
! <xs:element name="checkAvailabilityResponse">
! <xs:sequence>
! <xs:element name="rate" type="xs:double"/>
! <xs:element name="photo"
! type="xmime:base64Binary"
! xmime:expectedContentType="image/jpeg image/png" />
! <xs:element name="floorplan"
! xmime:expectedContentType="image/svg">
! <xs:simpleContent>
! <xs:restriction base="xs:base64Binary">
! <xs:attribute ref="xmime:contentType"
! fixed="image/svg" />
! </xs:restriction>
! </xs:simpleContent>
! </xs:element>
! </xs:sequence>
! </xs:element>
! . . .
</pre>
***************
*** 4167,4178 ****
</div>
! <p>Note the use of the xmime:expectedContentType and
! xmime:contentType attributes to declare the expected media type of
! the encoded data and to allow the client to indicate the type at
! runtime, respectively. These attributes are defined in Describing
! Media Content of Binary Data in XML [ref].</p>
! <p>A Response message conforming to this schema might look like
! this:</p>
<div class="exampleOuter">
--- 4153,4164 ----
</div>
! <p>Note the use of the <code>xmime:expectedContentType</code> and
! <code>xmime:contentType</code> attributes to declare the expected
! media type of the encoded data and to allow the client to indicate
! the type at runtime, respectively. These attributes are defined in
! Describing Media Content of Binary Data in XML [ref].</p>
! <p>A checkAvailabilityResponse message conforming to this schema
! might look like this:</p>
<div class="exampleOuter">
***************
*** 4180,4212 ****
id="example-MTOM-soap-message"
name="example-MTOM-soap-message"></a><i><span>Example 7-9.</span>
! An example of non-optimized soap message that contains embedded
! binary data</i></p>
<div class="exampleInner">
<pre>
<soap:Envelope
-
xmlns:soap='http://www.w3.org/2003/05/soap-envelope'
-
xmlns:xmime='http://www.w3.org/@@@@/@@/xmlmime'>
<soap:Body>
-
<g:checkAvailabilityResponse
-
xmlns:g="http://greath.example.com/2004/schemas/resSvc">
<g:rate>129.95</g:rate>
-
<g:photo xmime:contentType='image/png'>/aWKKapGGyQ=</g:photo>
-
<g:floorplan xmime:contentType="image/svg">Faa7vROi2VQ=</g:floorplan>
</g:checkAvailabilityResponse>
-
</soap:Body>
</soap:Envelope>
-
</pre>
</div>
--- 4166,4189 ----
id="example-MTOM-soap-message"
name="example-MTOM-soap-message"></a><i><span>Example 7-9.</span>
! Non-optimized SOAP Message with Embedded Binary Data</i></p>
<div class="exampleInner">
<pre>
<soap:Envelope
xmlns:soap='http://www.w3.org/2003/05/soap-envelope'
xmlns:xmime='http://www.w3.org/@@@@/@@/xmlmime'>
<soap:Body>
<g:checkAvailabilityResponse
xmlns:g="http://greath.example.com/2004/schemas/resSvc">
<g:rate>129.95</g:rate>
<g:photo xmime:contentType='image/png'>/aWKKapGGyQ=</g:photo>
<g:floorplan xmime:contentType="image/svg">Faa7vROi2VQ=</g:floorplan>
</g:checkAvailabilityResponse>
</soap:Body>
</soap:Envelope>
</pre>
</div>
***************
*** 4216,4221 ****
definition, a service may choose to allow or require that the
binary data be sent in an optimized format using the Message
! Transmission and Optimization feature. The use of this feature by
! the SOAP binding extension is indicated as follows:</p>
<div class="exampleOuter">
--- 4193,4199 ----
definition, a service may choose to allow or require that the
binary data be sent in an optimized format using the Message
! Transmission and Optimization Mechanism (MTOM). The use of this
! feature by the WSDL 2.0 SOAP binding extension is indicated as
! follows:</p>
<div class="exampleOuter">
***************
*** 4223,4265 ****
id="example-MTOM-soap-binding"
name="example-MTOM-soap-binding"></a><i><span>Example 7-10.</span>
! Indicating the use of MTOM in wsdl binding</i></p>
<div class="exampleInner">
<pre>
! <binding name="reservationSOAPBinding"
!
! interface="tns:reservationInterface"
!
! type="http://www.w3.org/2004/08/wsdl/soap12"
!
! wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP">
!
!
!
! <operation ref="tns:opCheckAvailability"
wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response">
!
!
! <input name="checkAvailability" />
!
! <output name="checkAvailabilityRespone">
!
! <feature uri="http://www.w3.org/2003/06/soap/features/http-optimization"
!
! required="true"/>
!
! </output>
!
!
!
! </operation>
!
! ...
!
! </binding>
</pre>
</div>
--- 4201,4229 ----
id="example-MTOM-soap-binding"
name="example-MTOM-soap-binding"></a><i><span>Example 7-10.</span>
! Specifying MTOM in a WSDL 2.0 Binding</i></p>
<div class="exampleInner">
<pre>
! . . .
! <binding name="reservationSOAPBinding"
! interface="tns:reservationInterface"
! type="http://www.w3.org/2004/08/wsdl/soap12"
! wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP">
+ <operation ref="tns:opCheckAvailability"
wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response">
! <input name="checkAvailability" />
! <output name="checkAvailabilityResponse">
! <feature
! uri="http://www.w3.org/2003/06/soap/features/http-optimization"
! required="true" />
! </output>
! </operation>
! . . .
! </binding>
! . . .
</pre>
</div>
Received on Sunday, 17 April 2005 18:42:51 UTC